Legal Information

Microsoft Exchange Server Programmer's Reference

Information in this document is subject to change without notice. This document is provided for informational purposes only and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Microsoft.

(c) 1996-1998 Microsoft Corporation. All rights reserved.

Microsoft, Microsoft Press, MS, MS-DOS, Visual Basic, Visual C++, Windows, Win32, Win32s, Windows NT, and BackOffice are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Macintosh is a registered trademark of Apple Computer, Inc.

Intel is a registered trademark of Intel Corporation.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Using the Microsoft Exchange Server Programmer's Reference

Using the Microsoft Exchange Server Programmer’s Reference

The Microsoft Exchange Server Programmer's Reference explains the concepts of writing applications for Microsoft® Exchange Server and describes the development tools included in the Microsoft Exchange Server Software Development Kit (SDK). These tools include code libraries, header files, sample applications, and sample code. Using this SDK, you can:

  • Develop stand-alone client applications and server applications for Microsoft Exchange Server.
  • Develop Administrator program extensions for Microsoft Exchange Server.
  • Use the sample applications to extend Microsoft Exchange Server client-server messaging and groupware.
  • Use the sample applications to build client applications and server applications customized for your environment.

You can also develop client extensions for Microsoft Exchange Server. For more information, see Client Extension Development Options and the Microsoft Exchange Client Extensions Programmer's Reference in the Messaging Application Programming Interface (MAPI) Programmer's Reference.


Using the Documentation

The Microsoft Exchange Server Programmer’s Reference fully describes the programming elements of Microsoft Exchange Server. It is the primary source for specific information about writing Microsoft Exchange Server applications.

As seen in the Contents pane, the Microsoft Exchange Server Programmer’s Reference is organized as follows:

  • Quick Start Procedures
  • Guide
  • Reference
  • Appendixes
  • Glossary

Quick Start Procedures

Topics in this section describe tasks commonly performed using the Microsoft Exchange Server SDK. They include design tasks, implementation tasks, and references to sample source code. Rather than providing complete in-depth information, these procedures contain links to descriptions of actual implementation details.

Guide

This section begins with a discussion of the key concepts and architecture of Microsoft Exchange Server. It continues with topics such as designing an application, setting up your development environment, debugging applications, extending the Microsoft Exchange Server Administrator program, and writing a setup program for an application, as well as how to build, run, and use the Microsoft Exchange Server sample applications.

Reference

This section consists of alphabetic listings of Microsoft Exchange Server programming elements, including objects, interfaces, functions, properties, and structures. Where appropriate, the reference pages include syntax, parameters and return values for each element.

Appendixes

This section includes information on file formats used for various aspects of Microsoft Exchange Server development or configuration.

Glossary

This section provides definitions for commonly used Microsoft Exchange Server terms and cross-references to related topics in the Guide and Reference.

For successful application development, the Microsoft Exchange Server Programmer’s Reference should be used in conjunction with the MAPI Programmer’s Reference. For other useful sources of information, see Finding Other Documentation.


Intended Audience

To develop applications for the Microsoft Exchange Server environment, your background should include:

  • Proficiency with C or C++ programming in the Windows environment and the Microsoft® Windows NT® Server network operating system.
  • Familiarity with basic features and capabilities of Microsoft Exchange Server and the Microsoft Exchange Client. Reviewing the Microsoft Exchange Server Administrator's Guide, the Microsoft Exchange Server Concepts and Planning Guide, and the Microsoft Exchange Server Application Designer's Guide is highly recommended.
  • Familiarity with MAPI.
  • Familiarity with network environments.


Hardware Requirements

The following hardware is recommended for Microsoft Exchange Server application development:

  • Intel 80486/25 or higher; Intel Pentium processor; RISC-based microprocessors such as MIPS R4000 and Digital Alpha AXP; PowerPC
  • Super VGA (800 x 600) 256-color display (recommended)
  • 50 MB of disk space (recommended)
  • CD-ROM drive
  • 32-MB RAM or more (recommended)
  • Network adapter card

In addition to a computer for application development, many developers use one or more extra computers to test their applications under varying memory and display configurations. Although extra computers are not required, they are recommended.


Software Requirements

To design applications for Microsoft Exchange Server, you need the following software installed on your system:

  • Microsoft Windows NT version 3.51 or above, with Service Pack 4.
  • Microsoft Exchange Server must be running on the domain.
  • Microsoft Platform SDK.
  • Microsoft Visual C++ version 4.0 is required. Earlier versions are not supported.
  • Sample applications may require the Administrator program to be running on the development computer. You may also need to install Microsoft Exchange Server and Microsoft Exchange Client.


Document Conventions

The Microsoft Exchange Server Programmer’s Reference uses the typographical conventions shown in the following table.

Convention | Description
monospaced text
 Examples and program code appear in a nonproportional typeface.
Bold text | Literal expressions that must be typed exactly as shown, such as function names, structure names, and keywords, appear in this bold typeface.
italic text | Italic text indicates a new or unfamiliar term, or an reference to a source outside this manual.
<Italic text> | Italic text surrounded by brackets indicates expressions, such as parameters, where you replace the text and the brackets with the actual value.
( ) In syntax statements, parentheses enclose one or more parameters that you pass to a function.
[ ] Brackets enclose optional syntax items. Type only
the syntax within the brackets, not the brackets themselves.


Finding What You Need

The Microsoft Exchange Server Programmer’s Reference is published in electronic format. The following sections explain how to use the powerful search and navigation tools.


Finding Reference Elements

You can use two different methods to find reference topics for Microsoft Exchange Server objects, structures, functions, interfaces, and properties:

  • In the Contents pane, open the appropriate Reference section and browse the alphabetic list.
  • On the toolbar, click the [image] button. In the list box that appears, type the name of the programming element you want to see, or scroll through the list and select a keyword. As you type, the list automatically scrolls to the word that most closely matches the text you are typing.


Viewing Source Code

To see the source code of a sample application or library included with Microsoft Exchange Server (including header files, when available), open the Code Samples section in the Contents pane. Then open the book representing an application or library and display the topic you want to view by double-clicking the name or icon of a source file.


Finding Other Documentation

The following information about Microsoft Exchange Server is available in Books Online, a Help file you obtain when installing Microsoft Exchange Server:

Microsoft Exchange Server: Getting Started

Microsoft Exchange Server Concepts and Planning Guide

Microsoft Exchange Server Administrator’s Guide

Microsoft Exchange Server Application Designer’s Guide

For information about MAPI programming:

Introduction to MAPI Programming (part of the Microsoft Platform SDK)

Inside MAPI, by Irving de la Cruz and Les Thaler (Microsoft Press, Redmond, WA)

For more information about programming gateways:

Gateway Programmer’s Reference

For information about the Microsoft Windows programming environment:

Microsoft Platform SDK

Programming Windows 95, by Charles Petzold (Microsoft Press, Redmond, WA)

For information about Microsoft Windows NT Server programming:

Microsoft Platform SDK

Microsoft Windows NT Server Resource Kit


Quick Start Procedures

Topics in the Quick Start Procedures folder examine tasks commonly performed using the Microsoft Exchange Server SDK. Each topic is divided into three sections: design tasks, implementation tasks, and references to sample source code.

These procedures are not intended to supply the actual implementation details. Instead, they provide a high-level overview of design decisions you will need to make and refer you to the necessary topics.

The procedures in this section are divided into two categories: server applications and client applications.

Following the procedures is a reference list of programming tasks covered in the Microsoft Exchange Server Programmer's Guide.


Quick Start Procedures: Server Applications

This section covers the following procedures:

  • Quick Start: Creating a Server Application

    Presents the basics of creating a gateway, a mailbox agent, or an add-in application.

  • Quick Start: Creating a Profile through MAPI

    Examines how to tailor profiles created to work with Microsoft Exchange Server.

  • Quick Start: Designing a Gateway

    Examines the most important issues to consider when designing a gateway.

  • Quick Start: Creating a Directory Synchronization Agent

    Discusses how to customize the DIRSYNC sample application.

  • Quick Start: Replicating Data from an External Database (such as SQL)

    Describes both the replication of information store data (such as transactions or Help Desk reports) and data intended for the Microsoft Exchange Server directory.


Creating a Server Application

This quick start procedure explains the set of tasks necessary to create a server application that will run with Microsoft Exchange Server. Server applications can be gateways, mailbox agents, or add-in applications.

All server application that run with Microsoft Exchange Server are programmed in C or C++, using Microsoft Visual C++. For more information, see Server Application Development Options.

For more information on developing server applications, see

  • Building a Server Application
  • Example: Building a Server Application.

Design Tasks

  1. Determine the role of the application. See Server Applications, Designing a Gateway, and About Mailbox Agents for more information.
  2. Decide how the application will be run and controlled. Will it run as a service of Windows NT Server? Will it have a user interface? Do you want it to be maintained through the Microsoft Exchange Server Administrator program?
  3. Decide whether to code the application from scratch or begin with an existing Microsoft Exchange Server sample application. For example, if you intend to develop a directory synchronization agent, you can start with the DIRSYNC sample application . For more information, see Creating a Directory Synchronization Agent.
  4. Decide whether you need to supply your customers with an installation program for the application. For information, see Setup Programs.

Implementation Tasks

If this is to be a service of Windows NT Server, see Installing an Application as a Service.

About Sample Source Code

The Microsoft Exchange Server SDK includes the source code (and compiled versions) of several sample applications written in C or C++. You can compile and run them in their present form, or change the source code to create new applications that meet your organization's specific needs.

Two particularly robust and helpful sample applications are:

Sample Mailbox Agent SMBAGENT, the sample mailbox agent performs the functions of a list server.

Sample Gateway For information about building and running the sample gateway, see Sample Gateway and Applications. For complete gateway development information, see the Gateway Programmer's Reference.


Creating a Profile through MAPI

This quick start procedure explains how to tailor profiles created to work with Microsoft Exchange Server. It is based on information about creating and configuring MAPI profiles in the Microsoft Exchange Client Extensions Programmer's Reference.

Design Tasks

In addition to the design tasks described in Creating and Configuring a Profile in the MAPI Programmer's Reference, you need to configure your new profile to be able to communicate with Microsoft Exchange Server. To do this, you need to know the name of the Home-Server and the mailbox name of your application. You also need to know whether the application for which the profile is being created will run as a service of Windows NT.

Implementation Tasks

Follow the steps in Creating and Configuring a Profile in the MAPI Programmer's Reference until you reach the step in which the MAPI IMsgServiceAdmin::ConfigureMsgService method is called. In this function call, specify the following information in the lpProps parameter. This parameter is a pointer to an SPropValue structure containing the values of the properties to display to the user in the property sheet.

  • Home Server of the application's mailbox. Use the property tag PR_PROFILE_HOME_SERVER. This property is defined in EDKMDB.H.
  • Name of the application's mailbox, using the property tag PR_PROFILE_MAILBOX. This property is defined in EDKMDB.H.
  • If the application is to run as a service, set the profile property PR_CONVERSION_PROHIBITED (in MAPITAGS.H) to TRUE. Doing so keeps MAPI from displaying dialog boxes — in particular the Enter Password dialog box — at times when they cannot be responded to, such as when your application must run unattended. (Windows NT services, for example, are an important class of unattended applications.)

After this, finish the remaining steps in Creating and Configuring a Profile.

About Sample Source Code

None available at this time.


Designing a Gateway

This quick start procedure examines the issues involved when designing a gateway. For complete gateway information, see the Gateway Programmer's Reference.

Design Tasks

  1. Determine the type of address mapping the gateway will need to perform. In other words, for incoming messages, what kind of foreign-system addresses will be mapped to (and for outgoing messages, from) the native EX address type of Microsoft Exchange Server. At this stage, the gateway may also need to generate nondelivery reports (NDR) if the destination address on an incoming message matches no valid recipient in the directory, or if the destination address on an outgoing messages contains no valid proxy address for an external recipient.
  2. Determine what message translation tasks are needed. First, this means knowing what types of messages (IPM, IPN, NDR, DR) will need to be translated. Second, how are the attributes on incoming messages mapped to MAPI properites? For example, incoming messages in SMTP format contain certain header fields; you would need to determine what MAPI properties to store them in. The gateway may need to generate an NDR if message translation cannot be performed, or performed incompletely.
  3. Decide whether this gateway will used for backboning Microsoft Exchange Server messages. If so, will the gateway need to preserve rich text? Will it use TNEF encapsulation? For more information on TNEF, see the MAPI Programmer's Reference.
  4. Design a strategy to have the gateway preserve trace information. Trace information is necessary so that message looping can be stopped. For more information, see Gateway Trace Information.
  5. As with all server applications, design the gateway to perform efficiently. For more information, see Application Performance.
  6. Decide on a threading model for the gateway. For more information, see Using MAPI in Multithreaded Applications.

About Sample Source Code

See Building the Sample Gateway and Sample Mailbox Agent and Sample Gateway and Applications. Also see the sample code in the section called GWSAMPLE.


Creating a Directory Synchronization Agent

This quick start procedure discusses how to design and implement a directory synchronization agent for use with the Microsoft Exchange Server directory.

This procedure uses code from the DIRSYNC sample application, which demonstrates how to transfer mailboxes and custom recipient information between foreign systems and a container on Microsoft Exchange Server. In its current form, the DIRSYNC sample application also shows how to use the directory access functions to build a transfer agent.

Communication with the foreign system is the functionality you will add to the existing DIRSYNC sample application. Depending on the tasks it will perform, your directory synchronization agent will need to export data and format it as required by DIRSYNC, or read the data exported by DIRSYNC and format it correctly for import into the foreign system.

Design Tasks

  1. Determine what foreign system will be the source or recipient of directory data.
  2. Decide whether your directory synchronization agent will be used to import from the foreign system into Microsoft Exchange Server, export from Microsoft Exchange Server to the foreign system, or transfer data in both directions.
  3. Decide whether your directory synchronization agent will be run upon demand or on a configurable schedule. DIRSYNC currently is a command-line application, so you could write a batch procedure to make it run periodically.
  4. Decide whether to make your directory synchronization agent run as a service of Windows NT Server. One purpose for this is to make the agent controllable through the Windows NT service control manager.
  5. Choose a user interface. This agent you build starting with DIRSYNC can remain a command-line application, or you can incorporate DIRSYNC code into a Windows program.

Implementation Tasks

You can use the code in DSYNCOMM.C as the basis for parts of your directory synchronization agent. Export and import functionality can reside in one program or be divided into two agents, as described here.

An agent that imports data from a foreign system consists of:

  • A module that reads data from the foreign system. This module then transfers data in one of two ways: see the sections Transferring Data Using Files and Transferring Data Using Structures. These sections refer to this export functionality (which you will need to write from scratch) as the Dirsync Agent.
  • A module that reads the exported data and writes it to the Microsoft Exchange Server directory. For this, you can use the DSYNCOMM import functions (see Functions of DSYNCOMM in the About Sample Source Code section).

An agent that exports data to a foreign system consists of:

  • A module that reads from the Microsoft Exchange Server directory. This module then transfers data in one of two ways: see the sections Transferring Data Using Files and Transferring Data Using Structures. For this, you can use the DSYNCOMM export functions (see Functions of DSYNCOMM in the About Sample Source Code section).
  • A module that reads the exported data and writes it to the foreign system. You will need to write this functionality from scratch.

Transferring Data Using Files

The export and import functions of DSYNCOMM write to and read from a file on the disk in the required DIRSYNC format. The agent you write that communicates with the foreign system must interpret this format when reading data exported from Microsoft Exchange Server, and convert data into this format after exporting it from the foreign system.

The following illustration shows this design strategy (with focus on data import), in which two separate processes run concurrently. You write the component labeled Dirsync Agent, which extracts data from the foreign system's directory system (or other database) and writes it to a file on disk in DIRSYNC format. Then, DIRSYNC calls DSYNCOMM functions to read data from this file and import it into the Microsoft Exchange Server directory.

Data Import Using a File

The process is similar for data export, but carried out in reverse. DSYNCOMM functions are used to export directory data into a file. The Dirsync Agent reformats that data as required by the foreign system and writes it into the foreign system's database.

Transferring Data Using Structures

Using structures makes disk access unnecessary and enables directory synchronization with only one running process. You use the functions in DSYNCOMM.C to communicate with the directory service of Microsoft Exchange Server, but you transfer directory data using structures instead of a file.

You will need to write your own functions to read from and write to the foreign system. In the following illustration, this functionality is represented by the component labeled Dirsync Agent, whose code is linked to that of DIRSYNC. The Dirsync Agent temporarily stores exported data in memory as structures of the type DAPI_ENTRY. This data is then imported into the Microsoft Exchange Server directory with the DSYNCOMM import functions. This design is shown (with focus on data import) in the following illustration.

Data Import Using Structures

The process is similar for data export, but carried out in reverse. The DSYNCOMM functions export directory data into structures. The functions of the Dirsync Agent read that data, reformat it into the form required by the foreign system, and write it into the foreign system.

About Sample Source Code

The DIRSYNC sample application contains code showing directory synchronization. Its two modules are compiled from the DIRSYNC.C and DSYNCOMM.C files:

  • DIRSYNC This file contains sample code showing directory synchronization using directory access functions. It implements both the inbound and outbound direction. That is, it can import from an external mail system or other software system into the Microsoft Exchange Server directory and exporting from the Microsoft Exchange Server directory to an external mail system or other software system. It compiles to an executable file that is run from the command line.
  • DSYNCOMM The functions in this file communicate with the foreign system. These routines perform directory synchronization by reading and writing to a file in a format that can be used for directory exchange. They were designed so that developers can easily replace them with their own functions. For example, they could be rewritten to communicate directly with a foreign mail system's messaging interface, or to make read/write calls to a database. The functions in this file are called by the code in DIRSYNC.C.

Functions of DSYNCOMM

The DSYNCOMM.C file contains functions that are called by the code in DIRSYNC.C. The DSYNCOMM functions communicate with the foreign system by reading from and writing to a file in a specific format. These functions were designed so that developers can replace them with their own functions. For example, they could be rewritten to make database read/write calls.

DSYNCOMM uses three primary functions for importing data.

DSYNCOMM Export Functions

Function | Description
HrOpenExport | Performs all necessary initialization before exporting records for directory synchronization.
HrWriteExport | Exports a single record for directory synchronization. It is called repeatedly: once for each record to be exported.
HrCloseExport | Performs all necessary cleanup after exporting records for directory synchronization.

DSYNCOMM uses three primary functions for exporting data.

DSYNCOMM Import Functions

Function | Description
HrOpenImport | Performs all necessary initialization before importing records for directory synchronization.
HrReadImport | Imports a single record for directory synchronization. It is called repeatedly: once for each record to be imported. When there are no more records to import, HrReadImport should return EDK_E_END_OF_FILE.
HrCloseImport | Performs all necessary cleanup after importing records for directory synchronization.


Replicating Data from an External Database

You can use MAPI or Incremental Change Synchronization (ICS) as a basis for replicating data into a Microsoft Exchange Server information store from an external database. In either case, you will also use the appropriate database query language to read data from the external database.

This procedure does not address the possibility of replicating data from a Microsoft Exchange Server information store into an external database.

Design Tasks

  1. Decide whether to use ICS or MAPI. ICS applications are more complex to build, but are more efficient and can offer built-in conflict resolution.
  2. If you are designing a new database, consider structuring it so that its elements correspond to distinct elements in the destination Microsoft Exchange Server information store. Each database record will correspond to one message, and each field in a record will correspond to one property in the corresponding message.
  3. Map the information store structure to the database structure. For example, a table in your database may become a public folder called Expense Reports. Map message properties to database fields; individual expense reports (records in the database) become messages in the Expense Reports public folder. Finally, the properties on individual messages map to fields within database records.
  4. Identify each database record unambiguously. You can use the PR_SOURCE_KEY property for this purpose (as each database record's primary key) because this property stays with an object throughout its existence.
  5. If you plan to use ICS, you must support several other properties.

    For folders: PR_SOURCE_KEY, PR_PARENT_SOURCE_KEY, PR_DISPLAY_NAME, PR_CHANGE_KEY, and PR_PREDECESSOR_CHANGE_LIST.

    For messages: PR_SOURCE_KEY, PR_CHANGE_KEY and PR_PREDECESSOR_CHANGE_LIST.

  6. Because in most cases messages will be stored in public folders, you need to decide whether to make folders read-only. Doing so simplifies your design by avoiding the data loss or conflicts that are caused when data is replicated from the database into messages that users have changed.
  7. Decide which database information will be displayed to users, and if the public folder is read/write, which information users will be permitted to change.

Implementation Tasks

  1. Using the appropriate database query language, implement an application to read changed records from the database. If you are using ICS, implement the ICS synchronizer interface.
  2. Write the code to transfer the data according to your mapping in step 3 of Design Tasks. If you are using ICS, implement an agent that regulates the transfer of data from your synchronizer to the Microsoft Exchange Server ICS collector.
  3. Build a custom form that lets users access the data in the public folder. The form may contain named properties (see the MAPI Programmer's Reference) for each of its fields. These named properties will be specific to the form's message class. This form displays the fields you chose to display in step 7 of Design Tasks. You can also program this or another form to display any fields used for user input, if the public folder is read/write.
  4. Set up the public folder. Although you cannot make a message read-only, you can set a folder to be read-only. (See step 6 of Design Tasks.) Define one or more views on the public folder.

About Sample Source Code

None available at this time.


Quick Start Procedures: Client Applications

This section covers the following procedures:

  • Quick Start: Creating Microsoft Exchange Client Extensions
  • Quick Start: The Basics of a C++ Form

See the following topics for general information on developing client applications:

  • Client Application Development Options
  • Building a Client Application.


Creating Microsoft Exchange Client Extensions

Microsoft Exchange Client Extensions are created using various interfaces (such as IExchExt) provided by Microsoft Exchange Server. For more information about extending the Microsoft Exchange Client, see the Microsoft Exchange Client Extensions Programmer's Reference.

Design Tasks

For information on designing client extensions, see Client Extension Development Options.

Implementation Tasks

For information on this topic, see the Microsoft Exchange Client Extensions Programmer's Reference.


The Basics of a C++ Form

This quick start procedure describes how to create a form using MAPI and Microsoft Visual C++. Forms developed with these tools typically perform better than those developed using Visual Basic because you can use callback functions, and you have read/write access to the MAPI directory. You can write 16-bit or 32-bit code, and there is client integration.

You can also use the Microsoft Exchange Forms Designer to create forms. For more information, see the Microsoft Exchange Server Application Designer's Guide.


Programming Tasks

This section provides a reference list of programming tasks covered in the Microsoft Exchange Server Programmer’s Guide. Tasks are arranged by general programming area. Click a topic to view its complete task description.

Improving Application Performance

Using the Performance Monitor

Checking Disk I/O with FERNEL32

Checking Network I/O

Profiling Your Application’s Performance

Using MAPI Call Traces

Building Applications

Installing a Typical Development Platform

Installing the Microsoft Exchange Server SDK

Setting Environment Variables

Debugging Applications

Connecting the Debugger to a Running Service

Using a Debug Version of MAPI

Using the Message Store Viewer

Working with Objects in the Microsoft Exchange Server Directory

Adding an Application Object

Adding an Object to the Directory

Finding an Object in the Directory

Opening an Object in the Directory

Importing and Manipulating Objects

Using MAPI with Directory Objects

Finding the Global Address List

Working with Microsoft Exchange Server Information Stores

Tasks Involving Information Stores

Opening an Information Store

Opening a Public Information Store

Opening a Private Information Store

Locating an Information Store

Determining the Type of Information Store

Tasks Involving Folders

Creating a Folder

Opening Special Folders

Opening the Inbox

Opening an Existing Private or Personal Folder

Opening an Existing Public Folder

Opening the Favorites Folder

Adding a Public Folder to Favorites

Deleting a Public Folder from Favorites

Reading ACLs

Modifying ACLs

Adding a New ACL Member

Creating a Rule

Reading Rule Contents

Modifying Rules

Using OLE Documents

Reading Messages in a Folder

Tasks Involving Mailboxes

Logging On to Mailboxes

Running an Application as a Privileged Service

Logging On to a Mailbox as a Privileged Service

Logging On to a Mailbox Using the IExchangeManageStore Interface

Tasks Involving Messages

Creating a Message

Creating and Posting a Message

Adding Custom Properties to a Message

Sending a Message

Working with Text in Rich Text Format

Tasks Involving Properties

Saving ANSI Text as a Message Property in RTF

Saving RTF Text as a Message Property in RTF

Retrieving ANSI Text from a Message Property in RTF

Tasks Involving ACLs

Reading ACLs

Modifying ACLs

Adding a New ACL Member

Tasks Involving Rules

Creating a Rule

Reading Rule Contents

Modifying Rules

Tasks Involving Backup and Restore

Backing Up Directory or Information-Store Data

Restoring Directory or Information-Store Data

Working with Forms

Installing Forms into the Organization Forms Library

Extending the Microsoft Exchange Server Administrator Program

Storing and Accessing Configuration Information

Designing Property Pages

Creating an Administrator Extension DLL

Initializing the Administrator Extension DLL

Inhibiting Standard Property Pages

Completing the Administrator Extension DLL

Modifying Extension Data

Creating Online Help

Creating Setup Programs

Creating a Complete Setup Program

Installing an Application as a Service

Installing an Admin-Extension Object

Installing Performance Monitoring

Installing Applications with Server and Client Components

Removing a Server Application

Running Sample Applications

ACLEDIT: Modifying an ACL

ADDRINST: Installing an Addr-Type Object

BACKTEST: Creating Backup Files

CFGCODE: Generating a Packed Property Structure

DIRSYNC: Importing and Exporting Mailboxes

DSEXPORT: Exporting Directory Objects

DSIMPORT: Importing Directory Objects

EXTDATVW: Viewing and Editing Extension Data

FIMPORT: Importing Folder Information

INSTFORM: Installing a Sample Form

MBINST: Installing a Mailbox Agent

MBLSAMPL: Accessing Mailboxes

MBXSERV: Viewing Messages in a Mailbox

POPPST: Creating a Customized Information Store

PROFINST: Installing a MAPI Profile

RPTDRIV: Monitoring Message Delivery

CRARUN: Creating a Custom Rule Action

RULEEDIT: Manipulating Rules

SERVINST: Installing a Service

SMBAGENT: Creating a Sample Mailbox Agent

TOOLFORM: Creating a C or C++ Form

TRACK: Tracking and Auditing Messages


Overview

Microsoft® Exchange Server is a client-server messaging and workgroup system that offers a transparent connection to many different communications systems. It provides users with an innovative electronic mail system, individual and group scheduling, online forms, and workflow automation tools. It provides you, the developer, with a platform on which to build custom information-sharing and messaging-service applications.

Microsoft Exchange Server’s development environment includes the following features:

  • Transparent connection to existing networks and mail servers Allows you to develop a single application that can be used across several platforms without writing or installing any new network software.
  • Programmer’s interface with Microsoft® Windows NT® Server network operating system and Microsoft Office Allows you to extend features that can be included in your applications.
  • Transparent interface with common add-in applications Provides options for extending the feature set you can build into your applications.
  • Built-in security features Includes automatic encryption of messages and information stored in folders, support for digital signatures, and support for passwords and access control lists for files and directories.

You can embed features of the following tools into Microsoft Exchange Server applications that you design:

  • Microsoft Exchange Server Administrator’s Program Allows you to extend and automate your applications using special functions and extension DLLs.
  • Code Samples An extensive set of code samples can be installed to add additional features to your system or can be modified to produce custom applications.
  • Microsoft Schedule+ Provides calendar, group scheduling, contact management, and other tools you can use to extend your application.
  • Microsoft Exchange Server Forms Designer A visual nonprogramming design tool that can be used to embed a form into an application, or to build a server application based on a form.


Microsoft Exchange Server as a Development Platform

Although Microsoft Exchange Server applications can have almost any structure, they generally fall into three categories:

  • Client application Uses the services of a server running Microsoft Exchange Server, but resides exclusively at the user’s location.
  • Server application Interacts with services such as the information store and the directory to provide services to users, but is not associated with any particular user.
  • Combined client and server application Includes a client component associated with one or more users and a server component that is a service.


About Client Applications

You can build client functionality in Microsoft Exchange Server by extending the Microsoft Exchange Client or by developing your own client application.

Extending the Microsoft Exchange Client usually involves adding functionality to the Viewer, such as a new pull-down menu or function key. The Viewer is where users access, organize, and exchange information, as shown in the following figure.

The Viewer groups many types of information in one place, including such diverse items as e-mail, word processing, voice mail, faxes, spreadsheets, presentation graphics, meeting requests, and customer contact reports. The toolbar is the interface for tasks such as printing, creating a new message, deleting an item, or viewing the address book. This interface is consistent across all platforms supported by Microsoft Exchange Server.


Information Storage

Storing Information

The Viewer structures its information in a graphical format showing a hierarchical tree of folders on the left of the screen and the contents of the selected folder on the right of the screen. All objects are viewed as folders and messages whether they are public or private, local or Internet, scheduling, e-mail, or documents.

The user interface directory structure contains several different types of folders—the mailbox, personal folders, and public folders.

  • The mailbox serves as the delivery location for all incoming mail messages for a designated owner. Information in a user’s mailbox is stored in the private information store on the client’s home server.
  • Personal folders contain information intended for private use. They can also be designated as the delivery location for mail if a user wants to store e-mail messages locally. Mail delivered to personal folders is still funneled through the mailbox on the server running Microsoft Exchange Server, but it is stored wherever the personal folder is located. Personal folders can either reside on a file server or locally on the user’s hard disk.
  • Public folders store information that is available and intended for sharing. They reside on servers running Microsoft Exchange Server and provide easy access to the information they contain.


Sharing Information

Microsoft Exchange Server allows users to share information either by sending e-mail or by sharing it with others using public folders. Applications can also send messages and access the public folders.

Information is organized and managed using rules, views, and the Find window.

  • Rules Can be automatically created or changed by your application. Microsoft Exchange Server uses rules to filter incoming mail and take actions such as moving selected objects to a particular folder, forwarding to another user, or deleting certain selected types of information. Auto-assistants are user interface options that can be used by your applications to create rules that sort items even when the user is not logged on.
  • Views Can be created or changed by custom applications. Rules allow users to organize and view information by selecting a predefined view or defining a custom view.
  • The Find window Allows applications or users to search through existing items stored in any folder by using a wide range of search criteria.


About Server Applications

You can add services to Microsoft Exchange Server systems by extending the Microsoft Exchange Server Administrator program or by developing a separate server application.

The Administrator program is used to perform operations such as creating mailboxes, managing basic Microsoft Exchange Server components, and managing directory objects. You can extend the Administrator program by adding custom property pages and adding application-specific extension data.

Server applications for Microsoft Exchange Server interact with user services such as the information store and the directory. Server application components can reside on a server running Microsoft Exchange Server, or on any computer running Windows NT Server, even if that system is not running Microsoft Exchange Server.

Microsoft Exchange Server runs as a mail server on the Windows NT Server operating system, which allows it to take advantage of the platform’s reliability, scalability, and multitasking capabilities. For example, Windows NT Server multitasking allows Microsoft Exchange Server to simultaneously update directory information, transfer information to a client, and route information to other servers and foreign systems.

The following figure shows how clients such as the directory and the information store access Microsoft Exchange Server services with complete independence from the underlying network. All communication between clients and services in the Microsoft Exchange Server environment is handled through remote procedure call (RPC) messages that can travel over almost any type of network, including Novell NetWare, Microsoft networks, and TCP/IP.

Client access of services running on Microsoft Exchange Server

Because services running on Microsoft Exchange Server support standard interfaces such as MAPI, clients can access them the same way they access other MAPI service providers. This simplifies Microsoft Exchange Server client application development. Programmers use APIs that they may have already used to access other MAPI services. Using these open interfaces, developers can build applications that include electronic mail, group scheduling, forms routing, bulletin boards, and workflow automation. Microsoft Exchange Server also allows existing MAPI-compliant applications from third-party vendors to interact with services running on Microsoft Exchange Server.


About Combined Client and Server Applications

Some applications include both a client and a service component. For example, you might design a document library application with a user interface that visually organizes and displays information to users, but also includes a server application component that manages documents in the information store and provides custom features such as version control and intelligent backup facilities. The following diagram illustrates combined client and server applications.

An application with both client and server application components

Although it is possible for client applications to communicate directly with services using mechanisms such as the remote procedure call (RPC) protocol, client application components and server application components in the Microsoft Exchange Server environment rarely connect directly to each other in this manner. Instead, client applications and services interact through messages that are sent to recipient objects in the information store. For example, a client application might issue a request to a service by sending a message to a folder in the information store. The service might poll this folder every few seconds to determine if any new messages have arrived and take action on new messages that appear.

When developing an application with both a client and a server component, you must decide how to divide the functionality between the client and server components. Performance and load balancing can often help determine these decisions.


Microsoft Exchange Client and Server Architecture

Microsoft Exchange Server employs a client-server architecture. While Microsoft Exchange Server can be installed in different configurations, a basic installation will have some components located on a Microsoft Exchange Server computer and other components located on one or more Microsoft Exchange Client computers. It may also involve server applications (including gateways) running on other computers. The following diagram illustrates the external interfaces in such an installation.

Microsoft Exchange Client and Server


Server Components

Server components for Microsoft Exchange Server often reside on a dedicated computer. These components are shown in the following diagram.

Server components of Microsoft Exchange Server

The following components run on the Microsoft Exchange Server computer:

  • Directory Stores and manipulates information about an organization’s Microsoft Exchange Server directory objects, such as recipients, distribution lists, public folders, and services.
  • Directory exchange agent (DXA) Maintains synchronization between a Microsoft Exchange Server directory and a Microsoft Mail 3.x directory or a directory using the Microsoft Mail 3.x protocol.
  • Information store Contains all server-resident information created by users such as messages, forms, and documents. The MAPI programming interface is used by both clients and services to access the information store.
  • Message transfer agent (MTA) Routes messages to other servers or to X.400 mail systems. The MTA is a native X.400 message transfer agent. Messages to be sent through gateways and mail connectors to other systems are also routed to the MTA, but then are routed back to the information store for direct transfer to the gateway or mail connector. There is no direct programming interface for accessing the MTA.
  • Gateway Provides a connection between a Microsoft Exchange Server system and a foreign mail system. The gateway translates messages and maps addresses between the two systems transparently to the user. Gateways can also be used to connect one Microsoft Exchange Server organization with another. While mail connectors are often specific to a single foreign mail system, gateways are often general enough to be customized for different systems. See the Gateway Programmer’s Reference.
  • Connector Similar to a gateway. Mail connectors are often developed for a single foreign mail system, such as SMTP.

The following basic services are associated with Microsoft Exchange Server:

  • Directory
  • Information store
  • Message transfer agent (MTA)
  • System attendant

These services are managed by the Windows NT service control manager.

Each server component of Microsoft Exchange Server can be accessed by developers so you can design your own server applications and customize your system to meet the specific needs of your organization.


Client Components

A client may be located on a Microsoft Exchange Server computer or on a user’s workstation. Client applications expand the capabilities of Microsoft Exchange Server. They employ services of Microsoft Exchange Server, but provide no services of their own. The Microsoft Exchange Client or a client application communicates with Microsoft Exchange Server through MAPI.

The following diagram shows a typical arrangement of client components on the user’s workstation.

Microsoft Exchange Client components

The Microsoft Exchange Client computer contains the following components:

  • Microsoft Exchange Client Provides e-mail delivery through user mailboxes, and provides information sharing through public folders.
  • Client extension Adds functionality to an existing client. Added buttons or menu options — not a new user interface — invoke this new functionality
  • Client application Any application other than the Microsoft Exchange Client or Schedule+ that accesses services of Microsoft Exchange Server.

MAPI is used by clients, services, and applications to access Microsoft Exchange Server directory and information store objects. Although Microsoft Exchange Server offers several different programming interfaces, the majority of operations performed in a Microsoft Exchange Server environment use MAPI functions. For more information, see the MAPI Programmer’s Reference.


Server Applications for Microsoft Exchange Server

Services of Microsoft Exchange Server interact with components such as the information store and the directory and offer custom services to clients. For example, a server application can be designed to search through folders in the information store for all messages containing a certain text string or property value. Server applications may function independently of clients, or they may include a client component. Server applications communicate with Microsoft Exchange Server through MAPI. The following diagram shows the components of a server application.

Components of server applications


About the Directory

The Microsoft Exchange Server directory contains objects that are the principal means for applications to find and access services, mailboxes, recipients, public folders, and other addressable objects within the messaging system. For example, if a directory object represents a public folder with its own destination address, users and applications can send messages directly to the public folder through the messaging system.

The directory consists of two components: the directory database and the directory service agent. The directory database stores directory information. The directory service agent manipulates the information in the directory database and handles directory requests from applications and services.

The importance of the directory in application development is usually the information provided from the directory service about the state of objects in the Microsoft Exchange Server system.

Directory information can be accessed in the following ways:

  • MAPI address book functions
  • Microsoft Exchange Server directory access functions
  • Lightweight Directory Access Protocol (LDAP)

When MAPI address book functions are used, applications interact with the Microsoft Exchange Server directory as a standard MAPI address book. The directory access functions give applications direct access to information within the directory, subject to security restrictions.

For more information about support for LDAP by the Microsoft Exchange Server directory service, see Using the LDAP Protocol.


About MAPI Address Book Interfaces

Mailboxes, distribution lists, and public folders are the most common addressable objects found in the Microsoft Exchange Server directory. These objects are accessed through the MAPI address book from both server- and client-based applications. For example, an application can supply a user’s name to the address book and retrieve the entry identifier for that user’s directory object. This entry identifier can then be used to obtain this user’s attributes, such as first and last name, department, phone number, and e-mail addresses.

MAPI address book functions are also used to write information to the directory and to create objects of selected classes in the directory. MAPI operates independently of the underlying directory service, so applications can work with any MAPI-compliant directory service. Most client applications use MAPI to look up information in the directory.


About Directory Access Functions

You can use Microsoft Exchange Server directory access functions instead of the MAPI address book interfaces to manage information contained in the directory. These functions are typically used to perform the following actions:

  • Manipulate directory objects while creating and maintaining custom add-on services.
  • Manage a large number of directory objects at one time.
  • Synchronize Microsoft Exchange Server directory objects with other directory services.
  • Automatically update Windows NT user accounts as directory objects are updated.

The directory access functions are available only to applications running on Windows NT Server. They are most often used for setting up and maintaining applications, and, where appropriate, by server applications themselves.

Calls to these functions are commonly used to create, delete, import, and export objects such as mailboxes, distribution lists, remote addresses, gateways, mailbox agents, address types, and address templates.

Specific tasks carried out by directory access functions include:

  • Loading configuration information or extended attributes for objects in the directory when a new mailbox agent or gateway is installed.
  • Creating new objects in the directory, deleting directory objects, or manipulating directory objects individually or as a group. For example, an application can create a new Recipients container to contain application-specific Mail-Recipients objects such as public folders or mailboxes.
  • Obtaining information about changes for synchronization with other systems.

For more information about directory access functions, see Using Directory Access Functions to Share Information.


About Directory Structures

The directory contains two separate but related structures:

  • Directory information tree (DIT) Describes how directory objects are logically configured to represent a Microsoft Exchange Server organization.
  • Directory schema Defines the directory’s object classes and their inheritance structure. For more information, see About the Directory Schema.

The DIT includes specialized objects called containers whose main purpose is to store and organize related objects.


About the Directory Information Tree

The directory information tree (DIT) represents the user’s view of objects within the organization. Although every company has its own unique DIT structure, a typical DIT resembles the one shown in the following diagram.

A typical directory information tree structure

All Microsoft Exchange Server systems have a similar DIT structure at the organization, site, and server levels. However, most DITs differ significantly at the lower levels.

The organization appears at the highest level in the DIT. Only a single instance of the organization is shown because it represents the entire system. Site objects appear on the second level and usually correspond to an organization’s geographic sites. Located below the site objects are a number of containers that group lower-level objects according to their function. For example, the Recipients container holds the mailboxes, public folders, custom recipients, and distribution lists that are used throughout the organization. Custom recipients are users or companies outside the organization, such as vendors or customers.


About Containers

A container is analogous to a file system subdirectory or folder. You can store related objects in it, as well as default security information for objects within the container.

For example, administrators might split the single default Recipients container into separate containers, each with its own mailboxes, public folders, and custom recipients. Each Recipients subcontainer may correspond to a geographic location or a group within a company. Administrators and programmers can define almost any type of container that holds any type of directory object.

Each site usually includes a Servers containers for one or more site servers, which usually provide a site’s networking, messaging, and communication services. Site servers run Microsoft Exchange Server, which includes the directory, directory exchange agent (DXA), information store, message transfer agent (MTA), and other components.

The Connections container includes gateway services objects for gateways linking Microsoft Exchange Server with other systems inside or outside the organization.

For more information on organizations, sites, and configuring a Microsoft Exchange Server network, see the Microsoft Exchange Server Administrator’s Guide and the Microsoft Exchange Server Concepts and Planning Guide.


About External Objects

In some cases, Microsoft Exchange Server is installed within an organization that uses other messaging systems such as SMTP and X.400. Objects such as mail recipients that are defined within these messaging systems are sometimes referred to as external objects. They can be addressed from within the Microsoft Exchange Server messaging environment in two ways:

  • As directory objects of the Custom-Recipient class. A Custom-Recipient object is an address for a user outside the Microsoft Exchange Server organization that is included in the directory and allows that user to receive mail from Microsoft Exchange Server users.
  • Directly, with an address type that is supported by a gateway or mail connector between Microsoft Exchange Server and the messaging system. This method is known as one-off addressing. Microsoft Exchange Server directly supports X.400, Microsoft Mail, and SMTP (Internet) address types. Programmers can add additional types.

Because every addressable directory object has a distinguished name (DN) consisting of its path plus its name, applications can address a message to any object using the object’s DN, regardless of whether an object is internal or external to the Microsoft Exchange Server environment. If an external object is referred to by its DN, Microsoft Exchange Server will automatically resolve the DN to the appropriate external address. This resolution is done using the Target-Address attribute, which is defined on all custom recipient objects.

The Target-Address attribute indicates the default external address to use for an object. A Target-Address is usually an X.400, SMTP, or other external address. All addressable objects in the directory also contain a set of proxy address attributes, each of which contains the address of the object represented in a foreign mail system. Proxy addresses make it possible to address any object using several addressing schemes, and also to send mail to a user in a foreign system using the proxy address in the Microsoft Exchange Server system. The concepts described in this section are illustrated in the following figure, which shows a Custom-Recipient object and three of its addressing attributes.

Custom recipient object with three addressing attributes


About Directory Security

When a user or a client application attempts to change a directory object or seek information on it, that request is granted or denied according to the permissions the requestor has on the object. These permissions are stored in the discretionary access control list (DACL) of that object.

Every object in the directory information tree (DIT) has an attribute called a security descriptor. This security descriptor is a binary value that contains the discretionary access control list (DACL) for that object. The DACL consists of a list of security identifiers (SIDs) and the specific permissions for each SID. The SID is a value generated for every new Windows NT user account for security and identification purposes. Microsoft Exchange Server uses the SID to identify the account for directory security.

Each DACL is a table, structured as shown in the following diagram.

Structure of a DACL

The permissions stored in an object’s DACL can be viewed through the Administrator program by looking at the object’s Permissions property page.

An access control entry is added to an object’s DACL when an administrator or a process assigns a role or individual access permission to a user for a given object. For example, when a mailbox is created and its primary Windows NT user account is assigned, an access control entry indicating the role of Mailbox Owner is created for the owner and stored in the DACL of the mailbox.

You can also add or change access control entries by using directory access functions such as BatchImport and DAPIWrite. These functions use several pseudo-attributes to convey information that will eventually be stored as directory attributes. The Obj-Admins pseudo-attribute specifies the names of accounts that have administrator permissions on the object. The Obj-Users pseudo-attribute specifies the names of Windows NT user accounts that have user permissions on the object. For more information, see Using Directory Access Pseudo-Attributes.


Inheritance of Permissions

The effective permissions a user can exercise on a directory object are the sum of two types of permissions:

  • The permissions the user account has on that object
  • The permissions the user account inherits from above. The account inherits only the permissions assigned to the same user account on object(s) above it in the directory information tree (DIT) hierarchy.

Although a user account automatically inherits any additional permissions that the account also has on the object’s parent object, the inheritance doesn’t end at the parent object. It continues up the directory tree within the object’s naming context.

Naming Contexts

In the Microsoft Exchange Server DIT, a naming context is a subtree that starts at one object (the naming context master object) and is bounded by leaf objects or the start of another naming context.

The permissions an object inherits from above in the DIT hierarchy are limited by naming context master objects. That is, objects below these master objects in the DIT do not inherit user-account permissions from objects above them in the DIT hierarchy.

The four kinds of naming context master objects are all container objects. They are listed in the following table.

Naming Context Master Objects

Designation | Object
NC1 | Organization container
NC2 | Site container
NC3 | Configuration container
NC4 | Schema container

Using Naming Contexts to Determine Permissions

The use of naming contexts lets administrators more easily tailor the security structure of the DIT, allowing a single Windows NT account to have one set of permissions at a higher level (such as an organization) and a different set at a lower level (such as a site).

For example, in the following diagram, the One-Off Address Templates object resides in the Addressing container below the Configuration container of the site called NAmerica-W. In this example, a Windows NT user account has the role of User on the One-Off Address Templates object, the role of Admin on the Addressing container, and the role of Service acct admin on the NAmerica-W site object.

Roles on objects

The effective permissions for this user on the One-Off Address Templates object are:

  • User permission on the One-Off Address Templates object itself, as specifically granted.
  • Admin permissions inherited from the Addressing object. This object is within the NC3 naming context (the Configuration object), so its permissions are inherited.
  • The user’s permissions on the NAmerica-W object are not inherited because the Configuration object (a naming context) interrupts the inheritance.

In this way, a user with broad permissions on an object high in the DIT hierarchy (such as the NAmerica-W object) does not automatically have access to all the information in the individual sites.


Roles

You assign permissions to a Windows NT account, user, or group by assigning a role to that account, user, or group. A role is a predetermined set of permissions that defines the access of a user or group to an object. Microsoft Exchange Server provides several default roles for directory access. Administrators can define custom roles to suit the needs of the site or organization.

The default roles for Microsoft Exchange Server directory object access and their associated permissions are shown in the following table.

Default Roles and Associated Permissions

Role | Permissions
Admin | Add child object, modify user and administrator attributes, delete objects, logon
Permissions admin | Add child object, modify user and administrator attributes, delete objects, logon, modify existing permissions
Service acct admin | Add child object, modify user and administrator attributes, delete objects, send messages as another user, , logon, replicate changed objects, modify existing permissions, act as mailbox owner
View-only admin | Logon only
User | Modify user attributes, send as this user, act as mailbox owner
Send as | Send as this user

Note Microsoft Exchange Server roles and the permissions they encompass are not influenced by the Windows NT rights assigned to the user.


Sharing Directory Information

Each site server stores a copy of the directory that is virtually identical to all other copies of the directory in the organization. Changes made to one copy of the directory are periodically propagated to all other copies of the directory on all other servers. This process is known as directory replication.

This means that, subject to a small latency period for the replication process, every Microsoft Exchange Server directory within an organization has the same directory objects. Furthermore, any object in the directory information tree (DIT) has the same distinguished name within all copies of the directory throughout the organization.

Administrators and applications frequently add, delete, and modify directory objects. In some cases, applications track the changes made to directory objects. For example, a service may keep track of which recipients have been added to a site, or which have recently been modified.

Tracking changes to directory objects can be done using two attributes, each of which are defined on all objects:

  • Update sequence number
  • Object version number

Directory replication within a Microsoft Exchange Server system is automatic. Microsoft Exchange Server also has the capability of sharing this information with other systems. This capability allows the directory address book to be synchronized with other sites and other organizations running Microsoft Exchange Server, as well as with systems that use other messaging and storage technologies.

The following sections describe the transfer of directory information between a Microsoft Exchange Server system and a foreign system. They also include a brief overview of the different methods you can use to transfer directory information, when each method is appropriate, and where to find further information.


Determining the Scope of Information Transfer

The method used to transfer directory information depends on the scope of the transfer — whether it’s within a Microsoft Exchange Server site or organization, beyond it to another organization, or to a foreign mail system.

The following cases summarize how directory information can be shared.

Information Transfer Within a Microsoft Exchange Server Site

You can configure the automatic directory replication process using the Microsoft Exchange Server Administrator program. For more information about transferring information between servers within a Microsoft Exchange Server site, see the Microsoft Exchange Server Administrator’s Guide.

Information Transfer Between Microsoft Exchange Server Sites

You can configure directory replication between sites using the Microsoft Exchange Server Administrator program and the directory replication connector. For more information about transferring information between Microsoft Exchange Server sites, see the Microsoft Exchange Server Concepts and Planning Guide and the Microsoft Exchange Server Administrator’s Guide.

Information Transfer Between Microsoft Exchange Server and Microsoft Mail 3.X Server

To configure directory synchronization between a Microsoft Exchange Server system and a Microsoft Mail 3.x server (or any system that uses the Microsoft Mail 3.x protocol), you can use the directory exchange agent supplied with the Microsoft Exchange Server Administrator program. For more information, refer to the Microsoft Exchange Server Concepts and Planning Guide.

Information Transfer Between Microsoft Exchange Server and Other Foreign Systems

You can transfer directory information to or from foreign systems (other Microsoft Exchange Server systems or outside mail systems other than Microsoft Mail3.x). The process includes generating a file that contains the directory information, sending it to the other system, and importing it at the foreign system. The DIRSYNC sample application demonstrates how to accomplish this type of information transfer, using a keyboard command for each part of this process. DIRSYNC can also be modified to perform this task automatically and avoid the need for creating or transferring files manually.

Note Public folders, which have components in both the directory and the information store, are automatically replicated to other servers and sites. For more information, see About Public Folder Replication.


Exporting and Importing Changed Objects

When changes have been made to directory objects since a previous export operation, directory access functions can detect these changes by checking each object’s update sequence number (USN). The USN is a counter maintained by the directory on a specific server. It is incremented whenever an object in the directory is changed, and then written into the USN-Changed attribute of the changed object. The USN therefore indicates the order in which a given object was altered relative to other objects in the directory on that server.

The USN-Changed and USN-Created Attributes

The USN-Created attribute is the value of USN-Changed that was assigned to the object at its creation. The USN-Created attribute does not change when the object is modified. The USN-Created attribute can be used in conjunction with USN-Changed to determine whether the object has been created or merely modified since the last export operation. This attribute can also be used to determine whether a deleted object existed at the time of the last export operation, or if it was both created and deleted since the last export operation.

Deleted Objects and Tombstones

A deleted object remains in the directory for a time in the form of a tombstone (an object with the Is-Deleted attribute set). Tombstones older than a certain age (the default is 30 days) are periodically deleted in a process known as garbage collection. If a directory synchronization program waits longer than the tombstone lifetime between updates, an object may be deleted and its tombstone removed before the directory synchronization program can read it. In this case, the foreign system may not be informed that the object has been deleted from the directory.

However, a directory synchronization process can tell if any deleted objects have been removed by examining the object’s PR_EMS_AB_USN_LAST_OBJ_REM property. If this property is greater than the largest USN exported in the most recent directory synchronization, a deletion has been missed. The DIRSYNC sample application does not check this attribute. Directory access functions can generate a list of the changed objects by selecting only those objects with a USN greater than the largest USN returned during a previous export. When this list is generated for the first time, it includes all objects in the directory. For more information about USNs, see Selecting Objects to Export and Accessing Directory Attributes with MAPI.

Choosing a Server for Object Export

Directory synchronization should be carried out from the same server each time. The USN for an object is server specific — it applies to this object only on this server. The USNs for a single object on different servers are not synchronized and are not likely to be the same. Replicas of objects will probably have different USNs on different servers. When a changed object is replicated to another server, the USN for the object on the second server is updated, but is not likely to be the same as the USN on the first server. For this reason, exports from different servers to the same foreign site would use a different set of USNs and would export incorrect data.

If the server for directory synchronization becomes unavailable, a new server is selected and the entire directory from that server is exported. Subsequent incremental synchronizations are performed from that server, or the same procedure is repeated to enable a new server.

Exporting and Transferring Object Information

The directory access functions create a formatted file that contains the information for all the exported objects. Alternately, they can pass the objects one-by-one to a caller-specified routine, which in turn can write them to a file in whatever format has been chosen. An export file generated in this manner can then be sent to another system, or it can be written directly to the foreign system’s import agent.

Agents on remote Microsoft Exchange Server systems can also generate export lists in directory-import format. Many foreign systems can be programmed to generate such lists from their databases. These export files are then mailed to the local Microsoft Exchange Server system, received through a gateway, and then imported using directory access functions.


Using Directory Access Functions to Share Information

The export directory access functions can use the USN-Changed attribute to detect whether a directory object has changed since the last export, but they cannot determine which of the object’s attributes have changed. Although callers of directory access functions can specify which attributes to return by using the pAttributes parameter, an object is still exported if other irrelevant attributes change.

For example, when a new address type is added to a Microsoft Exchange Server system, a proxy address is generated for every recipient in the Microsoft Exchange Server system. That causes every recipient to be marked as changed and new USN-Changed values to be generated, even though the changes may not be among the attributes that are exported.

The directory synchronization agent is responsible for determining whether a directory object has changed in a significant way, and therefore whether to keep the object in the export file. The DIRSYNC sample application uses the USN-Changed attribute to determine which objects to export. DIRSYNC does not decide if the change is significant, but simply exports all changed objects.

One advantage to using the directory access functions for directory synchronization is that no mail connection between the synchronizing systems is required. The designer is free to select whatever communications method is most appropriate. For example, a service can be designed to run periodically and check for changes in a database of users. Alternately, the database can be programmed to wake up the service when changes occur, which then reads and exports them. If a direct network connection exists between this service and the Microsoft Exchange Server directory that needs to be updated, no electronic messaging is necessary to send the changes to the directory. Instead, the service can directly call directory access functions to import changed data into the Microsoft Exchange Server directory.


Sharing Directory Information with a Database

Directory information can be shared with a database as well as another server. For example, an organization may store its human resources data in a database. This data is updated when new employees are added, or when other changes are made. When the changes are complete, an application can be run that extracts the new database information and generates an export file in the format used by the directory access functions. This file can be mailed to a Microsoft Exchange Server system in the same organization where directory access functions can be used to update the Microsoft Exchange Server directory. Database entries can automatically become Microsoft Exchange Server recipients.


Importing Data into Microsoft Exchange Server

To successfully import a new object into the directory, all the required attributes for this object must be defined. Some of these attributes are already defined because they are imported. The remaining attributes must also be defined before the object is successfully imported into the directory.

The object’s class determines which attributes must be defined. For example, if you create a Mail-Recipient object, a value must be supplied for its Delivery Mechanism attribute, Common-Name attribute, and Object Class attribute. To locate a complete list of required attributes for a directory object, see the SCHEMA.HLP file included in this SDK, or use the Microsoft Exchange Server Administrator program.

To find a complete list of required attributes for a directory object
  1. Start the Administrator program with the /RAW switch set.
  2. Select Raw Attributes from the File menu.
  3. In the List Attributes of Type box, select Required. All the required attributes will be displayed.

For more information about creating a process for exporting and importing data, see Creating a Directory Synchronization Agent.


Exporting Data from Microsoft Exchange Server

The default export file format generated by the directory access functions is described in the Microsoft Exchange Server Administrator’s Guide.

To export data from Microsoft Exchange Server to a foreign system, it may be necessary to convert the data into a format that can be read by the foreign system. In some cases, this intermediate conversion step can be carried out with Microsoft Excel macros. The data can be inserted into an Excel worksheet, and a macro can move the information into the appropriate columns and rows. The worksheet data may then be imported into the foreign system.

Some information exported from a Microsoft Exchange Server directory may not be readable by a foreign system. In these cases, the importing agent for the foreign system must determine the significance of the information, whether to import it, and how to import it.

For more information about creating a process for exporting and importing data, see Creating a Directory Synchronization Agent.


About the Information Store

Microsoft Exchange Server includes four kinds of information stores, all of which are implementations of MAPI message stores:

  • Public information store
  • Private information store
  • Personal folder store (PST)
  • Offline folder store (OST)

The public information store contains public folders that store information to be shared between users.The private information store consists of mailboxes and personal folders that contain information to be secured from other users.

The public information store and the private information store have the ability to automatically distribute selected information to various locations, and to update copies of their contents throughout the system.

The personal folder store (PST) is part of the Microsoft Exchange Client. It contains personal folders and is used to distribute selected information to various locations at the client computer as directed by rules associated with the personal folders. The PST can also be used to move or copy information between server and client.

The offline folder store (OST) contains synchronized copies of folders in the Favorites subtree that have been selected for offline access. It is created only when a user synchronizes these folders for offline access using local replication.

The user sees the public and private information stores as top-level folders in the folder list (the left pane of the client interface). The following figure shows this hierarchy.

The private information store is shown as the Mailbox for this user. The public information store is seen as Public Folders. The personal folder store is seen as the Personal Folders top-level folder. The offline folder store is seen as the Exchange Internet Discussion folder, which has been selected for offline access from the Favorites subtree. The suitcase icon indicates that this folder is selected for offline access.

The Favorites and All Public Folders subtrees appear under Public Folders. This hierarchy organizes the user’s view, but does not always represent the actual organization hierarchy of the stores. For more information, see Opening the Favorites Folder.

Favorites folders can be synchronized using local replication. This allows a user to work with folders in the public and private information stores while offline and online. For more information, see About Offline Folders.

All types of MAPI message stores share certain traits. For example, the IMAPISession::OpenMsgStore method is always used to open an information store object, regardless of its type or how it is implemented. The interface returned from this call is always an IMsgStore interface. For more information about these standard MAPI operations, see the MAPI Programmer’s Reference.

For more information, see the following topics:

Locating an Information Store

Opening an Information Store

Opening a Public Information Store

Opening a Private Information Store

Determining the Type of Information Store


About Mailboxes and the Private Information Store

The private information store consists of mailboxes that can belong to users or to applications. Mailboxes reside on the computer running Microsoft Exchange Server. Each newly created mailbox has four default folders visible to the Microsoft Exchange Client:

  • Deleted Items
  • Inbox
  • Outbox
  • Sent Items

The mailbox contains several other folders that are not visible and are used for storing information such as user-defined views. Users or applications can create new, visible folders in addition to the four default folders. The following diagram shows the internal architecture of a mailbox.

Mailbox architecture

Folders that are always present but are not visible to the user include the following:

  • Deferred Action Includes messages about actions that should be performed when resources are available to update the visible folders.
  • Schedule Contains Schedule+ information for the mailbox owner.
  • Shortcuts Contains information about Favorites folders.
  • Common Views Contains user-defined views.

The Finder and the Print Spooler are additional folders that are contained in the mailbox but are not visible to the user.


Access to Mailboxes

It is possible to open your own mailbox and, with sufficient permissions, to open another recipient’s mailbox. The owner of a mailbox (a user or an application) has automatic Owner privilege on that mailbox and can therefore open the mailbox and its contents. The owner of a mailbox can assign any of several types of delegate access for that mailbox to another recipient, who can then manipulate the mailbox and its contents according to certain rules.

An owner can also assign access control list (ACL) entries to server store folders, although an ACL entry is not necessary for Owner privileges. A third means of opening mailboxes is a mechanism called privileged access, which is associated with an administrator privilege granted to a server application. Such an application is known as a privileged service.

For more information about delegate access, see Setting Access Controls and DelegateName. For more information about privileged access, see Running an Application as a Privileged Service. For information about ACLs, see About Access Control Lists.


About Public Folders

The public information store contains public folders and messages that can be shared among multiple users and applications. A single public information store is shared by all users within a Microsoft Exchange Server organization, even if multiple servers are used.

The public information store consists of two branches: the interpersonal message (IPM) subtree and the non-IPM subtree. Contents of the IPM subtree are visible through the client, but contents of the non-IPM subtree are not visible. The following diagram shows the structure of the public information store.

Public information store architecture

Folders in the non-IPM subtree that are not visible to the user include:

  • EFORMS registry This top-level folder contains forms in various languages.
  • Offline Address Book folder This folder contains information that is needed to perform address book updates.
  • Schedule+ Free/Busy Folder This folder contains a subfolder for each site with free/busy information for the users at that site. It is consulted when meetings are automatically scheduled or other such operations are performed.


Access to the Public Information Store

Accessing the public information store is similar to accessing any other MAPI message store. MAPI methods are used to perform most functions, but some parameters to these methods differ from the ones used by other MAPI functions. Most MAPI client applications do not distinguish between public and private folders; this is a Microsoft Exchange Server distinction.

Special wrapper functions facilitate access to the Microsoft Exchange Server public information store. These functions hide some MAPI programming details when public information store operations are performed.

For example, when used with the entry identifier of a message store, the HrOpenExchangePublicStore function allows you to open a public information store. The FIsPublicStore function enables you to determine whether an open store is public. Once you’ve obtained the interface object for the public information store, you can use the public folder functions of Microsoft Exchange Server to manipulate the public folder. For more information, see Determining the Type of Information Store.

Unlike the private information store, the public information store makes no distinction between folder types. It can, in fact, be considered a special type of mailbox that holds a group of public folders created by administrators, users, or applications.

Public folders can only be accessed by persons or applications with sufficient permissions. For more information, see About Information Store Security.


About the Favorites Folder

The Favorites folder in the public information store contains links to public folders selected by a user for quick access. A link is created in the Favorites folder when a user selects a public folder and chooses Add to Favorites from the File menu of the Microsoft Exchange Client. Folders that appear in the user interface under the Favorites folder are actually public folders under the IPM subtree, but they can be accessed directly from the Favorites folder.

The Favorites Folder is used for the following:

  • As a shortcut to selected folders without requiring specific paths in the public folder hierarchy.
  • As the method for synchronization with offline folders, which give the user access to public folder information when offline.
  • As a means to provide an unread count on public folders, which allows the user to quickly judge the amount of new information in the folder.

The Favorites folder and the All Public Folders folder are part of the hierarchy table when it is obtained after opening the IPM subtree specifically, but not when the hierarchy table is traversed from the public information store root folder. For more information, see Opening the Favorites Folder. After you open the Favorites folder, you can add or delete links to public folders using the IExchangeFavorites interface.

When users are not directly connected to Microsoft Exchange Server, they can still have access to the Favorites folder by using local replication. See About Offline Folders.


About Offline Folders

When users are not directly connected to Microsoft Exchange Server, they can still have access to the Favorites folder by using local replication. Local replication is the synchronization of folders located on the server with the offline folder store (OST). Local replication automatically copies the following items:

  • Inboxes
  • Outboxes
  • Sent mail
  • Deleted mail
  • Any folder in the Favorites folder designated as an offline folder
  • Any folder in the user’s private information store designated as an offline folder

Offline folders include any folder that has been designated as an offline folder by the user through the client interface. incremental change synchronization is used to synchronize private information stores with the OST.

Folders designated as offline folders (either in the user’s mailbox or in the Favorites subtree) are copied to an OST file when the user requests folder synchronization for the folder. The complete folder hierarchy (the MAPI hierarchy table) is also copied, and is therefore identical when viewed by an offline application.

The offline folder can be accessed either offline or online at a given moment. When a user has made offline changes to a folder, these changes are automatically copied to the server the next time the user logs on to the system. Changes that may have occurred on the server while a user is offline are synchronized with the user’s OST only when he manually requests it.

An OST file is similar to a PST. The difference is that an OST file is RTF-aware, while a PST is not. The contents of any folder designated as an offline folder are included in the OST file, but the contents of the mailbox and other folders are not. For more information, see Working with Offline Folders and RTF-Awareness.


About Public Folder Replication

Public folder replication in Microsoft Exchange Server is a mail-based, multimaster system. In a mail-based system, all changes are sent to the replica servers in mail messages. In multimaster systems, any changes in public folder contents are propagated to all other replicas of that folder on other servers, rather than channeled through a specified master server. Folder hierarchy changes are sent to all public folder servers.

Replication is configured by an administrator through the Microsoft Exchange Server Administrator program. Per-folder replication schedules, which override the server’s replication schedule, can also be configured.

At the time of a scheduled replication, the information store on a server collects all changes since the last replication. It then packs the changes into one or more specially formatted mail messages and sends them to all servers that have replicas for those folders.

Objects in information stores have a property that indicates the order in which changes occurred. This property is used to report replication status. While changes are normally propagated from each server to all the others, a single server can request the replication status from another server, and then request that all changes made since a given change number be sent.

When replicated folder information is received, the receiving server checks for conflicts in the hierarchy and the contents of replicated folders.

Access control lists (ACLs) are part of the design of a folder, and as such are replicated. They have no effect on content replication. For more information about access control lists, see About Access Control Lists.


About Personal Folders

The personal folder store is part of the Microsoft Exchange Client. This information store resides at the client computer and is used to store items that are owned by individuals and not shared by multiple users. The following diagram shows the personal folder store architecture.

Personal folder store architecture

A user’s personal folders are found on the client computer in a file with the extension .PST. Only folders below the Top of Personal Folders folder are visible. The other folders below the root (such as IPM_VIEWS) are not visible.


About Rules

Microsoft Exchange Server uses rules to automatically execute predefined actions on selected objects. You can also develop applications that use rules to carry out predefined or custom actions. For example:

  • Rules can be triggered when mail arrives at a user's mailbox or items are sent or posted to a public folder. These rules can set up or control an often-used combination of condition and action.
  • Rules can perform a part of an application's activity, such as setting up folder structures.

For more information on developing applications that use rules, see Working with Rules.

A rule can be set up to run on either Microsoft Exchange Server or on the Microsoft Exchange Client. All rules on the client are known as deferred action rules. Rules on the server are of the following two types:

  • Rules on Public folders A predefined, limited set of rules.
  • Rules on Mailboxes The predefined rules, as well as custom actions that are invoked by mailbox rules. Custom actions take place on the Microsoft Exchange Client through the deferred action mechanism.

The mechanism for rules includes the following:

  • Server rules engine Part of the information store process that monitors messages that are sent to other users or posted to public folders.
  • Client interface The interface used for setting rules and for carrying out deferred actions.
  • IExchangeModifyTable interface An interface similar to an IMAPITable interface that is capable of handling the condition and action structures of rules.
  • IExchangeRuleAction interface An interface used to retrieve actions from deferred action messages.
  • IExchangeRuleExt interface and IExchangeRuleExtCallback interface Interfaces that provide users with custom deferred actions that can be selected from the Microsoft Exchange Client interface.


How Rules Interact with the Microsoft Exchange Client

Microsoft Exchange Server rules are evaluated against every message that comes into a folder or mailbox. When the message matches the rule condition, the rule fires and the rule action is executed. The server rules engine offers a fixed set of actions that it can carry out in the information store process on the server, but some actions must be carried out on the client. For instance, moving a message to a folder in another information store can be carried out only on the client.

The following actions are always passed to the client for execution:

  • Cross-store moves and copies.
  • Alert pop-ups.
  • Custom actions.


Rule Actions

Rule actions are of two types: normal and deferred.

  • Normal actions are carried out by Microsoft Exchange Server.
  • Deferred actions are carried out by the Microsoft Exchange Client code responsible for the rule. Deferred actions are invoked by deferred action messages. Deferred actions make possible tasks such as moving messages between folders in different information stores.


Deferred Actions

The server information store passes an action to the client by creating a deferred action message (DAM). This DAM is stored within the Deferred Action folder in the non-IPM subtree of the server’s private information store. Whenever a client connects to its mailbox, part of its initialization is checking for DAMs. If any DAMs are present, the client executes the action, known as a deferred action, as part of its initialization. All custom actions are invoked as deferred actions.


Custom Actions

You can also define custom actions and store them in a custom action DLL that is installed on the client computer. Users can create rules using functions from this DLL through the Inbox Assistant. The Inbox Assistant creates a rule on the server mailbox that results in a deferred action. When the client receives a DAM for the action (after the rule has fired), it invokes the DLL that is registered on the client to carry out the action. In other words, all custom actions are invoked as deferred actions. The CRARUN sample application provides an example of this type of custom DLL.

Two Microsoft Exchange Client interfaces are used for custom rule actions: IExchangeRulesExt and IExchangeRuleExtCallback. Both interfaces are defined in EXCHCLI.H.


Folders On Which Rules Can Be Set

Rules can only be set on folders in Microsoft Exchange Server-based information stores. They are accessible in the following folders subject to the restrictions defined in Rule Actions:

  • Private information store (mailboxes) Supports rules on all folders in both the IPM and non-IPM subtrees. The user interface of the Microsoft Exchange Client exposes rules only for the Inbox, but the server supports rules for all folders in mailbox information stores.
  • Public information store Supports rules on all folders in both the IPM and non-IPM subtrees. Only the folders in the IPM subtree have a user interface in the client. Folders in the Favorites folder in the public information store also support rules.


Rule Tables

Rule tables are associated with folders located in the server’s private information store (mailbox) and the public information store. For each incoming message, the conditions in the rule table are tested in sequence against the message. Any conditions that are TRUE trigger the associated action.

In private information store folders, only incoming messages are tested. In public information store folders, messages sent to the folder as well as those posted in the folder are tested.


Setting Rules

Rules are set by a rule provider at the client, and deferred actions are carried out by the provider action code. The default rule provider is code within the Microsoft Exchange Client that works with Microsoft Exchange Server to implement the Inbox Assistant, the Out of Office Assistant, and other folder assistant tools on the client menu and toolbar.

Rules processing occurs in the following sequence:

  1. A rule provider — either the Microsoft Exchange Client or a third-party provider — sets a rule on a folder. The rule is given a sequence number and stored in the folder’s rule table.
  2. The server rules engine interprets the rules in the table.
  3. The server rules engine evaluates the rule condition against items arriving in the Inbox and initiates actions for conditions that are TRUE.
  4. The server creates deferred action messages (DAMs) in the mailbox’s Deferred Action folder for a rule on a mailbox or private folder if the server cannot initiate the action or if the action is of the type deferred action.
  5. The corresponding provider code at the client retrieves any DAMs, either immediately or when the client reconnects.
  6. For deferred actions, the client then accesses the message in the mailbox or folder and carries out the action.

Rules components in Microsoft Exchange Server and client

The rules provider in the Microsoft Exchange Client allows custom action DLLs to be registered and called when their particular rules are fired.


Rule Properties

Microsoft Exchange Server provides applications called rule providers that have access to rules through MAPI folder properties. The set of rules for a user is maintained on a folder in the information store and is exposed through the MAPI property PR_RULES_TABLE (read-only), and the MAPI property PR_RULES_DATA (writable). PR_RULES_TABLE can be read using an IMAPITable interface, and PR_RULES_DATA can be read and edited through the IExchangeModifyTable interface. These properties and interfaces are defined in the EDKMDB.H file.

Besides the IExchangeModifyTable interface, a number of functions exist that can be used to add rows to the rule table, delete rows from the table, and enumerate the contents of the table. These individual functions may be easier to use for certain limited applications. See Creating a Rule.


Rule Conditions

Rule conditions are described in terms of MAPI SRestrictions. Rules are tested and fired in a sequence defined by the PR_RULE_SEQUENCE property. The Microsoft Exchange Client rule provider uses gaps between rules as a mechanism to allow rules to be reordered without replacing all the sequence numbers.This means that the sequence numbers need not be consecutive.

An error will be returned by the IExchangeModifyTable interface when rules are saved if either of the following conditions exists:

  • If an action cannot be carried out in the given context. For example, if a deferred action is requested on a public folder or if a move is requested to a folder that the information store cannot locate.
  • If a condition is in error.


About Information Store Security

Information store objects can be accessed only by users or applications with sufficient permissions. The ability to create or delete folders, post items, and edit public folder contents depends on the account’s permissions on that object, as specified by the access control list (ACL). An ACL is similar in function to the discretionary access control list (DACL), which limits access to directory objects. (See About Directory Security).

Access to information stores and the objects within them is granted in the following ways:

  • Mailboxes The information store verifies that the account requesting to log on (as identified by its security identifier) is that of the mailbox’s owner. If so, logon permission is granted.
  • Public information stores Security is not enforced on the public information store, but rather on individual folders within the store.
  • Offline folder stores (OST) Access to an OST is granted to the logon account with the profile in which the offline store was created. The OST may also be opened by another profile, but that profile must be logged on to the corresponding mailbox. File-level security can also be used to deny access to an OST.
  • Top folder within a store Special permissions are needed to create the top level folder in a public information store. No special permissions are needed in private information stores. Administrators can control the creation of top-level folders through the Administrator program.
  • Folder within a folder Folders within folders are treated as Contents of Folders, with this exception: The requestor must own a folder to delete it.
  • Contents of folders Access to messages and other items is determined by the permissions granted the requestor, as defined in the ACL of the containing folder. Any folder in an information store can have an access control list.


About Access Control Lists

An access control list (ACL) is used to control user access to information store objects. Any information store object for which a user can have access rights may have an associated ACL, including servers, sites, containers, mailboxes, and folders as represented within the information store.

Each ACL consists of a list of members and their associated security privileges, where each member is one of four entities:

  • A user from a Microsoft Exchange Server address book
  • A distribution list (DL) from a Microsoft Exchange Server address book
  • A public folder
  • A defined role with an associated set of permissions.

Applications are able to set, interrogate, modify, and delete ACL entries when the required permissions are in place. In this way they can control access to the folders they use.

The Structure of ACLs

An access control list (ACL) is stored as a table. Each row of the table consists of a distinguished name (DN) and a value that can be translated into the set of access controls (permissions) applied to that member. An ACL table is structured as follows.

Structure of an access control list

Because a directory object is identified within an ACL by its DN, any entity in the directory (including DLs) can be an entry in an ACL and thus have permissions on any folder. The permissions that may be assigned to an ACL entry are listed in the following table.

Permissions on information store objects

Permission | Description
frightsReadAny | Read any items.
frightsCreate | Create items.
frightsEditOwned | Edit any items owned by the user.
frightsDeleteOwned | Delete any items owned by the user.
frightsEditAny | Edit any item.
frightsDeleteAny | Delete any item.
frightsCreateSubfolder | Create subfolders for the folder.
frightsOwner | Set permissions on the folder.
frightsContact | appear as the contact on the folder. Not part of rightsAll.
rightsNone | No permissions on the folder.
rightsReadOnly | Read any item in the folder.
rightsReadWrite | Read from and write to any item in the folder.
rightsAll | All the above permissions on the folder except frightsContact.

At the time a folder is created, the entire ACL table is copied from the folder’s parent object. This means that the initial ACL contains at least these two entries: default and owner. This applies to private as well as public folders.

The initial default entry in an ACL cannot be deleted. Owner entries can be deleted, and other owners can be added. That is, new entries with the permission frightsOwner can be added, and an existing entry can be assigned the permission frightsOwner.

For more information about access control lists, see Manipulating ACLs and ACLEDIT sample application.


About Information Store Client and Server Components

Though usually considered part of the server, the server-based information store provider has both a server and a client component. Each component uses its own memory space in which it manipulates message objects. As shown in the following illustration, some of the message’s properties exist on the message object on the client and some exist on the server.

Message properties stored on both client and server

Applications make calls to the client component of the information store provider, and the store provider creates RPCs when it must get information from the information store component located on the server. This mechanism hides from applications the fact that the information store provider has a server component in addition to its client component. However, an understanding of this mechanism can be used when designing an application to optimize its performance.

Some operations on the store are very efficient because they can be serviced locally on the client. Others can become very I nefficient when they require repeated RPCs to the server. Some properties are stored — and can be retrieved — from the client without an RPC.

For more information, see Reducing the Number of RPCs.


About Incremental Change Synchronization

Incremental change synchronization is used within Microsoft Exchange Server for local replication. The collector and synchronizer that are shipped with Microsoft Exchange Server can be used to provide more general incremental change synchronization when used with an external agent.

Incremental change synchronization provides a mechanism to monitor and synchronize changes to an information store hierarchy or content. Changes may include the following:

  • Creating a folder or a message This includes incoming messages and posted messages, as well as folder or subfolder creation.
  • Modifying a folder or a message This includes moving of messages or updating of their contents.
  • Deleting a folder or message

Incremental change synchronization may be used for several purposes:

  • Retrieving changes Collecting the changes at one information store that have occurred within another information store.
  • Synchronizing changes Collecting change information from one information store and duplicating it at another store, thereby maintaining a store replica.
  • Replicating changes between two servers Keeping two or more information stores synchronized with one another while both are changing.

Two-way replication introduces additional complexity. To avoid looping conditions, each store is responsible for maintaining its state information.


Agents, Synchronizers, and Collectors

To synchronize information stores, a mechanism is required for retrieving incremental changes from one information store and placing these changes into another information store. This mechanism is implemented as part of the Microsoft Exchange Client.

Incremental change synchronization requires three component processes:

  • Agent Monitors and schedules synchronizations
  • Synchronizer Transfers changes when directed by the agent
  • Collector Collects changes on the receiving store.

The following diagram shows these component processes and their interactions with the information store.

A collector and synchronizer pair is supplied with the Microsoft Exchange Server.

The Agent

The agent is an external process that enables communication between the synchronizer and the collector. The agent process schedules and configures synchronization. The agent does not require detailed knowledge of the information store. Because more than one schedule for synchronization and more than one set of stores to synchronize may exist, more than one agent may also exist for the same information store.

The Synchronizer

The synchronizer receives a message from the agent when a synchronization is requested. The synchronizer then gathers a set of changes and transfers them to the collector process at the receiving information store. The synchronizer waits for a success message from the collector process. When the synchronizer receives this message, it transfers the next set of changes until all are complete. At the end of the process, the synchronizer sends a completion message to the agent.

The Collector

The collector mechanism imports the changes sent by the sending information store’s synchronizer. The collector mechanism sends a success message back to the synchronizer when a set of changes has been successfully synchronized.

Synchronization State

The synchronization state is a record of what has been exported in a synchronization action. By tracking what has been exported, it helps to determine what needs to be exported during the next synchronization.

The format of the synchronization state data is agreed on between the collector and synchronizer mechanisms for a specific information store. For example, if each change on a store is assigned a sequential index, and the highest index successfully received by the second information store is kept by the synchronizer, changes with indexes higher than this stored index can be transferred at the next synchronization. The agent determines where this state information is stored.

Synchronization involves sending messages across a network, so the possibility of a lost message or other unsuccessful partial synchronization always exists. Thus state information must be maintained for use either by the synchronizer or the agent.


The Process of Synchronization

The synchronization process begins when the agent process is started. This agent process may be a Windows NT service started by the system or a process run from a command prompt. Once the agent process is running, it performs two initialization steps:

  • Determines the source for changes by opening the relevant information store using a MAPI call, locating the folder from which changes are to be retrieved, and obtaining the synchronizer interface for this object.
  • Determines the destination for changes by opening the relevant information store, locating the folder that is to receive the changes, and obtaining the collector interface for this object.

The agent communicates with the collector only during this initialization. At all other times the agent communicates only with the synchronizer.

Once initialization has been completed, the agent makes periodic calls to the synchronizer requesting it to perform a defined synchronization. The synchronizer gathers and sends the changes and in turn makes a request to the collector to import the changes. The collector at the receiving information store imports the changes and, if the import was successful, sends a message indicating success. Following each successful import the synchronizer updates the synchronization state. This process continues until the requested synchronization is complete. The synchronizer then replies to the agent with a task-completion notification.

Two-way Replication

This process is similar for both synchronization and two-way replication. However, synchronization requires a single agent, collector, synchronizer, and synchronization state, while two-way replication requires a second collector, synchronizer, and synchronization state. The second synchronization state in a two-way replication is used by the synchronizer to verify that changes passed from one information store are not being returned, thus avoiding circular synchronization.

Two-way replication of information stores

During two-way replication, state information is shared between the collector and synchronizer pair of a single information store and not between the collector and synchronizer pair that are exchanging data.

Inter-site and inter-organization synchronization has additional complexity because of its distributed nature. The potential lack of network connectivity means that a direct connection between the collector and the synchronizer is not practical. In such cases a proxy collector must store the changes locally and propagate the changes to the remote site. An agent at the remote site can import the changes into the information store using the remote site collector. How the changes are propagated is an implementation decision for the designer of the collector at the receiving store.

Microsoft Exchange Server has implemented ICS using two collectors and two synchronizers. One collector/synchronizer pair is used for the hierarchy table of the folder being synchronized, and the other pair is used for the contents table of that folder.


Interfaces Used for Incremental Change Synchronization

The incremental change synchronization interface consists of three OLE interfaces:

  • IExchangeExportChanges provides the interface for the synchronizer (for both hierarchy and contents data).
  • IExchangeImportHierarchyChanges provides the interface used by the collector for folder imports (hierarchy table).
  • IExchangeImportContentsChanges provides the interface used by the collector for message imports (contents table).


About the MTA

The message transfer agent (MTA) provides the addressing and routing information for sending messages and distributing information through the system. Each MTA is associated with one information store. The Microsoft Exchange Server MTA conforms to the 1988 X.400 specification. The MTA is the engine for routing and transferring data between Microsoft Exchange Server systems or between a Microsoft Exchange Server system and a foreign system.


Relationship to MAPI Service Providers

When Microsoft Exchange Server sends a message, it relies on the MAPI subsystem to direct client requests to one or more transport-service providers. Windows DLLs serve as drivers for each transport provider. They also provide the interface between the MAPI spooler and the underlying messaging system or services.

MAPI defines three types of service providers:

  • Message store providers Supply message storage, organization, and retrieval facilities for a messaging system.
  • Address book providers Supply message addressing and distribution list facilities to the messaging client.
  • Messaging transport providers Move messages between messaging clients.

When a message is sent from a client application, MAPI.DLL responds to the common mail call (CMC) or MAPI call. MAPI then routes the messages to the appropriate message store and address book service provider. If a particular message is marked for sending, the message spooler checks the message’s address to determine which transport provider must be used to send the message. Depending on the designated message recipient, the message spooler may call upon more than one transport provider.

The spooler performs other message-management functions. It directs inbound messages to a message store and handles messages that are undeliverable because no transport provider can carry them. The spooler also provides an important store-and-forward function. The spooler holds the message in a store if the required messaging service is currently unavailable. When MAPI reestablishes connection to that messaging service, the spooler automatically forwards the message to its destination.

The Microsoft Exchange server information store offers more functionality than many other MAPI message stores. For instance, replication services are part of the Microsoft Exchange server information store. The replicated storage model allows the Microsoft Exchange server information store to distribute information within an organization without requiring users to know the location of the folders containing the information.


Application Design

This section presents information to help you design client and server applications that run with Microsoft Exchange Server. It begins with a brief discussion of the development options and continues with specific application design and development topics.


Microsoft Exchange Server Development Options

Microsoft Exchange Server provides a rich and complex development environment. The system is a MAPI service provider built on the Windows NT Server platform that employs the Active Messaging Library. You can use the following development tools:

  • Microsoft® Visual C++®
  • Microsoft® Visual Basic® Use Visual Basic with Active Messaging to access the Microsoft Exchange Server address book and information store, and to send and receive mail.
  • MAPI interfaces
  • Microsoft Exchange Server interfaces

Choosing the most appropriate tools depends on the application you plan to develop and the environment in which your application will run.


Client Extension Development Options

Instead of developing a separate application or a new user interface, you can extend the Microsoft Exchange Client. You can add command extensions, event extensions, property sheet extensions, and advanced search criteria, as discussed in the following topics.

Add Menu Commands to the Microsoft Exchange Client

Writing a client extension is the most common way to add menu commands to the Microsoft Exchange Client. A client extension can be created using several different methods:

  • Program the extension with Visual C++. This is the most common way to add functionality.
  • Use form verbs, which can be listed in the .CFG file used to install a form. The form will then appear in the Compose menu of the Microsoft Exchange Client.
  • Use the APPEXEC feature as a development shortcut. It provides backward compatibility with Microsoft Mail 3.x and launches an .EXE file from a menu command.

For more information, see the Microsoft Exchange Client Extensions Programmer's Reference.

Install and Use Customized Event Handling

You can build custom event handling into the Microsoft Exchange Client so the client can launch your application at the critical time during normal processing. Examples of events that can be synchronized with your application include:

  • Delivery of a new message
  • Reading of message properties (before or after)
  • Resolving an address (before or after)
  • Submitting a message for delivery (before or after)
  • Opening, reading, or writing an attachment

Visual C++ can be used to create customized event handling. For message delivery, the application can be tied to the MAPI spooler. For more information, see CRARUN: Creating a Custom Rule Action and Requesting Object Notifications.

Create Advanced Search Criteria

You can replace the advanced search criteria window with a custom search criteria window. Visual C++ and advanced search criteria extensions can be used to create this functionality. Keep in mind that only one advanced search criteria window at a time is available, so make the context for using yours as specific as possible.

Add a New Pane to the Viewer Window

You can add another pane to the Viewer window. The limits of Viewer window development are discussed in Client Application Development Options.

For complete information about developing client extensions, see the Microsoft Exchange Client Extensions Programmer's Reference.


Client Application Development Options

You can develop standalone applications for the Microsoft Exchange Client. The following topics discuss application development ideas.

Develop a New Viewer Window

You can use named views to change the columns, column order, grouping, sorting, and filtering on a folder. Development considerations include the following:

  • Only visible columns can be sorted.
  • Sort order is ascending or descending for the specific data type as originated or converted.
  • Sorting by one field only is allowed, but there are multiple grouping levels.
  • No specific functions for creating or editing views are exposed.

Any development tool can be used to create a new Viewer window. For more information, see the Microsoft Exchange Client Extensions Programmer's Reference.

Develop a Custom Client

You can create your own custom client interface to view a public folder by writing to MAPI. You can launch custom view windows from the Microsoft Exchange Client to obtain a simple level of integration. MAPI, Visual C++, and Visual Basic can be used for this type of development. For more information, see Building a Client Application.


Server Application Development Options

Many options are available to developers writing services for Microsoft Exchange Server. The following topics discuss development options for server applications.

Set and Manipulate Access Control List for Folders

You can set and manipulate access control list (ACL) entries on folders in the server store. (Note: This cannot be done from the Active Messaging Library.) Visual C++ can be used to set and manipulate ACL entries. See About Access Control Lists and ACLEDIT: Modifying an ACL.

Set and Manipulate Rules for Folders or Mailboxes

You can set and manipulate rules on inboxes or folders. Rules are evaluated by the server when incoming messages arrive. This action may take place immediately or be deferred until the client logs on. When you manipulate rules with your application, you can only specify actions that can be carried out by the server. Visual C++ can be used to set and manipulate rules. See RULEEDIT: Manipulating Rules.

Create and Delete Folders Using Your Application

You can create and delete folders using the Microsoft Exchange Client or MAPI. (Note: The Active Messaging Library does not support this functionality.) You can also make folders invisible on information stores. but not in the public folder hierarchy displayed by the Microsoft Exchange Client. To restrict visibility, the folder must be created beneath another folder that has restricted user permissions. See TOOLFORM: Creating a C or C++ Form and the Microsoft Exchange Server Application Designer’s Guide.

Create Custom Actions for Personal Folder Stores

You can create custom actions for a personal folder store (PST) based on rules. Custom actions are only available for PSTs because the necessary executable file must run on the client. However, the action could access the server-based information store. Most available tools can be used to create this type of application. See CRARUN: Creating a Custom Rule Action.

Create Custom Storage in Messages, Folders, and Directory Entries

You can create new fields and store information in a message. You can add named properties to a MAPI folder object, and you can add named properties to any directory entry. The Administrator program provides custom properties for some applications. You can also use MAPI and Visual C++ to create these application types. See EXTDATVW: Viewing and Editing Extension Data and Administrator Program_Extensions.

Create Customized Conflict Resolution for Forms

You can override the default conflict-resolution options provided with Microsoft Exchange Server. Such an application is attached to a form. Microsoft Exchange Server functions, MAPI functions, and Visual C++ can be used to create this type of application. See Resolving Message Conflicts with Forms.

Add Property Pages for Information Stores, Folders, or Messages

You can add property pages for the following objects:

  • Information stores
  • Folders
  • Messages

Visual C++ can be used to create new property pages. For more information, see Administrator Program_Extensions.

Tie Your Application’s Administration to the Administrator Program

You can control your application from the Administrator program by adding new property pages that manipulate objects exposed through the Administrator program. Microsoft Exchange Server functions and Visual C++ can be used to create these types of applications. See Creating an Administrator Extension DLL.

Create a Service with New Functionality

You can combine any of the other development options listed here to create new functionality for Microsoft Exchange Server. The Microsoft Exchange Server functions, Win32 functions, and Visual C++ can all be used. See Server Applications.


Forms, Schedule+, and Gateway Development Options

Forms, Schedule+, and gateways are applications that can be integrated into client and server applications. The following topics discuss application development ideas.

Developing Customized Forms

You can use Microsoft Exchange Forms Designer to create simple forms that are tightly integrated with the Microsoft Exchange Client through MAPIFORM.VBX and MSRICHED.VBX. The Forms Designer produces 16-bit Visual Basic 4.0 forms on both 16-bit and 32-bit platforms.

You can also use C or C++ to develop custom forms. These forms typically perform better than those developed using Visual Basic because you can use callback functions, have read/write access to the MAPI directory, and write 16-bit or 32-bit code. There is also client integration.

Installing Customized Forms

Forms can be manually installed by choosing the Forms Manager dialog box in the Microsoft Exchange Client. Forms will be automatically downloaded to the Forms directory at the client if the version is different. You can specify other forms to download by adding to the [Files] section of the .CFG file.

It may be necessary to create custom setup code for some types of client extensions or applications that must be installed. You can design a setup program that users run before using the application. You can also create a self-installing form that installs itself, runs, then deletes itself when it is invoked.

The Microsoft Exchange Server SDK provides helper routines to facilitate setting up a server application. Alternately, MAPI calls can be made to install a form. For more information, see INSTFORM: Installing a Sample Form

Replacing the Forms Manager

You can replace the Forms Manager with a custom application. (Note: Only one instance of Forms Manager can exist on any computer at one time.) MAPI or Visual C++ can be used to design a custom Forms Manager. See the Microsoft Exchange Server Application Designer’s Guide for more information.

Customizing the Schedule+ Interface

It is possible for an application to manipulate all Schedule+ objects, which include:

  • Schedules
  • Appointments
  • Attendees
  • Alarms
  • Events
  • Items
  • Projects
  • Tasks
  • Contacts

Automation (formerly known as OLE Automation), Visual Basic, and Visual C++ can be used to control Schedule+ objects. See Customizing Schedule+ Menus and Programmable Objects.

Using Schedule+ for Workflow Applications

Workflow applications are commonly used to manipulate Schedule+ objects. You can use Schedule+ objects to route a form based on the available times for each user. The routing can be tied to Schedule+ free/busy times. See the Microsoft Schedule+ Programmer’s Reference.

Writing Gateways to Other Mail Systems

You can write a gateway application to a foreign mail system. The Microsoft Exchange Server SDK provides a sample gateway that can be used or modified. See Sample Gateway and Applications .


Building a Server Application

Server applications extend the basic functionality of Microsoft Exchange Server. They can be used to provide a broad range of services, from mail gateways and voice mail to document management, content indexing, and electronic newspapers.

Server applications can be developed either as extensions to the Administrator Program or as stand-alone applications. Administrator extensions use the Administrator program interface and extend its functionality. Most standalone server applications are either mailbox agents or gateways. Mailbox agents are server applications that are accessed through a mailbox on a server. Gateways are interfaces with other mail systems. This section focuses on mailbox agents, but most of its concepts apply to gateways as well.

For complete discussions about server application development, see the following topics:

  • For information about writing a custom setup program for your server application, see Setup Programs.
  • For information on effective ways to access other user mailboxes from your application, see Information Store Operations.
  • For information on how to add new application-specific user information to the system, see Directory Operations and Administrator Program Extensions.
  • For information on gateways, see the Gateway Programmer’s Reference.


Administrator Extensions

You can extend the Microsoft Exchange Server Administrator program to include custom property pages, through which administrators can manage the application’s objects.

You can also create new data fields for a directory object, control these new fields through custom property pages, and manage this application-specific extension data. For more information, see Administrator Program Extensions.


Server Applications

Server applications can be mailbox agents, gateways or add-in applications. A server application should be implemented as a service of Windows NT Server. This means that the application is event-driven and can be controlled through the service control manager of Windows NT Server. It can function as an independent process before users log on, and it has an instance name to be used when logging on to MAPI.

When an application runs as a service of Windows NT Server, the service control manager is usually called to find its main function when it starts, to provide its messaging interface, and to tear it down gracefully when it ends. The interface with the service control manager can be handled in two ways: using Windows NT Server functions or using the WINWRAP library functions. For more information about the Windows NT Server functions, see Windows NT DDK Programmer’s Guide.

The WINWRAP library developed for Microsoft Exchange Server usually provides a more convenient way to handle the interface between a server application and the Windows NT service control manager.


Using WINWRAP Functions

The WINWRAP library (WINWRAP.LIB, with the WINWRAP.H header file) contains functions used to create a service from a Windows application without writing your own WinMain function and window message loop. The resulting application will be a Windows NT Server (32-bit) service.

WINWRAP defines a WinMain function that performs the following tasks:

  • Optionally creates a minimized service application icon on the desktop. To implement this function, pass NOTSERV and the name of the service from the Windows NT Registry.
  • Creates an hServiceStopEvent event object used to signal a shutdown of the service. This event object is initialized to FALSE (not signaled). You can get a copy of this event handle by calling the GetServiceStopEvent function.
  • Calls HrServiceStartup if the minimized window and hServiceStopEvent are created successfully. Otherwise it terminates the program.
  • Creates a new thread to run ServiceMain if HrServiceStartup returns TRUE.
  • Processes messages with the message loop.
  • Signals the hServiceStopEvent event object when the service is stopped or Close is selected from the system menu of the minimized service application icon.


Mandatory Entry Points and Variables

HrServiceStartup, ServiceMain, and HrServiceShutdown are functions you must write to match the prototypes given in WINWRAP.H. In addition, you must define the following global variables in the service’s code:

  • TCHAR szAppName[];
  • TCHAR szWindowTitle[];

For example, the XLATDRIV sample application defines these variables as follows:

TCHAR szAppName[]        = TEXT("XLATDRIV");
TCHAR szWindowTitle[]    = TEXT("Message Translation Sample");

HrServiceShutdown is called for every successful call to the HrServiceStartup function.


Events Signalled

The following handles to events are created by WINWRAP when the corresponding Pause, Continue, or Stop events are detected.

  • hServicePauseEvent
  • hServiceContinueEvent
  • hServiceStopEvent

These events are automatically controlled through the service control manager of Windows NT Server. Call HrServiceProcessControl periodically to allow the user to pause, continue or stop your service from the service control manager. HrServiceProcessControl will return EDK_E_SHUTDOWN_SERVICE if the service has been stopped.

When the hServiceStopEvent signal becomes TRUE, your application should exit. Remember to call HrServiceConfirmStop before exiting ServiceMain to notify WINWRAP that HrServiceShutdown can safely be called. The return value of HrServiceShutdown is used as the WinMain exit code.

If it is ever necessary to force the shutdown of the service, use ServiceStop rather than manually signaling hServiceStopEvent. An example would be if the service encounters an unrecoverable error and cannot continue.


About Mailbox Use

Mailboxes can be handled by server applications in three different ways:

  • Maintains a separate mailbox Most server applications are either mailbox agents or gateways that maintain their own mailboxes in information stores on Microsoft Exchange Server.
  • Accesses other mailboxes Server applications can use mailboxes other than their own with delegate access and privileged access. For information on privileged access, see Information Store Operations.
  • Uses no mailbox An application can be configured as an add-in service that has no mailbox.


About Mailbox Agents

Although the objectives and tasks of Microsoft Exchange Server servicesvary, they share a common information structure because they use standard interfaces and common objects. The following figure shows a simplified view of this common information-exchange structure as it applies to a mailbox agent.

Interfaces between a mailbox server, a client, and a mailbox on Microsoft Exchange Server

  • The main components and objects pictured in the diagram are defined below.
  • User’s client application Can include unextended Microsoft Exchange clients, custom-built applications, and extended versions of the Microsoft Exchange Client.
  • Mailbox agent process A server application that provides server functions and communicates using a mailbox on the information store. Mailbox agents may also include a public folder for information sharing.
  • Information store Acts as the primary information database for Microsoft Exchange Server.
  • Inbox Receives messages from users for the application.
  • Outbox Stores and sends messages to users from the application.
  • Public folder Folder within the information store that contains information to be shared with application users. Because of their flexibility and power, public folders are suitable for almost any kind of information-exchange application.

For information about this type of server application, see SMBAGENT: Creating a Sample Mailbox Agent.


Communication with Microsoft Exchange Server

Server applications communicate with Microsoft Exchange Server components through MAPI. This communication includes actions such as:

  • Using the address book

    (See Using MAPI with Directory Objects)

  • Accessing information stores

    (See Opening an Information Store)

  • Accessing public folders

    (See Opening an Existing Public Folder)

  • Transferring messages

    (See Message Transport Features

Special functions included with this SDK were developed specifically for communication between server applications and Microsoft Exchange Server. Some of these functions extend MAPI functionality, some enhance debugging capabilities, and others add completely new functionality.

To provide their service, most server applications must communicate with directory objects and information store objects. Depending on their functionality, many server applications must communicate with the Administrator program and Administrator extensions as well. The following illustration shows the primary ways a server application communicates with Microsoft Exchange Server components, including information stores, mailboxes, the directory, and the Administrator Program.

Server application and Microsoft Exchange Server communications

  • For information on how to access the Microsoft Exchange Server directory, see Directory Operations.
  • For information about using public information stores and public folders, see Information Store Operations.

A server application is not required to run on the same computer as the Microsoft Exchange Server software. Most server applications use MAPI, which is an RPC interface and can therefore be used over a network connection. This means the server application is not required to share a processor with the server, which can improve performance as long as the number of RPCs is kept small. Efficient use of MAPI, along with sparing use of RPCs, improves the performance of distributed processing architectures. For more information about performance considerations for server applications using RPCs, see Reducing the Number of RPCs.

Receiving Mail Messages

Once a mailbox agent or gateway has been installed, a corresponding Mailbox-Agent or Mail-Gateway object exists in the directory, which provides an address and the ability to receive messages. Even if a server application is not specifically designed to receive or handle messages, it’s a good idea to let users or administrators check for received messages. The ability of an application to receive mail can also be helpful when troubleshooting. For example, you can design a gateway application that forwards all messages that meet certain requirements and holds back those messages with inadequate or unrecognized addresses. These held-back messages can reside in the gateway’s own mailbox until an administrator or developer examines them and diagnoses the problem. A MAPI profile provides the ability to log on to a mailbox. For more information, see Creating a MAPI Profile for a Server Application.


Example: Building a Server Application

One way to explain some of the considerations for building a server application is to use an example and demonstrate some of the special functionality in the system.


How a Voice Mail Server Works

A voice mail server stores messages and makes them available when the user dials into the system. The user communicates with this application in the following manner:

To use a voice mail server
  1. User calls the voice mail access number.
  2. Voice mail server application answers and plays the welcome message.
  3. User keys in an ID number (an office telephone extension number) and a PIN.
  4. When the user is identified, the voice mail system reports the number of unread messages in the user's mailbox.
  5. User keys in a request to hear the sender and subject line of each message, or a subset of messages.
  6. User has the option of listening to the complete message or sending it to a fax gateway.

The Windows NT account of the voice mail application is assigned read-only access to mailboxes. In other words, an administrator grants the privilege of reading all the messages in the mailboxes to this account. When the voice mail application logs on as the Windows NT account, it can read all the mailboxes on the messaging site. (Applications of this type are granted some of the rights normally reserved only for administrators.)

The following diagram shows interactions of this voice mail system.

Architecture of a voice mail application

If a user chooses to send a message by fax, the application must forward the message to a fax server. First, MAPI creates the message, then assigns a destination address to the message, using FAX as the address type (FAX:xxxxx). The phone number of the destination fax machine is supplied as the address value. The message is submitted by calling the MAPI IMessage::SubmitMessage method.

After the message is submitted, Microsoft Exchange Server routes it to the FAX gateway, which puts the message into FAX format and sends it to the destination fax machine.

This voice mail application shares several other characteristics with common types of server applications.


Finding a User's Mailbox

Finding a User’s Mailbox

When the voice mail user has dialed in, provided numeric identification to the voice mail application, and requested to hear messages, the application must find the mailbox associated with that number. Microsoft Exchange Server provides many directory attributes for search criteria, any of which can be used by the application to perform ambiguous name resolution (ANR).

One way the voice mail application can quickly find the mailbox associated with the numeric identification is by using proxy addresses. Proxy addresses are e-mail addresses by which the mailbox is known to the outside world. They have the form AddressType:Address. Because proxy addresses are indexed, mailbox lookups are very fast. For the best performance, the voice mail application can create a custom proxy address for every voice mail user with a format such as VOX:123456, where VOX is the AddressType for this application, and 123456 is the voice mail user’s access number. When the user typs in 123456, the voice mail application constructs a lookup address VOX:123456 and performs a proxy address search. This search returns the distinguished name of the desired mailbox, which can then be used to gain administrator access to the mailbox.

When the voice mail application has gained administrator access to the mailbox, the voice mail password is checked. For more information, see Directory Operations and Administrator Program Extensions.

For more infomation about creating DLLs to automatically generate proxy addresses, see the Gateway Programmer’s Reference.


Multiple Threads and MAPI Sessions

If your voice mail server is connected to a number of phone lines, you may want to use multiple processing threads to service incoming calls. Once you have created a MAPI session, this session can be connected to only one mailbox at a time. If the voice mail server must handle twenty incoming calls at the same time, twenty MAPI sessions must be created.

Multiple MAPI sessions are able to access multiple mailboxes simultaneously by using a thread for each interaction. When the number of threads exceeds a certain limit (perhaps fifteen to twenty threads), context switching between threads begins to lower performance. The solution is to separate the user’s perception from the software that is actually executing. When a user asks to hear a message, instead of allocating a dedicated mailbox thread to that request, the request is queued for processing by one of a smaller number of mailbox access threads.

When the mailbox access thread is free, it opens the mailbox associated with the message, locates the message, and passes the message to a message reader thread that reads the message over the telephone to the user. This implementation gives good performance. Users tend to pause a long time between mailbox accesses while listening to messages and instructions, so a single mailbox access thread or message reader thread can easily handle mailbox access for many users.

Add well-designed caching, such as saving the contents tables for all the users currently online, and the application becomes even more efficient.

The MBLSAMPL sample application demonstrates privileged access by opening an information store and logging on to multiple mailboxes. Its sample code shows you how to specify the recipient’s name whose mailbox you want to access, and if successful, how to determine the number of new messages.

Special handling of messages is necessary in a multithreaded environment to avoid long-term blocking. A console application or a Windows NT service that is a MAPI client may need to handle messages in an initialization thread. To do this, the application must perform the following tasks:

  1. Call MsgWaitForMultipleObjects when the main thread blocks.
  2. Call the GetMessage, TranslateMessage, and DispatchMessage sequence of Win32 functions to handle the message when MsgWaitForMultipleObjects returns the sum of the value of the nCount parameter and the value of WAIT_OBJECT_0, indicating that a message is in the queue.

For more information about creating multithreaded applications, see Using MAPI in Multithreaded Applications.


Building a Client Application

A client application is a program that runs on a user’s computer, communicates with Microsoft Exchange Server, and is controlled through a user interface. Most client applications interact with Microsoft Exchange Server by retrieving data from the information store, placing information in a public folder, or manipulating messages to be sent or posted. A third-party client application may perform actions similar to those of the existing Microsoft Exchange Client, or it may supply new functionality.

It is not necessary for a client application to be accompanied by a server application. For example, a hypothetical application could be started by double-clicking its icon like any other Windows application. The application could then log on to Microsoft Exchange Server, gather information from a public folder, and display the information. One of this application’s tasks may be to check the Windows NT Registry and determine the correct information to gather and display for a particular user.

Microsoft Exchange Server can support client applications that run independently — whether or not the Microsoft Exchange Client is running at the same time. Such client applications are set up to operate directly through MAPI and to connect their logons to an active Microsoft Exchange Server application that is MAPI-compliant. The application can then interact with information in the Microsoft Exchange Server information store and manipulate information stored and distributed by Microsoft Exchange Server.

The following factors may indicate that a standalone client application is appropriate:

  • Your application presents users with a different user interface than Microsoft Exchange Clients, but provides access to Microsoft Exchange Server information.
  • Your application presents Microsoft Exchange Server information in a different way than users normally encounter. In this respect, Microsoft Schedule+ is a good example of a client application. Scheduling information is stored and distributed through replication by Microsoft Exchange Server, but the context in which it is presented differs from Microsoft Exchange Clients.


Starting a MAPI Session

Like a server application, a client application uses profiles to log on to MAPI. However, a server application creates its own profile while a client application often uses the user’s existing profile on the client computer. In other words, if the user is already logged onto Microsoft Exchange Server, the client application can obtain a MAPI session from a logged-on user. This means that the client application actually connects to an existing session, which makes its startup cleaner and faster.

You can set up your client application to log on and log off using its own MAPI session instead of connecting to an existing session (such as a Microsoft Exchange Client session). For example, the client application would be required to log on explicitly if no sessions are currently active. An application may also deny connection of other clients onto its session.

MAPI provides and displays a profile dialog box that allows a MAPI logon. This interface can be bypassed by using the appropriate MAPI flags, provided the client application knows the name and password of a profile to be used. Settings such as the profile name and user passwords are saved for each provider in the profile that resides in the registry on the user’s computer. This occurs in Windows NT Server and in Windows 95. When the client application calls the MAPILogonEx function, MAPI first looks for a list of profiles in the registry on the client computer.


Installing Client Applications

It is important to provide users with a setup program for client applications and their extensions. For more information, see Setup Programs. Setting up client extensions requires specific techniques, which are discussed in the Microsoft Exchange Client Extensions Programmer’s Reference.


Using MAPI in Multithreaded Applications

A thread is the basic entity to which a 32-bit 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 and service providers such as Microsoft Exchange Server 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 is used only on the thread that created it.
Free threading (thread-party) model | An object is used on any thread.

MAPI and MAPI service providers use the free threading model, supporting thread-safe objects that can be used on any thread at any time. The current version of OLE uses the apartment threading model. The apartment threading model supports objects that must be explicitly transferred when a thread that did not create an object uses that object.

The mechanism used by OLE to transfer objects from one thread to another is known as marshaling. Marshaling involves a stub object and a proxy object. These 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 LRPC (Lightweight Remote Procedure Call). 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 helps prevent problems between clients and service providers.

A MAPI object can be accessed in the following ways:

  • 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

Client applications and service providers 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 MAPIOpenFormManager. 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 open a status object by calling OpenEntry with that entry identifier. 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 objects. Status objects obeys apartment model rules and clients must use them only on the thread that created them.

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 DLLEntryPoint 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. Clients should not require the DLLEntryPoint functions because the MAPI service provider interface has its own initialization and deinitialization entry points.

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 marshalling the object.


Implementing Thread-Safe Objects

With objects that are returned from interface method calls directly, it is the service provider’s responsibility to ensure thread-safety. With callback objects, it is the client’s responsibility. A service provider implements a thread-safe object by serializing access to shared data within the object, ensuring that one thread does not inadvertently replace the work of another thread. A service provider can implement serialized access to data in three ways:

  • Provide every object with its own critical section by calling the Win32 EnterCriticalSection function at the beginning of every method call and the LeaveCriticalSection function at the end. Most samples in MAPI use this method. This option has two drawbacks: high overhead and the possibility of deadlock. For example, deadlock can occur if the thread-safe object calls either the MAPI support object or an object returned indirectly through one of the copy methods.
  • Use a single critical section for all objects, calling EnterCriticalSection when the provider is loaded and LeaveCriticalSection when the provider is unloaded. This option is the simplest, but performance suffers when it is used with multithreaded clients.
  • Create a small number of critical sections to be associated with crucial shared data structures. The data is isolated from the object, placed, for example, in memory or in a parent object. Access to the data is handled through an internal interface. This option offers the best balance between performance and simplicity.

A client can implement a thread-safe notification callback by calling the MAPI HrThisThreadAdviseSink utility, which transforms a non-thread-safe advise sink into a thread-safe one. (There is no such utility at this time for progress callbacks.) A client can choose to use the MAPI thread-safe progress object or create one manually.

A thread-safe object may or may not 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 is useful in some situations. Two MAPI tables always provide their own context by definition. A single table used on more than one thread does not and should not provide a 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 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_NOTIFY. 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.


Options for Memory Management

Selecting memory allocation functions is an important step in the design of an application for Microsoft Exchange Server. You can choose from several strategies when selecting a design for memory allocation. Important considerations include the following:

  • Memory allocation strategy may be determined by the interface you use for development. For example, MAPI functions such as PrepareRecips and ResolveNames require the use of MAPI allocation functions. You will need to consider other development options if these allocation functions do not meet your needs.
  • Memory allocation can have a great effect on performance, depending on the type of application and the memory allocation strategy. Negative effects can result from serialization of critical sections, fragmentation of heaps, repeated allocations, and overhead.
  • Memory allocation strategy differs according to the type of application you are developing. For example, performance is very important to a service that is tied to the scalability and performance of Microsoft Exchange Server itself, and less important for the interactive functions of a client application.
  • Memory allocation sometimes results in memory leaks.
  • Multithreaded applications and multiprocessor systems require special consideration for memory allocation.
  • Client applications may need to run on both 16-bit and 32-bit systems.

Serialization is an important consideration when choosing memory allocation functions. It occurs when a process must lock out all other processes while a critical section executes. This means that one process must complete all its transactions before the next process begins.

When a large number of such critical sections try to access a process at the same time, performance is affected. Such a process is said to be serialized. Serialization is a rate-determining step — a factor in computing the rate of throughput. If all the processes in a system must spend time in a memory allocator, the performance of the system as a whole is determined by the performance of the memory allocator.


Memory Allocation for Client Applications

The most important considerations for client applications are the following:

  • Portability
  • RPC serialization
  • Performance

For most client applications (and interactive applications in particular), heap performance and serialization are not as great a factor when the application is run only on the client. They become more important when remote procedure calls (RPCs) are involved.

MAPI provides three functions that manage memory in a consistent way. MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer enable client applications and service providers to exchange blocks of memory. MAPIAllocateBuffer is called initially to allocate memory for a buffer; MAPIAllocateMore can allocate another block of memory that is linked to the initial block.

When both client applications and service providers use these functions, whoever owns and is able to release a particular block of memory is no longer an issue. The service provider can simply allocate memory blocks and the client can later release them at will, independent of the service provider.

If the application has unusually high performance requirements, be aware that the MAPI allocation functions are serialized and do not offer control over the locality of allocations. Both of these factors can impair the performance of multithreaded applications. Use the Win32 memory allocator functions in this case.

Another thing to consider is that the very convenience of the MAPI allocators can affect performance. For example, MAPI providers always return memory allocated using MAPI allocators. So every time a call is made to IMAPIProp::GetProps, IMAPITable::QueryRows, or any MAPI functions, the memory is released and must be reallocated for the next call, so the client allocator itself is serialized if it is a MAPI allocator.

For general applications and most interactive ones, the CPU overhead incurred by the heap allocator is negligible. The difference in performance between the MAPI allocator and other allocators is also negligible. This includes many client applications and a few server applications that perform logging, reporting, link monitoring, and other tasks where flexibility and simplicity are more important than throughput.

Special consideration is required for 16-bit client memory allocation. Using the Windows 3.11 heap allocator may not be appropriate for your Microsoft Exchange Server client applications. The Win32 LocalAlloc function relies on a fixed-size heap in the application’s data segment and is too small for most usage. The Win32 GlobalAlloc function returns a new segment for each allocation, and only a limited number of segments are available, so it may not be a good choice for your application either. If your application must cover all platforms, MAPI allocators are often the best choice for local heap implementation. OLE allocators can also be used.

The C runtime function malloc has low overhead, but requires that memory is specifically freed. This function may be useful for applications if regular calls to the _heapmin function can be made. MAPI providers should never use malloc because they cannot predict when they will be called by the client. MAPI allocators support linked allocations, while OLE allocators do not. OLE supports resizing blocks, while MAPI does not. The 16-bit OLE allocator is not tolerant of a large number of allocated segments when the application itself has significant overhead.

For 32-bit clients, either HeapAlloc, VirtualAlloc, or a custom memory manager should be used, depending on whether there are special performance requirements for the memory manager.


Memory Allocation for Server Applications

Server applications are rated by their throughput numbers and by the number of simultaneously connected users they can support. Therefore, performance is the most important consideration. Minimizing the effects of memory allocation functions on performance requires an understanding of the unique interactions of such a system and time spent tuning the system based on these unique interactions.

Important issues include the following:

  • Locality of reference (how many memory pages are touched)
  • Scalability on multiple CPUs
  • Fragmentation
  • Serialization
  • Matching the memory allocation characteristics of an application to its environment
  • Considering multiple threads and multiple processors and their effect on the performance of memory allocation functions
  • Matching the memory allocation characteristics of an application to its purpose

For a server application, the choices include the MAPI allocator functions, the Win32 HeapAlloc or GlobalAlloc functions, or writing allocator functions specifically for the application.

MAPI requires the use of MAPI allocators for certain allocations. When MAPI allocators are used and several very busy threads must make MAPI calls, there will be serialization and reduced performance.

The MAPI allocators do not give the application control over the placement of memory blocks, which makes it impossible for the application to tune locality. The MAPI allocators always serialize through a critical section on a common heap because they can make no assumptions about how they will be called. Besides adding CPU overhead, this can dramatically impact the scalability of a multithreaded server.

There has been considerable analysis of how Win32 memory allocator functions behave in the information store process. Fragmentation has not been shown to be a problem with a single heap. Win32 functions give good performance in coalescing free blocks and packing new allocations into the right place. The information store, however, is heavily serialized with a single heap. Using the multiple heaps available with some other allocation strategies virtually eliminates this contention.

Because calls to the MAPI functions PrepareRecips and ResolveNames reallocate memory in ADRENTRY, it is likely that the MAPI allocators must be called if an ADRLIST is used in your application. Because of this, at some point in a multithreaded application there will be multiple threads trying to access the one Microsoft Exchange Server directory heap available to MAPI client applications. The contention for this heap will have an adverse effect of performance. To see if this is affecting your application, count the number of allocations per hour against the number of threads using MAPI allocators. A gateway is an example of an application that is very likely to use PrepareRecips and ResolveNames.

Server applications do not normally use the OLE IMalloc memory allocation function except where required by OLE interfaces.

The malloc and free C runtime functions cause problems for server applications in two ways. First, unless the Visual C++ 4.0 version is used, free does not return memory to the operating system. Unless the application is able to call _heapmin periodically, its virtual memory consumption will grow without bound. The C++ new and delete operators use malloc by default. Overhead-conscious server applications written in C++ should always overwrite the new and delete operators. Whether to replace them with a new pair of global operators that call HeapAlloc, or to implement smarter class-specific operators, depends on how the application organizes its object lifetimes. The malloc and free memory allocation functions as implemented in Visual C++ 4.0 actually call HeapAlloc and HeapFree functions respectively. If that version is used, there is no problem with returning freed memory to the system.

Another option to consider is a package of memory allocation functions written for your application, which can implement multiple heaps serialized outside the HeapAlloc and HeapFree functions. Such a package can eliminate almost all heap contention by tracking which heap is busy and always trying to steer allocations to non-busy heaps. This is useful for per-thread heaps. When the heap is created, the parallelism can be specified, which controls the number of heaps.


Performance Considerations in Memory Management

How an application uses its chosen memory allocators is just as important as choosing them in the first place. An application that spends a significant portion of its time in the heap allocator is not well-designed. It should be using custom allocators to create objects with less overhead.

Multithreaded server applications can use the following features of HeapAlloc to improve their performance:

  • Give a thread its own heap (locality) if its dynamic memory needs warrant this.
  • Use the HEAP_NO_SERIALIZE flag to the Win32 HeapAlloc function to eliminate critical section waits and improve scalability. If you use this flag, however, you must manage heap access yourself or risk corrupting the heaps.
  • Eliminate the need to free individual items by creating a temporary heap and destroying the heap when done. This saves overhead and gives more locality, thus improving performance.
  • Eliminate the overhead of checking for memory allocation failure by using the HEAP_GENERATE_EXCEPTIONS flag to HeapAlloc, and handling memory allocation failure as an exception.
  • To maximize performance by increasing locality, it may still be necessary for the application to create custom allocators for various types of objects. Using HeapAlloc alone may not suffice.

Another C runtime function, _alloca, should be used instead of the heap allocator when the item to be allocated is of function scope, requires only short-term memory use, and its size can vary. The _alloca function simply extends the function’s stack frame, so it is very fast. When the function returns, the allocation evaporates.

It is not unusual for applications that run well on single processor systems to degrade in performance on a multiprocessor system. This is almost always the result of excessive contention for locks, particularly for critical sections. The Win32 GlobalAlloc function, the OLE IStorage and IStream functions, and similar allocator functions all use critical sections for synchronization. For a single processor system, it is very rare to find contention on these critical sections since the thread that owns the critical section is unlikely to be preempted. On a multiprocessor system, such contention is much more likely since more than one thread is running simultaneously.

The easiest way to determine whether an application is having trouble with contention is to run the application first on a single processor machine and then on a multiprocessor machine and compare the context switches per second and the system calls per second. These will both increase when there is contention. When there is no contention on a critical section, it is very fast and requires no context switching or system calls. When there is contention (one thread tries to acquire the critical section while another thread holds it) additional system calls and context switches are required in order for the requesting thread to wait until the owning thread has released the critical section.

Other interesting statistics that can uncover a performance deterioration because of an allocation problem are the number of context switches per transaction and the number of system calls per transaction. If these numbers change dramatically with the number of processors or the amount of load on the system, there is probably an allocation problem with the application.


About Source Extractors

A source extractor can export directory information, mailboxes, personal address book (PAB) entries, personal distribution lists, mail messages, attachments, calendar data, and public information. Microsoft Exchange Server provides source extractors for many popular systems. If a source extractor for your system does not exist, you can create one to copy information from your system to migration files. You can then use the Migration Wizard to import the information to Microsoft Exchange Server. For more information, see the Microsoft Exchange Server Migration Guide.

Creating and using a source extractor involves the following activities:

  • Designing your source extractor
  • Formatting the migration files
  • Editing the migration files
  • Troubleshooting errors

About Migration Files

A source extractor must create the following three types of migration files:

  • Packing list file Lists primary and secondary files and specifies the code-page for all migration files.
  • Primary files Contain directory information, message headers, personal address book entries, personal distribution lists, and pointers to secondary files.
  • Secondary files Contain blocks of data, such as message bodies, attachments, and schedule data.

The following figure shows the relationships between the migration files.

Each migration file contains one or more types of objects, as described in the following table.

Objects | Purpose
Custom recipient addresses | Creates custom recipients.
Mailbox names | Creates mailboxes, replacing custom recipients when correctly configured.
Mailbox data | Imports messages into the Microsoft Exchange Server mailbox.
PAB data | Imported as a message in the Inbox for users to recreate their personal address book entries.
Public data | Creates public folders, imports data, and assigns the current administrator as owner.
Scheduling data | Creates a schedule file, attaches the file to a message, and imports the message.

For information on the format required for migration, see Migration Files.


Designing a Source Extractor

You must consider many issues when designing your source extractor. For example, your source extractor will ideally extract a reasonable amount of data overnight. If you have international users, the source extractor should be easy to localize and should include appropriate code-pages. You should also consider these questions:

  • What level of sophistication is required to install and configure the source extractor?
  • Does a user-driven source extractor make sense?
  • Where are the files going to be edited after export and before import?
  • How will the files be transferred from the extract location to the import location?
  • Will file transfer modify the files?
  • Is the existing system going to be in use?

Also consider the following additional issues when creating your source extractor:

  • Existing data If possible, copy, don’t move, the data from your existing system, so that you will have an additional copy of the data.
  • Group migration If your existing system has account information in the directory, select accounts to migrate by department or location.
  • Permissions Administrator or user authentication should be required to copy data from the source system.
  • Primary mailbox files Mailbox files need to be edited if you’re changing the directory name. It is best to put all the directory entries into one primary file.
  • Mailbox names You cannot change the common or directory name of a mailbox after you create it. If you have a new naming convention, modify every primary file that contains mailbox creation information, or modify the source extractor to select the new directory names from a file.

You should also consider each of the following issues:

  • Choosing the addressing conventions
  • Choosing information to extract
  • Configuring command-line options
  • Configuring special features

For more information, see the Microsoft Exchange Server Migration Guide.


Choosing the Addressing Conventions

The Migration Wizard can use three different types of addresses. For more information on the Migration Wizard, see the Microsoft Exchange Server Migration Guide.

Display Name

The display name is the friendly name of a recipient. Source extractors should convert message recipients, senders, and appointment attendees to display names. The Microsoft Exchange Client compares the display name with personal and global address list entries. If it cannot find a match, it displays possible matches for the user to select from.

E-Mail Address

Source extractors use unique identifiers to relate each mailbox or custom recipient in the existing system to each mailbox or custom recipient in Microsoft Exchange Server. These identifiers are known as source e-mail addresses and are stored in the following format: Migrate:TYPE:address.

This address is created in the directory section of the primary file and must be in a column with a header of secondary-proxy-addresses. You can remove the Migrate e-mail addresses after migration is complete.

E-mail addresses are also used for personal address book (PAB) entries. By default, the following address types are valid: MS, MSA, X400, and SMTP. Other gateway address types can be made available. Microsoft Exchange Server defines an address for a foreign system recipient in this format: TYPE:address. For example: SMTP:alig@eur.fab.com

When extracting addresses from foreign systems, your source extractor must create a target address, or extract the address as a direct address.

Also consider these PAB addressing issues:

  • Do you remove addresses from mailboxes on the existing system?
  • Do you change the display name to include the address?
  • Do you change the addresses to route mail to the appropriate gateway?

Display Name with E-mail Address

The source extractor can use display names with e-mail addresses. Use this format only for addresses not in the Microsoft Exchange Server global address list. For example: Allison Klein[SMTP:AKlein@eur.fab.com].


Choosing Information to Extract

When planning your migration, consider which data to extract. For example, you may or may not want to extract schedule and calendar features or personal distribution lists. You may want to limit the extraction to certain ranges of data. For example, you could impose an age limit on mail. Also consider the special issues that related to extracting the following information.

Personal Address Books (PABs)

If users can create their own directory entries in personal address books (PABs) on your existing system, you can extract the information. If the administrator cannot access PABs, consider how users will migrate this data. You can have users compose messages to all their PAB entries, type their own names in the Copy To (Cc) fields, and send the messages before their mailboxes are moved. The messages are then migrated to Microsoft Exchange Server, where users can open the messages and add the recipients to the new PABs.

Attributes

Some existing systems have additional data about each account stored in their directory — title or department, for example. Extract this information as part of migration, or import it separately by using the Directory Import command in the Administrator program.

Attachments

Is the attachment useful after being migrated? Attachments that require an application on a host system may no longer be useful in their current format. Do any attachments need to be converted before being added to the migration file?


Configuring Command-Line Options

For automation, compatibility, and ease of use, configure the source extractor to support the following command-line options:

  • Batch control file
  • Accounts file
  • Administrator account and password

If the operating system of the source extractor does not support command-line options, you can design the source extractor to find batch control and accounts files with default names.

The batch control file has one required variable: the accounts file. Some optional variables are detailed in the following table. Depending on your existing system, some of these variables may be required, and others will be useful.

Variable | Description | Suggested default value
Accounts (Required) | Path and file name of the accounts file. |
File | Path and file name of the packing list file to be created. |
Mailbox | Mailbox creation information. | TRUE
Email | Private messages from the accounts. | TRUE
Remote | Custom recipient information. | FALSE
Public | Public messages and bulletin board information, if supported. | TRUE
PAB | Personal address book (PAB) entries and distribution lists. | TRUE
Schedule | Schedule and appointment data. | TRUE
EmailStart | Earliest date to retrieve messages. Migration file date/time format. Required if using EmailEnd. |
EmailEnd | End date to retrieve messages. Migration file date/time format. Required if using EmailStart. |
SchedStart | Earliest date to retrieve appointments. Migration file date/time format. Required if using SchedEnd. |
SchedEnd | End date to retrieve appointments. Migration file date/time format. Required if using SchedStart. |

The order of variables in the batch control file is not important. Mailbox and Remote are mutually exclusive. Each variable has its own line, followed by a comma and the value for that variable. Each line ends in a line feed and carriage return. The following examples illustrate the correct format.

  • Control file that does not migrate schedule information and limits e-mail messages to a date range:
    Schedule,FALSE
EmailEnd,19950323000000
Accounts,C:\PO7User2.txt
EmailStart,19940413171900

  •
Control file that limits schedule data, but imports all e-mail messages:
    Accounts,M:\migrate\batch\user.txt
SchedStart,19940101000000
SchedEnd,19970101000000
LogLevel,Verbose
Public,FALSE

    •

The accounts file in the preceding example specifies the mailboxes or accounts from which to copy data. It is useful when running in batch mode or when migrating many users. The accounts are listed by their source addresses or by a unique identifier. Each accounts file should contain accounts from only one system, postoffice, or server. The following example illustrates the correct format:

Stephanie Bourne
Karl Buhl
Paul Canniff


Configuring Special Features

You may want to configure your source extractor to perform certain activities. For example, it is advisable to configure both an error log and online Help, which can help troubleshoot problems. Also consider configuring the following features:

  • Mail forwarding You can configure the source extractor to forward mail, depending on your existing system’s features.
  • Special migration folder If you configure this folder, only messages in the folder and in the Inbox are migrated.
  • Status file To prevent a mailbox’s contents from being imported twice, configure your source extractor to keep a log of migrated users.
  • Last message configuration A message informing users that their new mailboxes are available and not to use the old mailboxes anymore.


Editing Migration Files

You can edit migration files to change or add data. You edit the primary files after they are extracted and before they are imported with the Migration Wizard.

Important Editing the secondary files is not recommended. Changes to secondary files require recalculating all offsets and then updating the primary file.

You may want to edit the primary files for the following reasons:

  • To change the common names of mailboxes. You can only do this before the mailbox is created.
  • To make the aliases different from the common names.
  • To change the display name format.
  • To parse the display name to generate the given name and surname fields, depending on the configuration of your source extractor.
  • To add additional fields and data (telephone numbers, department names, and other items) to the directory.
  • To delete all messages sent before a certain date if your source extractor doesn’t support the limiting of messages.

Important Editing migration files can introduce invalid or incorrect data. Make a backup of all migration files before editing them.

You can avoid editing the primary file by configuring the source extractor appropriately. For example, you can configure the source extractor to create given names and surnames, or to accept a text file of the old mailbox names and their new Microsoft Exchange Server common names. Use the following procedures to modify common names.

To modify the common names of mailboxes
  1. Configure the source extractor to create files with mailbox creation information only.
  2. Modify the small primary file, and then use the source extractor to create migration files that don’t need editing.
  3. Import the smaller mailbox creation files, and then import the mailbox data files.

You can also use the Directory Import and Directory Export commands instead of the Migration Wizard to import data. You can use these commands to change the display names, addresses, given names, surnames, and other mailbox properties.

Important Some primary file fields may exceed 255 characters, but some spreadsheet programs can’t hold more than 255 characters in a cell. The extra characters may be truncated without notice, causing a loss of data.


Troubleshooting Errors

If errors occur during the import of migration files, the Migration Wizard logs errors to an application log and importing may stop. If importing continues, the error is written to a recovery file. A recovery file is created each time files are imported. The recovery files are written into the Temp directory of the computer running the Migration Wizard.

Therefore, if an error occurs, first check the application log and the recovery file. One error in the file format can cause multiple or cascading error messages. If the error can’t be found in the line with the error report, an error in a previous line might be causing the problem, or there may be an improper offset to the secondary file.

If it is a primary file error, you can edit this file and fix the problem. If it’s a secondary file error, you get a pointer to the problem, which you can attempt to fix. If you must edit the secondary file, make a backup first. Be careful not to change the offsets of later sections. After all problems are fixed, you can create a new packing list file that lists the primary and edited (not original) secondary files.

File Processing

If you understand how the Migration Wizard processes the files, you can troubleshoot problems. The Migration Wizard first reads the packing list file and then starts processing the first primary file. The following table describes how each primary file is processed.

Section | Processing
Directory | Every line after the directory header line until the start of the next section is passed to the directory import DLL one line at a time.
PAB | Each line of personal address book (PAB) data is read. After all lines are read, a message is created.
MailMessage | If the mailbox does not exist, it is created by custom recipient conversion if possible. If a message is for public folder, it is created with appropriate permissions if necessary. For each line, a message is created. The secondary file is checked for body and attachments. If body is empty and there is a document, the attachment to mailbox is copied as a free document. If body is empty and there is a schedule file, the body is supplied by the Migration Wizard and the attachment is added.


Troubleshooting the Primary Files

If you can’t find anything wrong with the primary file lines with error reports, trace errors with the following procedure:

To check for errors in a primary file
  1. Make a backup copy of the original migration files.
  2. Edit the primary file to remove all lines with error reports.
  3. Import the edited files.

    Error reports can now be eliminated. However, if errors are still reported, the errors are in the previous lines. The errors in the previous lines did not stop the importing, but did cause problems in the next lines.

  4. Make a copy of the backup migration files.
  5. Edit the primary file, removing the lines previous to the lines with error reports.
  6. Import the edited files.

    The error reports can now be eliminated.

  7. If errors are still reported, repeat steps 4 through 7, removing lines previous to the lines removed in the last test.

Once you identify the problem lines, see how they differ from lines that were successfully imported, or how they differ from the proper migration file format.


Troubleshooting the Secondary Files

You cannot edit a secondary file if the edits will change the offsets. Adding or removing even a single character from the secondary file can cause errors when later importing objects. If you edited a secondary file and then get errors when you try to import it, replace the edited file with an unedited backup copy.

If you did not edit the file, first examine the application log and the secondary recovery files. If other objects of the same type migrated successfully, compare the objects in the recovery file with the objects in the migration files. Check whether the offsets from the primary file match the entries in the secondary file, and check for conversions that might have altered the end-of-line characters.


Application Performance

It's always important to design your Microsoft Exchange Server application for maximum performance because the range between average and excellent performance in this environment is quite noticeable. Using the programming practices and tools described in this section can result in a substantial performance gain — not only for your application, but for the entire Microsoft Exchange Server system.

Minimizing the number of remote procedure calls (RPCs) for your application is the most important factor in improving performance. Two important ways to reduce RPCs are using the MAPI_DEFERRED_ERRORS flag and batching calls when using the IMAPIProp::GetProps and IMAPIProp::SetProps methods.

Using tools such as the Windows NT Performance Monitor and the FERNEL32 DLL can also improve performance. They can alert you to less efficient code processes so you can optimize these areas.

Recommendations contained in this section are loosely organized in order of importance and ease of completion. In general, the ones listed first are easiest to implement and provide the largest performance gains.


Reducing the Number of RPCs

Remote procedure calls (RPCs) allow two processes to communicate transparently over a network. Although RPCs are essential to client-server architecture, they can cause significant network overhead. When a message is sent, it is enclosed within an envelope of information that is required for addressing, routing, and network protocol. This extra information and the time required to process it is called functional overhead. For example:

  • Depending on the operation, the functional overhead of an RPC is at least 10 milliseconds, plus an average of 200 milliseconds for a round trip from the client to the server.
  • Each RPC expends an average of 300 bytes of network I/O overhead, as well as server and client CPU overhead for sending, receiving, and processing.
  • When direct binding of messages is possible (such as when TCP-IP protocols or IPX protocols are used), each RPC causes only an average of 260 bytes of network overhead.

An excessive number of RPCs leaves the server with less time to process internal requests, which affects the server’s performance and scalability. Minimizing the number of RPCs for your application improves response time for clients, and also improves the server’s overall performance.

To reduce the number of RPCs
  • Use the IMAPIProp::GetProps and IMAPIProp::SetProps methods efficiently by batching calls to these methods. See Getting and Setting Properties Efficiently and Minimizing IStream Interface Use.
  • Use the MAPI_DEFERRED_ERRORS flag, which has the secondary effect of delaying calls until the information is needed. See Using the MAPI_DEFERRED_ERRORS Flag.
  • When possible, access data locally by keeping frequently used items cached at the client and by using properties that are already stored locally. See Accessing Data Locally and Building a Cache of Frequently Used Items.
  • Choose the MAPI method that uses the fewest RPCs. See Selecting MAPI Methods That Use Fewer RPCs.


Getting and Setting Properties Efficiently

Most Microsoft Exchange Server applications get and set properties frequently. You can significantly improve application performance by making this process as efficient as possible.

To reduce the number of RPCs generated by getting and setting properties
  • Avoid calling the IMAPIProp::GetProps and IMAPIProp::SetProps methods by using properties that are already stored locally. This reduces RPCs and total overhead for each property.
  • Get or set as many properties as possible with a single RPC.

Using the IMAPIProp::GetProps Method

Each GetProps call generates an RPC that results in an average of 260 to 300 bytes of network overhead in addition to the bytes of data sent. This overhead has a performance impact, particularly on users with slow links or modems. For example, an application designed to read a message by retrieving each of its properties separately requires 10 to 12 RPCs for each message, which results in 3000 bytes of overhead per message. Using more efficient methods noticeably improves the performance of this type of application.

Note Getting properties that are stored on the local computer does not cause an RPC. For a list of these properties, see Using Local Properties and Building a Cache of Frequently Used Items.

Grouping GetProps and SetProps Calls

Besides using local properties, you can group information that may generate an RPC into a single call. Server-based services generally attempt to batch as many calls as possible, but rewriting your client application to group them into one call is a good way to reduce the overhead.

Processing a Minimum Set of Properties

You can eliminate RPCs by designing your client application to process only those properties that are required. Determine the minimum set and take advantage of the fact that the server often returns multiple properties when queried for a single property. Querying all properties whether or not they are needed is generally not a good strategy.

Using the IMAPIProp::SetProps Method

Functional overhead is also incurred each time you set a property with the SetProps method. It is a good idea to design your client application to gather as many properties as possible before setting them on the server.

A provider such as the Microsoft Exchange Server information store can collect a number of SetProps requests at the client and store the cached information until an RPC is forced by a call such as the IMAPIProp::SaveChanges method. It then writes all the changes at once. This greatly reduces overhead for SetProps calls.

Example: Using the SetProps Method Efficiently

A client application sends a message and saves a copy of the message in a private folder. The current design requires three calls to SetProps. This number is reduced when the provider caches these SetProps requests and makes one call when the message is submitted. This results in only one RPC. A better solution is to rewrite your client application to group its own SetProps requests into one call. This reduces CPU usage more than the first solution because fewer total function calls are made.


Using the MAPI_DEFERRED_ERRORS Flag

The primary purpose of the MAPI_DEFERRED_ERRORS flag is to defer error reporting. You can also use this flag to reduce RPCs generated by an application. When the MAPI_DEFERRED_ERRORS flag is set, error reporting is deferred until the IMAPIProp::GetHierarchyTable method or the GetProps method is called. A secondary effect is that function calls are also deferred until the information is actually required. For example, when the MAPI_DEFERRED_ERRORS flag is set, the MAPI OpenEntry function will execute. It will not, however, actually open a folder and require an RPC until information is requested from the folder. The OpenEntry call and the information request are cached at the client.

Using the MAPI_DEFERRED_ERRORS flag makes error handling slightly more difficult because the calling application does not immediately receive the information for the OpenEntry call. If the folder you want to open does not exist, you will not see the error until you actually try to retrieve information from the server. To minimize this problem, make your error handling more generic and plan for events that may occur in later function calls.

The MAPI_DEFERRED_ERRORS flag also adds some complexity to the client and even more complexity to providers, but it dramatically reduces the number of RPCs. Testing shows that using MAPI_DEFERRED_ERRORS can reduce network overhead as much as 50 percent by reducing the number of round trips to the server, as well as increasing scalability of the server.

Example: Using the MAPI_DEFERRED_ERRORS Flag

A client application requests information from the server every 30 seconds by calling the GetContentsTable, SetColumns, and GetRowCount methods. The first call to GetContentsTable causes an RPC, and then SetColumns and GetRowCount each cause an RPC.

If the MAPI_DEFERRED_ERRORS flag is set on the GetContentsTable function call, all three operations are combined into one RPC. This significantly enhances the application’s performance.

Note The advantage gained by using the MAPI_DEFERRED_ERRORS flag varies according to service provider. A client application working with an information store service provider running on a remote server may perform much more quickly with the MAPI_DEFERRED_ERRORS flag set. However, if the same client application is working with an information store service provider running on the local computer, it may show no improvement at all because the data is retrieved locally and no RPCs result.


Accessing Data Locally

When possible, design your application to check for information locally before making calls to the server. You can access data locally by building a cache of frequently used items and by familiarizing yourself with properties that are already stored locally. This recommendation applies not only to MAPI functions, but also to other functions that access information from a server.

Example: Sharing Information between Applications

A Microsoft Exchange Client application retrieves the PR_MESSAGE_CLASS and PR_DISPLAY_NAME information store properties several times during processing. This application runs in conjunction with other client applications that use and store the same properties. In this situation, the client application can be designed to share the properties with the other applications to reduce the total number of RPCs.

Example: Using Information from Other Messages

A client application forwards open messages and takes more than three seconds to forward each message. It causes as many as sixteen RPCs per message by reading information from the server, changing the Forward form, and writing the information back to the server. All information needed for the Forward form is available locally at the client computer. Because of this, the entire operation can be performed without RPCs if the information is copied from the form for the currently open message, modified as necessary, and used in the Forward form.


Building a Cache of Frequently Used Items

Building a cache at the client computer improves performance when the data is frequently accessed and stored remotely. Although this process uses extra memory at the client, it reduces the number of RPCs for information retrieval, thus reducing I/O for the server.

When creating your cache, you should consider the cache size, the hit ratio (estimation of how often it will be used), and the consistency of the property to be cached (how often it changes). Caching only those properties that change infrequently on the server provides a better guarantee of consistency between the client and server versions of the property values. It also saves the client from having to refresh the cache as frequently.

A poorly designed cache can actually impair performance by taking more time to perform operations than simply retrieving the properties from the server. Because refreshing cache entries takes time, the most efficient cache maintains valid property values for the longest possible interval before a refresh is required.

Besides properties, you can cache other types of information. For example, Microsoft Exchange Server messages can contain text displayed in multiple fonts and colors, and embedded OLE objects such as bitmaps. It is inefficient to display these types of messages if font and color information must be retrieved from the operating system for each character. To accelerate the process, use the Microsoft Exchange Server Rich Text Edit field to cache these properties.


Selecting MAPI Methods That Use Fewer RPCs

The following table lists a number of commonly used MAPI methods and the circumstances under which they cause RPCs. To optimize your application’s performance, use the MAPI methods that cause the fewest RPCs.

Commonly Used MAPI Methods and RPCs

MAPI Method | Causes RPC?
Advise | Never causes an RPC.
CompareEntryIDs | Very rarely causes an RPC.
CopyTo | Always causes an RPC.
CreateAttachment | Causes an RPC except when creating the first message and the MAPI_DEFERRED_ERRORS flag is set.
CreateBookmark | Causes an RPC except when creating a bookmark for the beginning or end of a table.
CreateFolder | Always causes an RPC.
CreateMessage | Causes an RPC except when MAPI_DEFERRED_ERRORS is is set.
DeleteProps | Causes an RPC for information store and folder objects, rarely for most other objects.
FindRow | Always causes an RPC, but retrieves extra information to save for subsequent calls of the QueryRows method, which can minimize future RPCs.
DeleteMessages | Always causes an RPC.
FreeBookmark | Never causes an RPC.
GetAttachmentTable | Causes an RPC except when MAPI_DEFERRED_ERRORS is set.
GetContentsTable | Causes an RPC except when MAPI_DEFERRED_ERRORS is set.
GetHierarchyTable | Causes an RPC except when MAPI_DEFERRED_ERRORS is set.
GetIDsFromNames | Usually causes an RPC unless the identifier is already in the cache (identifiers are cached locally after the first call).
GetNamesFromIDs | Usually causes an RPC, unless the name is already in the cache (names are cached locally after the first call).
GetProps | Causes an RPC unless properties are stored locally
GetRecipientTable | Causes an RPC except with MAPI_DEFERRED_ERRORS set.
GetRowCount | Usually causes an RPC, except when table properties are cached by provider.
OpenEntry | Causes an RPC except with MAPI_DEFERRED_ERRORS set.
OpenMsgStore | Always causes an RPC.
OpenProperty | Depends on the property. Never causes an RPC if MAPI_DEFERRED_ERRORS is set.
QueryColumnsAll | Causes an RPC for contents, attachment, and recipient tables. Never causes an RPC for all other tables.
QueryPosition | Usually causes an RPC, with a few exceptions (such as at the beginning and end of a table).
QueryRows | Usually causes an RPC. Never causes an RPC when used after FindRow (on same row) or when already at end of table.
QuerySortOrder | Never causes an RPC.
Release | Causes an RPC only for an information store object. Never causes an RPC for all other objects.
Restrict | Causes an RPC only if called before data is in the cache. Does not when passed NULL on already nonrestricted table.
SaveChanges | Causes an RPC except with MAPI_DEFERRED_ERRORS set, although using MAPI_DEFERRED_ERRORS is not usually recommended.
SeekRow | Usually causes an RPC except when already at the row, seeking to the end, or seeking to the beginning.
SetColumns | Causes an RPC only if called before data is in cache.
SetProps | Causes an RPC for information store and folder objects, rarely for most other objects.
SortTable | Causes an RPC only if called before data is in the cache.
SubmitMessage | Always causes an RPC.


Using Local Properties

When an object is first accessed by the server, the following properties are stored on the local computer. As a result, function calls asking for any or all of these properties do not cause an RPC when the IMAPIProps::GetProps method is called.

Properties on Information Store Objects (Logon)

PR_ENTRYID
PR_RECORD_KEY
PR_SEARCH_KEY
PR_STORE_ENTRY_ID
PR_STORE_RECORD_KEY
PR_OBJECT_TYPE
PR_STORE_SUPPORT_MASK
PR_VALID_FOLDER_MASK
PR_MDB_PROVIDER
PR_IPM_SUBTREE_FOLDER
PR_IPM_FINDER_FOLDER
PR_IPM_VIEWS_FOLDER
PR_IPM_DAF_FOLDER
PR_MTS_IN_FOLDER
PR_MTS_OUT_FOLDER
PR_IPM_OUTBOX_FOLDER
PR_IPM_SENTMAIL_FOLDER
PR_IPM_WASTEBASKET_FOLDER
PR_IPM_COMMON_VIEWS_FOLDER
PR_SCHEDULE_FOLDER
PR_NON_IPM_SUBTREE_FOLDER
PR_EFORMS_REGISTRY_FOLDER
PR_SPLUS_FREE_BUSY_FOLDER
PR_OFFLINE_ADDR_BOOK_FOLDER
PR_LOCALE_EFORMS_REGISTRY_FOLDER
PR_LOCAL_SITE_FREE_BUSY_FOLDER
PR_LOCAL_SITE_ADDR_BOOK_FOLDER

Message-Store Object Properties on Non-DOS Clients

PR_DISPLAY_NAME
PR_COMMENT

Properties on Message Objects

PR_OBJECT_TYPE
PR_REPLICA_SERVER
PR_PARENT_ENTRY_ID
PR_STORE_ENTRY_ID
PR_STORE_RECORD_KEY
PR_ENTRY_ID
PR_RECORD_KEY
PR_LONGTERM_ENTRY_ID
PR_INSTANCE_KEY
PR_MAPPING_SIGNATURE

Properties on Folder Objects

PR_OBJECT_TYPE
PR_ENTRY_ID
PR_RECORD_KEY
PR_SEARCH_KEY
PR_INSTANCE_KEY
PR_STORE_ENTRY_ID
PR_STORE_RECORD_KEY
PR_LONGTERM_ENTRY_ID
PR_ACCESS_LEVEL
PR_DEPTH
PR_DISPLAY_TYPE
PR_MAPPING_SIGNATURE

Properties on Attachment Objects

PR_OBJECT_TYPE
PR_MAPPING_SIGNATURE
PR_INSTANCE_KEY


Minimizing IStream Interface Use

Using the IStream interface improves performance when large amounts of data must be retrieved, but results in a large amount of overhead for smaller properties. As a general rule, use IStream only for properties greater than 16K in size.

Note This size limit exists because the RPC buffer has a maximum size. The maximum size of the buffer varies according to service provider.

Some providers, including the Microsoft Exchange Server information store, have the ability to batch IStream interface operations into calls to the IMAPIProp::GetProps and IMAPIProp::SetProps methods. If you must write many small amounts of data to a property using the IStream interface, these write operations are first held by the information store provider at the client. When you call the SaveChanges method, the provider writes them to the server with a GetProps call if they are small enough. However, this optimization still incurs more overhead than if the client itself uses GetProps and SetProps.

Small writes to a stream may also cause excessive transaction logging. If you write data to a stream and then call the SaveChanges method, the changes are committed. To ensure data integrity, each SaveChanges operation creates an entry in the transaction log. Additional write operations and SaveChanges calls create more logs. As a result, a write of less than 1K can generate more than 10K of logging information.

Example: Minimizing IStream Interface Use

A Microsoft Exchange Client application uses only the IStream interface to read and write the body of a message. Even to write the word “Hello,” the IStream interface creates a stream and then closes the stream to send just eight bytes of information. This causes much more overhead than using the GetProps and SetProps methods.

Performance is noticeably improved when the client application is rewritten to follow these guidelines:

  • When the size of the data is known and it is small enough, use the GetProps or SetProps methods.
  • If the size of the data is larger than 16K, use the IStream interface.
  • When the size of the data is unknown, first try GetProps or SetProps. If the call fails, an error will be returned. Then use the IStream interface.

Most messages are below the maximum size retrievable by a single GetProps call. In the default case, CPU cycles and RPCs are saved bycalling GetProps or SetProps as a general rule rather than using IStream.


Using Buffered Streams

When the IStream interface is used, several different functions can be called to produce the stream. Generally, performance is improved by using a buffered stream. The MAPI OpenStreamOnFile function produces a stream that is not buffered, so Microsoft Exchange Server provides the OpenVirtualStreamOnFile and OpenVirtualStreamOnProperty functions, which provide buffered streams.

To transfer data using buffered streams
  • Use the Virtual Stream on File (VSOF) mechanism, which is obtained with a call to the OpenVirtualStreamOnFile function. This is a buffered version of the MAPI OpenStreamOnFile function and is recommended in most cases.
  • Use the Virtual Stream on Property (VSOP) mechanism, which is obtained with a call to the OpenVirtualStreamOnProperty function. This function creates a buffered stream and is used for retrieving and setting binary and string properties that may be too large to use with the IMAPIProp::GetProps and SetProps methods.
  • Use the MAPI OpenStreamOnFile function by passing in flags to control the creation of the stream object. This function call returns a stream pointer and a Stream object. In most cases, performance is improved by using the OpenVirtualStreamOnFile function.
  • Use the Win32 IStream interface functions. This interface is used by all the preceding functions to return a Stream object and a pointer which should be used for memory allocation and deallocation. To free the Stream object, the application or provider must call the OLE IStream::Release method.

All of the procedures listed above use OLE streams. Win32, MAPI, and the Microsoft Exchange Server SDK all contain functions for working with OLE streams. For information about the IStream interface, see the Platform SDK. For more information about the MAPI OpenStreamOnFile method, see the MAPI Programmer’s Reference.

For more information about OLE, see Inside OLE 2 by Kraig Brochschmidt (Microsoft Press).

Streams can be used to work with rich text format (RTF) properties. For more information, see Saving ANSI Text as a Message Property in RTF, Saving RTF Text as a Message Property in RTF, and Retrieving ANSI Text from a Message Property in RTF.


Using the MAPI Idle Engine

If users perceive a delay while your application performs processing that is not time-critical, you can defer the processing until a time when it will not be noticed. Use the MAPI idle engine as a strategy to delay performing the operation.

The MAPI idle engine is a set of functions that can improve performance by making good use of idle time.

To use the MAPI idle engine
  1. Create a callback function that contains tasks that can occur when the MAPI subsystem is idle.
  2. Defer processing by registering the task as an idle task.

When MAPI detects idle time, it executes this task by invoking your callback function. For more information, see the MAPI Programmer’s Reference.

Example: Timing Status Bar Use

A Microsoft Exchange Client application moves and deletes messages slowly enough that the delay is noticeable to users. It spends too much time getting and processing notifications, then updating the status bar display. To accelerate these operations, the application is redesigned to use the status bar only after a two-second delay if the process is still running.

After this change, when a user deletes a single message, the response is much faster. If multiple messages are deleted and the process takes longer than two seconds, the status bar provides information about the continuing process. This modification saves time and increases feedback to users for both large and small operations.

Example: Optimizing Application Startup

A Microsoft Exchange Client application starts slowly because it invokes a large number of MAPI methods on startup. To improve this application’s startup time, some of the MAPI calls are deferred until after the application starts and the user interface displays. User interaction often generates idle time, so deferred calls will usually be made transparently to the user.


Using More Efficient Function Calls

MAPI provides you with several ways to retrieve data because many properties can be duplicated on a message, on a folder, and on an information store. One strategy for improving efficiency is to find the data retrieval path that generates the smallest number of RPCs and MAPI calls. When several MAPI calls can be used to get the same data, test for the best performance by timing each, then using the most efficient call.

Example: Reducing Function Calls

A Microsoft Exchange Client application opens a folder, gets the hierarchy table, sets the columns, sends the message, opens the message, and retrieves a property to determine which language the client is using.

This application can obtain the information more quickly by setting the columns on the MAPI display table, requesting rows, and setting a parameter to the desired property. This creates a large savings in CPU use, saves memory resources, and reduces the number of RPCs generated.


Using MAPI Function Calls on Tables

Microsoft Exchange Client applications make frequent calls to MAPI table functions. Optimizing the use of table functions can result in significant performance improvements.

Using QueryRows

Efficient use of the IMAPITable::QueryRows method can improve performance when accessing table data. Instead of calling the IMAPITable::GetRowCount method and using the returned value in a subsequent call to QueryRows, first estimate the maximum number of rows possible in the table. Then call QueryRows(<large number>) to ask for all the rows at once. QueryRows returns the row count, along with the other information. If you do not get every row, request the remaining rows. To query all rows most efficiently, use the MAPI HrQueryAllRows function. See the MAPI Programmer’s Reference for details on this function.

It is also advantageous to run the QueryRows method on as many columns as needed in a single operation, and to use default formats. When rows and columns are not in the default format, queries usually incur more overhead.

For more information, see Ordering Function Calls to Ensure Table Notifications.

Using SetColumns

Efficient use of the SetColumns method also improves performance. Follow these guidelines:

  • Always call SetColumns before calling the Advise, SortTable, or Restrict methods.
  • Call the Advise method after calling the HrQueryAllRows MAPI function unless there is a good reason not to do so. This reduces overhead because HrQueryAllRows may also perform a SetColumns, SortTable, and/or a Restrict operation.
  • If you must use SetColumns, be sure you have set the minimum number of columns needed.
  • Never call SetColumns, Restrict, or SortTable twice on the same table.
  • Combine multiple Restrict calls into a single call.

Calls to the Restrict method are generally expensive to the server in terms of network overhead. For example, message tables are large. Therefore, restrictions are proportional to the number of messages in the database. Avoid doing a Restrict call whenever possible. Calls to Restrict for special tables like Rules and Forms are notable exceptions because the server is able to perform these restrictions in memory.


Removing Memory Leaks

Memory leaks decrease the available memory and increase disk swapping. They also reduce stability, degrade performance over time, and can eventually bring your computer to a halt. Because a number of MAPI functions allocate memory for you, but do not free it, you must remember to free this memory yourself. Many tools are available to help you find memory leaks.

Do not assume that all the leaks you detect are your own. If one application uses the DLL of another application, this DLL may cause a memory leak, although the original application may appear to be causing the problem.

The Windows NT Server Resource Kit and the Platform SDK contain tools to help you with memory leak detection for Windows NT Server and Windows 95. For more information, see Using a Debug Version of MAPI and The Microsoft Windows NT Advanced Server System Guide.

Using GlobalAlloc, HeapAlloc, and MAPIAllocateBuffer

The Win 32 GlobalAlloc and HeapAlloc functions and the MAPIAllocateBuffer functions are designed for memory management. A 32-bit application should use the HeapAlloc function for the best performance.

For a complete discussion about memory allocation options and performance, see Options for Memory Management.


Using the Performance Monitor

The Windows NT Performance Monitor can help you isolate performance bottlenecks. Many Microsoft Exchange Server components create their own performance counters that provide more detailed information about performance bottlenecks. Using the Performance Monitor and the logging facility will help you identify problem areas. The main areas to consider when searching for bottlenecks are memory accesses, CPU usage, disk I/O, and network I/O.

Using the Disk Performance Monitor

The Performance Monitor counters for disk monitoring are turned off by default because they erode Windows NT Server performance by 1 to 2 percent. The Performance Monitor should be turned off when you are not specifically monitoring disk performance.

The Performance Monitor counters indicate the number and size of reads and writes that are being generated for a particular disk. They also show the percentage of time your application spends accessing a particular disk or disk strip set, as well as other information.

To turn on disk performance monitoring for a Windows NT Server computer, type diskperf -y at a command prompt and restart the computer. You may want to start the disk performance monitor on all your development servers before you begin testing your application.

To prepare for performance monitoring
  1. Start the Windows NT Performance Monitor.
  2. From the View menu, choose Log.
  3. From the Edit menu, choose Add to Log. Add counters for the following:
    Logical Disk
Memory
Processor
Redirector
Server
  4. Choose Done.
  5. From the Options menu, choose Log. Enter a file name on a separate drive to isolate logging I/O. For example, if Microsoft Exchange Server resides on the C drive, enter logs on the D drive.
  6. Optional: Adjust the periodic update to be 1/100 of your time. For example, if your test requires 300 seconds, set the periodic update to three seconds. This makes it easier to view the data in one screen.
  7. Click OK.

To start performance monitoring and collect data
  1. Choose Log from the Options menu in the Windows NT Performance Monitor window.
  2. Click Start Log.
  3. Start your application.

Note Before running a test, choose Chart from the View menu. Add basic counters such as:

Processor:%Processor Time
Logical Disk:C,D

This allows you to monitor the test until it is completed and the counters return to idle levels. Also, when you get all the settings, save your layout by choosing Save Workspace from the File menu. This will allow you to restore the settings at a later date.

To monitor the test

To monitor a test in session, choose Chart from the View menu.

To stop test logging
  1. From the Log menu, choose View when the test is finished.
  2. From the Options menu, choose Log.
  3. Click Stop Log.

To produce a view that gives you basic patterns
  1. From the Options menu, choose Data From and enter the log file name.
  2. From the View menu, choose Chart.
  3. From the Edit menu, choose Add to Chart. Enter the following:
    Processor:% Processor Time
Logical Disk:% Disk Time
Redirector:Bytes Total/sec
Memory:Pages/sec
To analyze the data

You can draw your first conclusions from the data results. For example, if the Percent Processor Time is listed at 100 percent during most of the test, your application is CPU-bound.

To produce a view that allows you to look at all recorded data
  1. From the Report menu, choose View.
  2. From the Add to Report menu, choose Edit.
  3. For each object, add all counters for all instances.

For example, your test may have sent 100 messages. Multiply the Disk Bytes per second by the time interval as shown in Graph Time in the Chart View. Divide by 100 messages to determine the Disk I/O required per message.

Isolating Problems

Analyze the data obtained for each component to identify the direct source of any problems. Recommendations for isolating problems include the following:

  • Use a computer with multiple disks to isolate a component responsible for excessive disk I/O operations. Use the Microsoft Exchange Server optimizer (PERFWIZ.EXE) to move the information store logs, information store databases, directory service logs and databases. The Microsoft Exchange Server message transfer agent (MTA) can be used to separate the drives. You can then monitor each drive for I/O to discover which component accesses the disk most frequently. Set up Microsoft Exchange Server and Windows NT Server on one disk, a log file on a second disk, and stripe the remainder of your disks together to hold the database.
  • Add process-specific or component-specific objects such as the Microsoft Exchange Server information store object when logging. This will provide you with more specific information about the component in question.
  • To monitor a test in session, choose Chart from the View menu.

For more detailed information about the Performance Monitor, see Optimizing Windows NT in the Windows NT Server Resource Kit.


Checking Disk I/O with FERNEL32

The Windows NT Server Resource Kit provides DLL replacements that can monitor usage for any Win32 function.

FERNEL32.DLL is a replacement for KERNEL32.DLL in Windows NT Server. It includes functions for the kernel-level interfaces, which include file I/O, semaphores, events, and mutexes. Using FERNEL32 with the APF32DMP.EXE program, you can run a test and view all file activity requested by each component from the Windows NT Server kernel. This will tell you how much I/O is generated by each file. You can then isolate areas where I/O affects performance.

This same technique can be used to replace ADVAPI32.DLL, GDI32.DLL, USER32.DLL, and the CRTDLL.DLL with ZDVAPI32.DLL, ZDI32.DLL, ZSER32.DLL, and ZRTDLL.DLL. These utilities output unformatted text, so they may require a parser for data analysis. For more information, see Optimizing Windows NT in the Windows NT Server Resource Kit.

To use FERNEL32.DLL
  1. Make sure your application is stopped.
  2. Type the following at a command line:
    APT32CVT FERNEL32 <application list>

    for example:
    APF32CVT FERNEL32 EMSMTA.EXE

  3. Start your application.
  4. Start the APF32DMP.EXE utility.
  5. Select FERNEL32.DLL.
  6. Change to the directory to start your test case.
  7. In APF32DMP.EXE, choose Clear.
  8. Perform your test case.
  9. In APF32DMP.EXE, choose Dump.

After running your application with FERNEL32, the FERNEL32.WAP file contains the data to be analyzed. It is located in the working directory of the application you are profiling. To analyze this data, you may need to create simple parsing tools, which you can write with Microsoft Excel macros or other programs.


Checking Network I/O

The Network Monitor tool helps determine where network bottlenecks are occurring. Network Monitor runs on Windows NT Server and is available from Microsoft. Other network monitoring tools can be obtained from independent software vendors.

For Microsoft Exchange Server or any client-server application, an important measurement is the number of bytes flowing between the server and the client and how many RPCs are required per action. Network Monitor can count both, and you can run it on both the server and the client. Network Monitor can analyze each frame, then compute the overhead.

The Network Monitor can also report the actual number of bytes transmitted. It includes low-level connections for Windows NT Server actions, and the redirector to establish and maintain that network connection. The number of connections should be kept low, especially when a large number of users are connected remotely. The number of bytes is particularly important for scalability and for slow-link clients. Less network I/O means a network/server can support more clients, and also means faster operation for remote clients over slow links such as a modem.

Example: Checking your Network I/O

Using a network monitor during a test of a Microsoft Exchange Client shows that each RPC has a 304-byte overhead. So many RPCs are being requested that RPC overhead consumes 50 percent of network I/O. Also, more than 40,000 bytes of network I/O are required to reply to a message. This again demonstrates the importance of reducing RPCs and monitoring their use.

To use the Network Monitor
  1. Enter Network Address for the computers you want to monitor.
  2. Run NET CONFIG RDR.
  3. Look for the 12 character Ethernet network address for each network card. Example: 00AA0038ADC1
  4. Start Network Monitor.
  5. From the Capture menu, choose Addresses.
  6. Click Add.

To select type: ETHERNET
  1. Type in a 12-character address for Address. Example: 00AA0038ADC1
  2. Type in server name for Name. Example: SERVER
  3. Type in comment. Example: Microsoft Exchange Server
  4. Click OK.
  5. Click Save and save to DEFAULT.ADR.

Repeat these steps for any other computers to be monitored.

To monitor traffic between the server and client
  1. From the Choose Capture menu, choose Filter.
  2. Edit the line that reads INCLUDE ANY <--> ANY.
  3. Select the server on the left and the client on the right.
  4. Click OK.

For future use, save and load the filters.

To begin capture
  1. Get test ready to run.
  2. From the Capture menu, choose Start.
  3. Choose Run Test.
  4. From the Capture menu, choose Stop.

To analyze the data

The Station Stats window allows you to view how many bytes are being sent and received between the client and the server.

To produce a view that allows you to see all RPCs to and from the server
  1. From the Capture menu, choose Display Captured Data.
  2. Choose Filter from the Display menu.
  3. Edit the line that reads Protocol == Any.
  4. Disable All protocols.
  5. Enable the MSRPC protocol.

To produce a view that allows you to see and count the number of RPCs to the server
  1. From the Capture menu, choose Display Captured Data.
  2. From the Display menu, choose Filter.
  3. Edit the line that reads Protocol == Any.
  4. Disable All protocols.
  5. Enable the MSRPC protocol.
  6. Add an Expression.
  7. Choose the Property tab.
  8. Select and expand MSRPC.
  9. Select P-Type in Protocol:Property listbox.
  10. Select == in Relation listbox.
  11. Select Request in Value listbox.
  12. Click OK.

For future use, load and save the views.


Profiling Your Application's Performance

Profiling Your Application’s Performance

If you suspect that CPU usage may be causing performance bottlenecks, use the Call Attributed Profiler (CAP) tool, which is part of the Windows NT Server Resource Kit. This tool requires a special build of applications, but performs a detailed trace of every function call and how much time that call requires. It identifies frequently called functions that are slow and need to be optimized or called less often.

You can also use the CAP tool to parse the data into a Microsoft Excel readable format, and to identify calling functions and called functions.

Example: Using the CAP Tool to Eliminate Duplicated Calls

A Microsoft Exchange Client application often opens multiple folders, but its performance is slow and you can see it redraw every message in the folder. This performance bottleneck can be identified by CAP profiling

In this case, CAP profiling results indicate that the application is asking for time-zone information on every call. Because time zone information does not often change, this information can be requested once, then saved for the entire session. This reduces the time spent making multiple calls, reduces CPU time, and improves performance significantly.

To use CAP profiling
  1. Copy CAP.DLL from the Windows NT Server Resource Kit to your system directory.
  2. Compile your application for profiling. See the Microsoft Visual C++ Manual for instructions.
  3. Make any necessary changes to the CAP.INI file. See Optimizing Windows NT or CAP.TXT of the Windows NT Server Resource Kit for general information on preparing CAP.INI. Use the following table to customize your copy of CAP.INI.

For more information, see CAP FLAGS in the Windows NT Server CAP.INI file.

Setting Up CAP.INI

Section in CAP.INI
Usage Notes
[EXES] List the CAP-ready .EXE files to profile. The profiler automatically starts when you launch one of these .EXE files.
[PATCH CALLERS] List the DLLs called by the file names (not compiled for CAP) into %SystemRoot%\SYMBOLS\DLL. For example, if you put KERNEL32.DLL in this section, copy KERNEL32.DBG to %SystemRoot%\SYMBOLS\DLL.

List DLLs built for profiling if you want to profile internal calls. Note that all exported functions in this DLL are listed twice.
[OUTPUT FILE] CAP output is directed to the file specified in the following line:
FILENAME=C:\CAP.END
[CAP FLAGS]
profile=off
perthreadmem=8388608

If you set the profile flag to off, profiling will default to OFF (otherwise the default is ON). In this case, profiling will only start manually by using CAPDUMP.EXE. If you don't need to profile immediately after startup, set profile to OFF. As a result, the .EXE file will start much faster.

Note that the perthreadmem parameter is required. It represents the amount of memory CAP allocates per thread to collect data. This parameter is expressed in bytes (for example, 8 MB). If you experience problems such as running out of memory, try changing this value.

To start and run CAP profiling
  1. Start your .EXE files.
  2. Run CAPDUMP.EXE. For more information, see the Windows NT Server Resource Kit.
  3. In CAPDUMP, choose Clear and Restart, then choose OK to begin profiling.
  4. Run your test.
  5. In CAPDUMP, choose Stop, then choose OK.
  6. In CAPDUMP, choose Dump and Stop, then choose OK. CAP will start writing to disk.

Refer to the Windows NT Server Resource Kit for CAP data analysis tools.


Using MAPI Call Traces

Performance information can be gathered from your application by using the MAPI call trace provided as part of the MAPI package.

To get MAPI call traces from the personal information store
  1. Copy MSPST.INI from the MAPI SDK to the root of your Windows NT Server directory.
    • Type COPY MSPST.INI C:\WINNT
  2. Change every value in MSPST.INI that starts with Perf from 0 to 1.
  3. Change the following values in MSPST.INI:
    TraceGetProps=1
TraceSetProps=1
TraceDeleteProps=1
TraceSetColumns=1
TraceSortTable=1
TraceRestrict=1
TraceFindRow=1
  4. Edit or create the MAPIDBG.INI file in your Windows NT Server directory to contain the following lines:
    [General]
DebugTrace=1
  5. Install a debug version of the Microsoft Exchange Client.
  6. Start the Microsoft Exchange Client. Output from the PST will print to the print destination of OutputDebugString.
    • On Windows NT Server, the easiest way is to start the Microsoft Exchange Client in WINDBG mode. The output appears in the Command window.
    • On a 16-bit client, use DBWIN to capture the output from the Microsoft Exchange Client.
  7. Mark the area before the test. When the test is complete, cut and paste the text to the Windows Notepad application to save the trace for further analysis.

If you receive a First Chance Exception notification when starting the client, stop WINDBG, restart WINDBG, and then execute the following steps:

  1. From the Options menu, choose Exceptions.
  2. For Except #, enter 000006ba.
  3. Make sure Action is set to Ignore.
  4. Click Add.
  5. Click OK.
  6. Press F5 to start Microsoft Exchange Server and log on.


Development Environment

Before you develop Microsoft Exchange Server applications, prepare your development environment by performing the following tasks:

  • Installing the necessary software
  • Setting environment variables. Optionally, this task includes setting up debug logging.

Other aspects of Microsoft Exchange Server application development include:

  • Compiling and linking your code with Microsoft Visual C++. You can use its interactive development environment or you can build applications from a command prompt with the command NMAKE.
  • Selecting the correct runtime libraries and include files.

To learn about developing applications for Microsoft Exchange Server by building its sample applications, in particular the Sample Gateway and Sample Mailbox Agent.


Installing a Typical Development Platform

The typical development environment for the Microsoft Exchange Server SDK includes the following products. To avoid conflicts, install them in the order listed.

  1. Windows NT Server Version 3.51 or later as a base platform.
  2. Microsoft Visual C++ Version 4.0 or later (earlier versions are incompatible with the Microsoft Exchange Server SDK).
  3. Microsoft Exchange Client
  4. Microsoft Exchange Server For developing and testing most types of applications, you will need the entire Microsoft Exchange Server product on your development computer or on a networked computer. Note that some applications require only the Microsoft Exchange Server Administrator program.
  5. Microsoft Exchange Server SDK See Installing the Microsoft Exchange Server SDK.


Installing the Microsoft Exchange Server SDK

Once Microsoft Exchange Server is installed, the next step is to install the SDK itself. If you plan to install and build all the sample applications, at least 50 MB of disk space is required.

To install the Microsoft Exchange Server SDK
  1. Change to the directory containing the setup program for the sample applications:

    \BKOFFICE\<computer type>\DEBUG\SAMPLES\EXCHANGE

  2. Type SETUP at the command prompt.

The setup program automatically sets several environment variables.

The Microsoft Exchange Server SDK includes a set of sample applications that are already compiled. They are located in the \BKOFFICE\BIN directory. See Building the Sample Applications.


Setting Environment Variables

To prepare your system for developing Microsoft Exchange Server applications, make sure the proper changes have been made to the system environment variables. Remove any out-of-date settings when updating Microsoft Visual C++ or Microsoft Exchange Server. For best results, remove any extra semicolons. They may be tolerated in the PATH variable, but will cause errors in the INCLUDE and LIB variables.

To verify that environment variables are set correctly
  1. Type SET at a command prompt to view a list of all environment variable settings. All variables listed in the following steps should be present. If you see any problems, modify the systems settings found in the Control Panel as directed.
  2. At the Windows NT Control Panel, choose System. The System dialog box provides settings for System Environment Variables and User Environment Variables. (If you are using version 4.0 or later of Windows NT, click the Environment tab, and edit System Variables or User Variables.) When changing these variables, note that user environment variables take precedence over system environment variables.
  3. Make sure the following system environment variables are set. If not, change their values in the System Environent Variables list box:

    BASEMAKE = C:\BKOFFICE\INCLUDE\BASEMAKE.INC

    BKOFFICE = C:\BKOFFICE\

  4. Make sure the following INCLUDE system environment variables are set. If not, add the following directories in this order:

    C:\BKOFFICE\INCLUDE
    C:\MSDEV\INCLUDE
    C:\MSDEV\MFC\INCLUDE
    C:\MSTOOLS\INCLUDE

  5. Make sure the following LIB system environment variables are set. If they are not, add the following directories in this order:

    C:\BKOFFICE\LIB\I386
    C:\MSDEV\LIB
    C:\MSDEV\MFC\LIB
    C:\MSTOOLS\LIB

  6. Make sure the following PATH system environment variables are set. If they are not, add the following directories in this order:

    C:\BKOFFICE\BIN
    C:\MSDEV\BIN
    C:\MSTOOLS\BIN

    If Microsoft Exchange Server is to be installed locally, add this directory:

    C:\EXCHSRVR\BIN

  7. If you changed your environment variables, you can verify them by typing SET at a command prompt.
  8. Optionally, you can set three additional environment variables to control runtime debug logging:
    • EDK_DEBUG_FILE Set this environment variable to the debug log file name. For example, type:

      SET EDK_DEBUG_FILE = C:\BKOFFICE\DEBUG.LOG

    • EDK_ASSERT Set this environment variable to TRUE to enable runtime logging of asserts. The EDK_ASSERT variable defaults to FALSE.
    • EDK_DEBUG Use this environment variable to set the debugging level as indicated in the following table.

Microsoft Exchange Server SDK Debug Levels

Level | Purpose
D_PUBLIC | Traces calls to public functions.
D_PRIVATE | Traces calls to private functions.
D_ERROR | Logs ASSERT errors.
D_WARNING | Logs warnings.
D_STATUS | Logs a specified variable's value.
D_ACTION | Logs arbitrary text at code locations you specify, such as Now logging on to MAPI or other actions started or completed.
D_OTHER | Logs other requested information, such as a hex dump.

By default, all these debug levels are set and all debug messages are logged to the debug log file. Setting one or more levels listed in this table causes these events to be displayed on screen as well as written to a log file. To set combinations of individual levels, separate level names by commas or spaces, but not both. Example: SET EDK_DEBUG = D_PUBLIC,D_PRIVATE.

If you do not set the EDK_DEBUG_FILE environment variable and the application is being run as a service of Windows NT Server, debug messages are written to the %SYSTEMROOT% directory, which defaults to C:\WINDOWS\SYSTEM32\. By default, the debug filename is the process identifier in hexadecimal, left-padded with zeroes. For example: 0000005A.LOG.

You can use macros and functions described in EDKDEBUG.H to add extra error-logging flexibility and make debugging easier.


Building Sample Applications in the Visual C++ Development Environment

The sample code that ships with the Microsoft Exchange Server SDK compiles into three types of programs:

  • Console applications
  • Windows applications
  • DLLs

Note The SDK also provides static link libraries in directories under the \LibSrc directory. These libraries are not intended to be altered.

To build a sample application from within Visual C++, follow these steps:

To build a sample application or DLL
  1. Create a top-level project for the sample application:
    • Select New on the File menu.
    • In the New dialog box, select Project Workspace and click OK.
    • In the dialog box New Project Workspace, select Application (for a Windows application), Dynamic-Link Library, or Console Application.
    • Type the name of the sample application (for example, FIMPORT) in the Name box. Example: FIMPORT
    • Select the location of the application's files in the Location box, then click Create.

      Location example: C:\BKOFFICE\SAMPLES\EXCHANGE\FIMPORT

  2. Add the application's .C, .CPP, .RC, and .DEF files to the project:
    • Choose the Files into Project option from the Insert menu.
    • Select the appropriate files from the File Name list box in the Insert Files into Project dialog box, and click OK.
    • Make sure to insert only one file each of the type .RC or the type .DEF. For example, if an application's directory contains two .RC files (such as \PROXYGEN\EDKPROXY.RC and \PROXYGEN\PROXYVER.RC), do not include the version resource file (PROXYVER.RC).
  3. If the application's directory contains an .MC (message compiler) file, create a subproject for it and associate an external makefile with it. See Creating a Message-Compiler Subproject.
  4. Select the correct set of libraries for the linker:
    • Choose the Settings option from the Build menu.
    • In the Settings For box, choose a build type (for example, Win32 Debug or Win32 Release).
    • Click the Link tab and then click the Ignore all default libraries option.
    • For Object/library modules, type or paste the following library names, separated by spaces:

      ExchSDK.Lib Mapi32.Lib Uuid.Lib kernel32.lib advapi32.lib user32.lib ole32.lib version.lib msvcrtd.lib oldnames.lib

    You can also choose the EXCHSDKD.LIB debug version instead of EXCHSDK.LIB, but first verify that this library has been built. See Building the Set of Sample Applications and Using the ExchSDKd Library.

  5. Click the C/C++ tab. In the text box Preprocessor definitions, append the following to the existing definitions list:

    _MT,_DLL,_WIN32,WINVER=0X0400

  6. Click OK. You can now build the sample application.


Creating a Message-Compiler Subproject

If the application's directory contains an .MC (message compiler) file such as \ACLEDIT\ACLEDIT.MC or \RULEEDIT\RULEEDIT.MC, you need to create a subproject for it. This procedure uses the ACLEDIT project for an example, in which a message-compiler subproject named AclEditMsgs is created.

To create a message-compiler subproject
  1. Choose the Project option from the Insert menu. In the Type box of the Insert Project dialog box, click Makefile. In the Name box, type a name for the subproject, such as AclEditMsgs. Click Create. Click Yes in the warning box that reads:

    The makefile name or some other command line may be specified in the Project Settings dialog. Would you like to go there now?

    The Project Settings dialog box will be displayed.

  2. In the Settings For box of the Project Settings dialog box, choose a build type (for example, Win32 Debug or Win32 Release, or both) for the subproject AclEditMsgs. Click the General tab. Replace the entire contents of the Build command line text box with:

    MC -V -C -S -H ..\ -R ..\ -X ..\ ..\ACLEDIT.MC

    This command line includes the name of the top-level project's message compiler file—in this case ACLEDIT.MC. Click OK.

  3. In the FileView pane of the Project Workspace window, click the subproject—in this case, AclEditMsgs files. Build the subproject. This step generates header files and resource files. The generated files are placed in the main project directory, which lets you compile the top-level project without specifying subdirectories.
  4. Click the top-level project in the Project Workspace window—in this case, AclEdit files. Choose the Files into Project option from the Insert menu. Select the appropriate files (in this case, ACLEDIT.CPP and ACLEDIT.RC) from the File Name list box in the Insert Files into Project dialog box, and click OK.
  5. Return to step 4 of To build a sample application or DLL, which directs you to select libraries for the linker.


Creating Custom Tools with Microsoft Visual C++

You can create custom tools that perform common tasks, then add them to your Visual C++ development environment. Once you create a custom tool, it appears as an option on the Tools menu.

To create a custom tool, choose the Customize option at the Tools menu of Visual C++. Click the Tools tab, then enter settings that describe the custom tool into the text boxes of the Tools page. For more information, click the Add button on the Tools page. Click Help on the Add Tool dialog box.

Examples: Custom Tools

The following examples show the settings you specify to add tools to the Tools menu.

Tool for Building a Separate File

This tool builds a file that is not part of the project you currently have open. You can use the tool when you do not want to open a separate project, or add that file to your current project.

Menu Text                &nmake Other
Command:                 nmake.exe
Arguments:               (blank)
Initial Directory:       $Filedir
Prompt for Arguments:    (blank)
Redirect to Output Win   X
Close Window on Exit     (blank)

Tool for Rebuilding EXCHSDK.LIB

This tool rebuilds EXCHSDK.LIB after you have used NMAKE OTHER to build a library.

Menu Text                Make &ExchSDK.Lib
Command:                 nmake.exe
Arguments:               clean all
Initial Directory:       \edk\src\exchsdk (or your path)
Prompt for Arguments:    (blank)
Redirect to Output Win   X
Close Window on Exit     (blank)

Tool for Deleting the .EXE File or DLL

This tool deletes the executable file or DLL that you normally build with the current makefile.

Menu Text                &Delete Target
Command:                 c:\winnt\system32\cmd.exe (or your path)
Arguments:               /c "echo del $Target" & del $Target
Initial Directory:       (blank)
Prompt for Arguments:    blank)
Redirect to Output Win   (blank)
Close Window on Exit     (blank)

Tool for Making a File Writeable

This tool changes a read-only file to one that is writeable.

Menu Text                 Read/&Write
Command:                  c:\winnt\system32\cmd.exe (or your path)
Arguments:                /c  Attrib -r $Filename
Initial Directory:        $Filedir
Prompt for Arguments:     (blank)
Redirect to Output Win    (blank)
Close Window on Exit      X

Tool for Making a File Read-Only

This tool changes a file that is read/write to read-only.

Menu Text                Read Only
Command:                 c:\winnt\system32\cmd.exe (or your path)
Arguments:               /c  Attrib +r $Filename
Initial Directory:       $Filedir
Prompt for Arguments:    (blank)
Redirect to Output Win   (blank)
Close Window on Exit     X


Using NMAKE Switches

When building an application outside the Visual C++ development environment, you do so by opening a command prompt and typing NMAKE in the application's directory. This executes the makefile in that directory using the options specified in the BASEMAKE.INC file, assuming that the BASEMAKE environment variable has been set equal to the BASEMAKE.INC file. In addition to the standard set of options available with NMAKE, the Microsoft Exchange Server SDK defines several other options. They include the following switches:

  • INCLUDE= Specifies the path of the INCLUDE directory. Unless this switch is set to some other directory, the default path is set to \BKOFFICE\include.
  • LIB= Sets the path to the EXCHSDK library directory. Unless some other directory is specified, the default path is \BKOFFICE\LIB\I386.
  • PACK= Enables linking on a function-by-function basis by creating packaged functions. This setting invokes the /GY compiler switch. The default is set to Yes.
  • LOG= Sets a destination directory and output file for errors generated during the build. Setting LOG=No causes error messages to be sent to the screen, rather than to a file. Otherwise, error messages are sent to the $(OBJDIR)\$(PROJ).OUT file, which is the default behavior. The file is created in the <component>\WIN32\<build type> directory, where <component> is the name of the project.
  • WARNING_LEVEL= Sets the default warning level. Valid settings are 0, 1, 2, 3, and 4, with 4 as the highest warning level and 0 as the lowest level (no warnings). Default level is 3.
  • BLDTYPE= Sets the build type. See Setting the Build Type.
  • MSVCER= Sets the Microsoft Visual C++ version. This switch must be set to 4.0 or later.

Setting one or more switches on the NMAKE command line invokes that particular option for that one build. All other current settings remain intact.


Defining Alternate NMAKE Functionality

The following special flags define alternate functionality for NMAKE:

  • LISTOUT Used to view the output file, which contains the text NMAKE will print to STDOUT. See Viewing the Output from your Build.
  • LISTDIR Specifies the directory of files in \WIN32\DEBUG.
  • DELOUT Deletes the output file. This is necessary because, unless it is set, output is appended to the output file.
  • CLEAN Allows you to remove any files in the current directory that were created during previous compilations, including those with .OBJ, .ERR, .LIB, .EXE, .DLL, .MAP, .RES, and .EXP extensions. See Cleaning the Directories of All Build Products.

To use the special functions for NMAKE, type NMAKE and the function name. For example: NMAKE [BLDTYPE=RETAIL] CLEAN.


Setting the Build Type

You can choose either the DEBUG or RETAIL build type for Microsoft Exchange Server sample applications. Changing the build type changes the products of the build. Either of these versions can built at any time.

Debug Version

The DEBUG version of Microsoft Exchange Server sample applications includes the debug DLLs for creating and debugging new applications. Because the DEBUG build includes the debugging functions, it is larger and runs more slowly than the other two versions. If the BLDTYPE is set to DEBUG, this version of a product is built in the <component>\WIN32\DEBUG directory. This will not affect any products that may exist in the WIN32\RETAIL directory. If you do not specify a build type, the DEBUG build type will be chosen.

Note The Microsoft Exchange Server sample applications are shipped in a compiled version, in the \BKOFFICE\BIN directory and its subdirectories. These applications have been compiled with the build type set to RETAIL. You can recompile these sample applications with the DEBUG build type. If you recompile an individual sample application, recompile the EXCHSDK library from the LIBSRC directory with the DEBUG build type before compiling the sample application to avoid link errors.

To build with the DEBUG version, type a command that includes the DEBUG flag . For example: NMAKE BLDTYPE=DEBUG

Retail Version

The RETAIL version of a Microsoft Exchange Server sample application includes no debug DLLs, performance monitoring, or profiling tools, so it has the best performance. A RETAIL version is usually built when you are satisfied with an application's functionality and performance. If the BLDTYPE is set to RETAIL, this version of a sample application is built in the <component>\WIN32\RETAIL directory. Therefore, it will not affect any applications that may exist in the <component>\WIN32\DEBUG directory. The compiled set of sample applications included with this SDK is built with the RETAIL build type.

To build with the RETAIL version, type a command that includes the RETAIL flag.

For example: NMAKE BLDTYPE=RETAIL


Automatic File Copying

The BASEMAKE.INC file automatically copies compiled import libraries (LIB) and static libraries (LIB) into the default \LIB\I386 directory under the \BKOFFICE root directory. You can change this default behavior by editing the \BKOFFICE\include\BASEMAKE.INC file and modifying the Inference Rules section.

Trying to compile with incompatible libraries causes linker errors. For information about including only compatible libraries, see Choosing Runtime Libraries.


Choosing Runtime Libraries

When you create Microsoft Exchange Server applications, it is important to determine which runtime libraries to include and which should be explicitly excluded. The Visual C++ compiler will not build products that include incompatible libraries. If you have attempted to link an incompatible library, the compiler will return a LNK4098 error.

Multithreaded runtime libraries are not compatible with single threaded libraries. Debug versions are not compatible with nondebug versions. The EXCHSDK.LIB and EXCHSDKD.LIB libraries are used to compile all the sample applications written for multithreaded support.

When programming with Visual C++, you choose or exclude libraries to be used only for the current project workspace.

To include a library for the current workspace, choose the Settings option in the Build menu. Click the C/C++ tab in the Project Settings dialog box. Select a library option from the Use run-time library list box.

To exclude libraries, click the Link tab in the Project Settings dialog box. Use the Ignore libraries or the Ignore all default libraries options to exclude any libraries that conflict.

The VERBOSE switch displays progress messages that indicate the libraries searched. The online Help for the Project Settings dialog box explains how to set the VERBOSE option and other linker options.

For more information about choosing runtime libraries, see Building Sample Applications in the Visual C++ Development Environment and the Visual C++ Programmer's Reference.


Choosing INCLUDE files

When compiling Microsoft Exchange Server applications, always include the EDK.H header file. This choice is designed to eliminate any problems with header files that require external header files to be included.


Building the Sample Gateway and Sample Mailbox Agent

The Microsoft Exchange Server SDK includes a functional gateway and a mailbox agent, which are the two main types of server applications. You can use these sample applications to learn how to construct new applications, and you can build them to test the setup of your development environment.

Sample Mailbox Agent

SMBAGENT, the sample mailbox agent, performs the functions of a list server. Users introduce a topic and SMBAGENT creates a specialized folder for it. Users can then post documents to the topic, and the documents will be delivered to all users who have joined it. Other users can join the topic, and thereafter will receive all the mail from that topic.

For instructions on building and running the sample mailbox agent, see SMBAGENT: Creating a Sample Mailbox Agent.

Sample Gateway

A gateway is a connector between a Microsoft Exchange Server system and a foreign mail system. Messages pass through the gateway and are translated from the format of one system to the format of the other. The gateway must keep information about each user in both environments. The sample gateway included with the Microsoft Exchange Server SDK can be compiled and used as it ships, or can be changed to suit your application. For information about building and running the sample gateway, see Sample Gateway and Applications.

For complete development information about gateways, see the Gateway Programmer's Reference.

Installation Steps

If you develop a gateway or mailbox agent, several installation steps are necessary to connect them with Microsoft Exchange Server. These steps have been automated for the Microsoft Exchange Server Sample Gateway and the Sample Mailbox Agent in the MBSETUP and GWSETUP programs, respectively.

These steps can also be performed manually or by building a batch file. For information about building and running sample utility programs manually or using a batch file, see Using a Batch File to Install SMBAGENT.


Sample Applications

The Microsoft Exchange Server SDK includes a number of client and server sample applications written in C or C++. You can use them in the following ways:

  • Compile and run the sample applications in their present form.
  • Add the sample applications directly to Microsoft Exchange Server for increased functionality.
  • Change the source code and create new applications that meet your organization's specific needs.

You can also use the sample applications as a learning tool by reviewing the source code, building the sample applications, and observing the methods employed.

Microsoft Exchange Server Sample Applications

The following sample applications are provided with the Microsoft Exchange Server SDK:

ACLEDIT: Modifying an ACL

ADDRINST: Installing an Addr-Type Object

BACKTEST: Creating Backup Files

CFGCODE: Generating a Packed Property Structure

CRARUN: Creating a Custom Rule Action

DIRSYNC: Importing and Exporting Mailboxes

DSEXPORT: Exporting Directory Objects

DSIMPORT: Importing Directory Objects

EXTDATVW: Viewing and Editing Extension Data

FIMPORT: Importing Folder Information

INSTFORM: Installing a Sample Form

MBINST: Installing a Mailbox Agent

MBLSAMPL: Accessing Mailboxes

MBXSERV: Viewing Messages in a Mailbox

POPPST: Creating a Customized Information Store

POSTSMPL: Mail-Enabling an Application

PROFINST: Installing a MAPI Profile

RPTDRIV: Monitoring Message Delivery

RULEEDIT: Manipulating Rules

SERVINST: Installing a Service

SMBAGENT: Creating a Sample Mailbox Agent

TOOLFORM: Creating a C or C++ Form

TRACK: Tracking and Auditing Messages

Gateway Sample Applications

The following sample applications are described in the Gateway Programmer's Reference:

EXTNINST: Installing an Administrator Extension

GWINST: Installing a Mail-Gateway Object

LOOKUP: Finding a Proxy Address

PERFTEST: Monitoring Performance

PROXYGEN: Generating a Proxy Address

QUEVIEW: Listing Gateway Folders

TMPLINST: Installing an Address Entry Template

XLATDRIV: Translating Messages

Sample Gateway and Applications


Building the Sample Applications

Once you have installed Windows NT Server, Microsoft Visual C++, the Microsoft Exchange Client, Microsoft Exchange Server, and the Microsoft Exchange Server SDK, you are ready to begin development work. For more information, see Development Environment.

At this point you can also use Visual C++ to build the Microsoft Exchange Server sample applications. You can do this in either of two ways:

  • From a command prompt See Building an Individual Sample Application, or see the sample application's description in Sample Applications.
  • Using the Visual C++ development environment See Building Sample Applications in the Visual C++ Development Environment.

Approximately 1 GB of hard disk space is adequate for setting up the development environment and building the sample applications.

Build Version Types

You can build two different versions of each sample application: DEBUG and RETAIL. See Building the Set of Sample Applications.

Tip Installing the Microsoft Exchange Server SDK creates the \BKOFFICE\BIN directory, copies a complete set of compiled sample applications into it, and adds this directory to your search path. To run a sample application you have built or modified instead of the compiled version in the search path, do one of the following:

  • Use the full pathname.
  • Modify the search path.
  • Run the sample application from the directory containing the object files.


Sample Application Syntax and Parameters

A syntax diagram is provided in each sample application section, as well as a list of required parameters, optional parameters, and descriptions. The syntax diagram shows the conventions that are followed.

Convention | Description
BOLD TEXT | Bold text represents literal expressions that must be typed exactly as shown, such as function names, structure names, and keywords. This text is shown in upper case format, although it may be typed in upper or lower case. In a few cases the program is case-sensitive for parameters, and these are shown in the required case.
<Bold italic text> | Bold italic text surrounded by brackets indicates expressions, such as parameters, where you replace the text and the brackets with the actual value.
|| | The OR or pipe symbol indicates that one of a set of parameters is required or optional, and the set is mutually exclusive.
[ ] | Brackets enclose optional syntax items. Type only the syntax within the brackets, not the brackets themselves.

Tip When using parameters for the Microsoft Exchange Server sample applications, you need not type the entire parameter on the command line. You can enter the minimum number of characters necessary to unambiguously identify a command-line flag. For example, /C= is enough to identify the /CONTAINER= flag, but /IMP= is not enough to distinguish between the /IMPORT, /IMPLINE and /IMPFILE flags.

Command-line parameters can be prepended with either a slash ("/") or dash ("-") character.


Sample Application Directory Structure

Installing the Microsoft Exchange Server SDK creates the following directory structure.

Microsoft Exchange Server SDK directory structure

Note The preceding figure shows only a subset of directories and subdirectories of the Microsoft Exchange Server SDK.

This installation's directories contain the following data:

  • \BKOFFICE Contains the README.WRI release notes file for the Microsoft Exchange Server SDK and other products.
  • \BKOFFICE\BIN Contains compiled sample applications and code libraries (.EXE files and DLLs).
  • \BKOFFICE\HELP Contains the online Help files, including SCHEMA.HLP.
  • \BKOFFICE\INCLUDE Contains the header files.
  • \BKOFFICE\LIB Contains code libraries (.LIB) for functions included in sample applications that can also be included in third-party applications. Subdirectories of the \BKOFFICE\LIB\ directory contain code libraries for other development platforms.
  • \BKOFFICE\SAMPLES\EXCHANGE Contains the component directories for sample applications. Each sample application can be built separately in its own component directory, or the entire set of applications can be built from this directory.
  • \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC Contains the component directories for libraries. Each library can be built in its own component directory, or the entire set of libraries can be built from this directory.
  • \BKOFFICE\BIN\SAMPLEGW Contains the set of files for a gateway setup program. This directory is separate to avoid conflicts between file names that are not unique. For example, the SETUP.INF file also appears in the mailbox agent setup program.

    Source files for the sample gateway elements are located in other \BKOFFICE\SAMPLES\EXCHANGE subdirectories. For example, compile the sample gateway in the \BKOFFICE\SAMPLES\EXCHANGE\GWSAMPLE directory. Compile the SGWADMIN.DLL library in the \BKOFFICE\SAMPLES\EXCHANGE\SGWADMIN directory.

  • \BKOFFICE\BIN\SAMPLEMB Contains the set of files for a mailbox agent setup program. This directory is separate to avoid conflicts between file names that are not unique. For example, the SETUP.INF file also appears in the gateway setup program files.

    Source files for the sample mailbox agent elements are located in other subdirectories of \BKOFFICE\SAMPLES\EXCHANGE. For example, compile the sample mailbox agent in the \BKOFFICE\SAMPLES\EXCHANGE\SMBAGENT directory. Compile the SMBADMIN.DLL library in the \BKOFFICE\SAMPLES\EXCHANGE\SMBADMIN directory.


Sample Application Input Files

Input files are included with all sample applications that require them. This allows you to immediately run the sample applications. See File Formats for information on the types of input files needed for Microsoft Exchange Server applications.

The following sample input files are provided.

Sample Input File | Description
PROXYGEN.DLL | Sample DLL for creating proxy addresses of the type EDK.
SAMPLE.INI | Input file of properties that can be used to produce the sample gateway property page.
FROMHR.CSV | Sample import file that can be used with DSIMPORT.
WCHECK.EXE | Sample form that sets up a two-person game of checkers.
CHEKRFORM.CFG | .CFG file that must be installed for WCHECK.
SMBADMIN.DLL | Sample DLL for the mailbox agent.
RULEEDIT.INI | Sample .INI file used by the RULEEDIT sample to modify the rules on a mailbox.
POPPST.INI | Sample .INI file to install in a new PST. Also includes a section that provides values for the properties of a new message, and a section that adds this message to an existing PST.

A batch file you can use to install the mailbox agent is also provided. See Using a Batch File to Install SMBAGENT.


Building the Set of Sample Applications

All the sample applications are shipped in two forms: as compiled, executable files and as source files. You can rebuild the sample applications as a set or individually. Rebuilding the sample applications is useful for the following purposes:

  • Creates a set of sample applications with the DEBUG build type. This allows you to extract more information about the sample applications from the Visual C++ interface.
  • Acts as a test of your development environment.
  • Simplifies the process of building a complex sample application that requires several other sample applications to be built before it can run.

You will need Visual C++ version 4.0 or later on your system, which can be used to compile both C and C++ files and must be part of the development environment.

A WIN32 subdirectory is added below the current directory for each sample application. A subdirectory is added below the WIN32 subdirectory for the build type. For example, if the build type is DEBUG, this subdirectory is called DEBUG. All object files, .LIB files, and output files are placed in the build type subdirectory. In this way, DEBUG and RETAIL versions of a product can exist simultaneously in the same directory tree.

To build the set of all sample applications
  1. Change to the directory containing the sample applications:

    \BKOFFICE\SAMPLES\EXCHANGE

  2. Type NMAKE [BLDTYPE=RETAIL].

    This command builds each library in order, then combines all the libraries into the ExchSDKd.LIB library (DEBUG) or the ExchSDK.LIB library (RETAIL).

Building all the sample applications may take 45 to 60 minutes. If stopped, then restarted, the process will compare all products and build only those that have changed since the last time it was invoked. In essence, the process will restart from where it stopped.


Building an Individual Sample Application

The shipped versions of the sample applications are built with the RETAIL build type. If do not specify a build type when building an individual sample application, it will be of the DEBUG build type. To build a sample application with the build type of DEBUG, rebuild the libraries in the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC directory with the build type of DEBUG. The combined library of the DEBUG build type is called EXCHSDKD.LIB. The combined library for the RETAIL build type is EXCHSDK.LIB.

In some cases, build products are copied to the directory from which the individual sample application is installed or run. In all cases, a Win32 subdirectory is added below the current directory and a subdirectory for the build type is added below it. All object files, .LIB files, and output files are placed in the DEBUG or RETAIL subdirectory according to build type.

The following procedure describes the general process of building individual sample applications.

To build an individual sample application
  1. Change to the directory containing the sample application:

    \BKOFFICE\SAMPLES\EXCHANGE\<sample application name>

  2. Type NMAKE [BLDTYPE=RETAIL].
  3. For usage information, type <application name> /? at the command prompt.
To rebuild the libraries with a DEBUG build type
  1. Change to the directory containing the makefile that builds all the libraries:

    \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC

  2. Type NMAKE.

    This builds all the libraries with the DEBUG build type.

Note You cannot rebuild the libraries from the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\EXCHSDK directory. This makefile only contains instructions for gathering the already compiled individual libraries into the EXCHSDK.LIB library. See Setting the Build Type.


Viewing the Output From Your Build

To view the output from your build, change the LOG= NMAKE switch to ON. This creates a log that you can check for errors. See Using NMAKE Switches.

To view build output for individual sample applications
  1. Change to the directory containing the sample application:

    \BKOFFICE\SAMPLES\EXCHANGE\<sample name>

  2. Type NMAKE [BLDTYPE=RETAIL] LISTOUT.

    The LISTOUT process works only when you are building a single sample application. LISTOUT is not available for a build of all the sample applications. The NMAKE LISTOUT command produces only the log file listing and no build products.


Cleaning the Directories of All Build Products

The NMAKE CLEAN command cleans the directory structure of all build products with a single build type. If you run this command from the \BKOFFICE\SAMPLES\EXCHANGE directory, all the build products with the specified build type will be removed from all directories. This includes the compiled sample applications, individual sample applications that you have built, and the contents of all subdirectories created by the builds.

You can also run the NMAKE CLEAN command from an individual sample application's directory. If run from an individual directory such as \BKOFFICE\SAMPLES\EXCHANGE\SMBAGENT, subdirectories of the specified build type under this directory are removed. In other words, DEBUG and RETAIL copies are removed separately.

To clean an individual sample applications's directories of all build products
  1. Change to the directory from which the sample application was built:

    \BKOFFICE\SAMPLES\EXCHANGE\<sample name>

  2. Type NMAKE [BLDTYPE=RETAIL] CLEAN.
To clean the entire directory tree of all build products
  1. Change to the directory from which all the sample applications are built together:

    \BKOFFICE\SAMPLES\EXCHANGE

  2. Type NMAKE [BLDTYPE=RETAIL] CLEAN.


ACLEDIT: Modifying an ACL

The ACLEDIT sample application demonstrates how to modify a public folder's access control list (ACL) in a Microsoft Exchange Server information store. An ACL is a table that lists the users with specific permissions on a given folder and those associated permissions. The ACL includes entries for roles such as owner permissions, contact permissions, and default permissions. ACLEDIT demonstrates the functions of the ACLCLS.LIB library. See About Access Control Lists.

To build ACLEDIT.EXE and ACLCLS.LIB
  1. Change to the directory containing the ACLEDIT source files:

    \BKOFFICE\SAMPLES\EXCHANGE\ACLEDIT

  2. Type NMAKE.
  3. Change to the directory containing the ACLCLS.LIB source files:

    \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\ACLCLS

  4. Type NMAKE.


ACLEDIT Syntax and Parameters

To run ACLEDIT

Type the following on the command line:

ACLEDIT /PROFILE=<profile name> /STORE=<name of store> /FOLDER=<full path name of folder> || /INBOX

COMMAND=

/LIST [/POSITION=<ACL number>] ||

/INSERT /RIGHTS=<selection from permissions list> /USER=<user

display name> [/POSITION=<ACL number>] ||

/MODIFY /POSITION=<ACL number> /RIGHTS=<selection

from permissions list>] ||

/DELETE /POSITION=<ACL number>

Only a single command can be entered on a line.

ACLEDIT Parameters

Parameter | Settings
/PROFILE= | Specifies the MAPI profile name of the person or application running the ACLEDIT application. If the profile name contains spaces, enclose it in quotation marks. This parameter allows the ACLEDIT process to log on to MAPI and open the public folder store.
/FOLDER= | Specifies the full path name of the folder. If the name of the folder contains spaces, enclose it in quotation marks. Because a path to a nested folder is indicated with the use of backslash characters, a folder name that contains a backslash character is not valid for ACLEDIT. When accessing the public store, use IPM_SUBTREE to indicate the top for the public folders. For example: ACLEDIT /PROFILE="BLACK" /STORE="PUBLIC FOLDERS" /FOLDER="IPM_SUBTREE\TEST FOLDER" /LIST
/STORE= | Specifies the name of the information store containing this folder. For example: /STORE="Public Folders"
/INBOX= | Specifies the inbox associated with the named profile. The inbox must be Microsoft Exchange Server-based.
/LIST | Lists the entire ACL associated with this mailbox or folder. Use the optional /POSITION parameter to list a single position within the list.
/COMMAND= | Specifies the modification you want to perform: /INSERT, /MODIFY, /LIST, or /DELETE.
/INSERT | Inserts the right specified by the /RIGHTS parameter in the last position of the ACL of the user specified by the /USER parameter.
/MODIFY | Modifies the right at the position specified by the /POSITION parameter in the ACL associated with the specified profile.
/DELETE | Deletes the right at the position specified by the /POSITION parameter in the ACL associated with the specified profile.
/RIGHTS= | Indicates the specific permissions being modified. A table of all possible permissions values follows.
/USER= | Indicates the display name of the user who is being granted permissions on this mailbox.
/POSITION= | Specifies the number associated with this entry.


ACLEDIT Permissions

The following table lists the possible values for the /RIGHTS parameter. The permissions are granted to the user to perform the actions that appear in the description column.

Permission | Description
READANY (READONLY) | Read any message in the folder. Default.
CREATE | Create messages in the folder.
EDITOWNED | Edit any messages owned by himself in the folder.
DELETEOWNED | Delete any messages owned by himself in the folder.
EDITANY | Edit any messages in the folder.
DELETEANY | Delete any messages in the folder.
CREATESUBFOLDER | Create subfolders within the folder.
OWNER | Set permissions on the folder.
CONTACT | Establishes the user as the contact person for the folder.
NONE | No permissions.
READWRITE | Read and edit any items.
ALL | Includes all permissions except Contact permissions.


Modifying Permissions with ACLEDIT

The following procedure gives examples of the command lines used to modify user access permissions using ACLEDIT. The first command shows how to list the current access permissions. The second command shows how to grant another user (Test Account) several access permissions on Karin Gallagher's mailbox. The third command shows how to delete one of the users who has permissions to Karin Gallagher's mailbox.

To modify user access permissions using ACLEDIT
  1. List the access permissions for the user inbox of Karin Gallagher by typing the following command:

    ACLEDIT /PR="Karin Gallagher" /INBOX /LIST

  2. Give a second user, Test Account, the readany and editowned permissions to Karin Gallagher's inbox by typing the following command:

    ACLEDIT /PR="Karin Gallagher" /INBOX /INSERT /RIGHTS="READANY EDITOWNED" /USER="Test Account"

  3. Delete the member in position 10 of the ACL of Karin Gallagher's inbox by typing the following command:

    ACLEDIT /PR="Karin Gallagher" /INBOX /DELETE /POS=10

The next procedure gives examples of the command lines used to modify public folder permissions using ACLEDIT. The first command lists all the access permissions on TEST FLDR. The second command gives the CREATE SUBFOLDER and CONTACT permissions to TEST FLDR to the Test Account.

To modify public folder permissions using ACLEDIT
  1. List the permissions for the public folder labelled TEST FLDR on the public folder store of the MYSERVER server by typing the following command on one line:

    ACLEDIT /PR="MYSERVER" /STORE="PUBLIC FOLDERS" /FOLDER="IPM_SUBTREE\TEST FLDR" \LIST

  2. Give the CREATE SUBFOLDER and CONTACT permissions to the Test Account profile by typing the following command:

    ACLEDIT /PR="SERVER2" /STORE="PUBLIC FOLDERS" /RIGHTS="CREATE SUBFOLDER CONTACT" /NAME="Test Account"

To modify folder permissions in the PST using ACLEDIT

List the permissions for the My Folder folder in the private information store (PST) by typing this command on one line:

ACLEDIT /PR="MYSERVER" /STORE="MAILBOX - Karin Gallagher" /FOLDER="TOP OF INFORMATION STORE\My Folder" /LIST

The ACLEDIT /LIST screen output lists all members with permissions to a public folder or mailbox along with their permissions. The member permissions that are displayed are restricted by the security context. If you do not own the folder whose permissions you are editing, ACLEDIT displays only your permissions on the folder and those of the folder's contact person. If you do own the folder, ACLEDIT displays all folder members and their permissions.

If a user requests permissions that are disallowed, ACLEDIT returns a message to the user listing the actual permissions that are set rather than the permissions that have been requested.

For example, position 0 always contains the DEFAULT member. Position 1 always contains the FOLDER CREATOR member. These members cannot be deleted or replaced. They can only be modified. If you attempt to place another member at position 1, the FOLDER CREATOR member at position 1 will be returned instead.

If a user already has specific permissions on a folder, you cannot use the INSERT command to give this user additional permissions, but you can use the MODIFY command to modify the existing entry.

Note If you use ACLEDIT to give Folder Owner permissions to a user, read and write permissions are not automatically included. Granting the actual read and write permissions is a separate step, even to the folder's owner. The new folder owner can grant read and write permissions, but does not have these permissions until they are specifically assigned.


ACLCLS.LIB Functions

The ACLCLS.LIB library contains the following functions.

Function | Purpose
HrFolderACLsOpen | Retrieves a pointer to an object which implements the IExchangeFolderACLs interface defined in ACLCLS.H.
CFolderACLs::Create | Creates a new instance of the CFolderACLs object. Also take care of setting up the standard OLE dispatch object pointer for the new instance.
CFolderACLs::HrGetTableEntry | Retrieves an IExchangeModifyTable ACL table entry using the entry identifier. This method is used to examine the table entries and determine if a requested action was completed. This check is necessary because IExchangeModifyTable code may reset permissions, add entries, etc.
CFolderACLs::HrOpen | Opens the object on an ACLs folder.
CFolderACLs::QueryInterface | Returns a pointer to the object that implements the desired interface (if this object supports the interface).
CFolderACLs::AddRef- | Increments the reference count on this object.
CSROWLST::HrInitialize | Initializes a CSROWLST. An SRowSet is stored in the CSROWLST. The SROWNODES are ordered according to the order they are found in the table. Upon completion of this method (either successful or unsuccessful), all storage associated with lpRows is reassigned to the CSROWLST or is deallocated.
CSROWLST::HrDelete | Deletes the current record.
SROWLST::HrInsert | Inserts a new CSROWNODE before the current record and advances the cursor.
CSROWLST::HrRemove FromLst | Removes the current record from the list and makes it available to the caller. The caller is responsible for deleting the record when it is no longer needed.
CSROWLST::SetCursor | Standard C++ set member function that sets the current cursor position.
SROWLST::HrWriteToTable | Writes the contents of the CSROWLST to the table.


ACLEDIT Sample Code

The following source files for the ACLEDIT sample application are included in this SDK:

  • ACLEDIT.CPP
  • ACLCLS.CPP
  • ACLCLSF.CPP
  • ACLCLSI.CPP
  • SROWLST.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


ADDRINST: Installing an Addr-Type Object

The ADDRINST sample application demonstrates how to install an Addr-Type object in the directory. ADDRINST also installs the proxy generation DLL associated with the object.

Every gateway has an associated address type that corresponds to the address format of the foreign system the gateway serves. This address type is represented by an Addr-Type object pointing to the DLL that generates proxy addresses in the gateway's format.

When the Addr-Type object is created, a mailbox of its type is also created for each user on the server. After ADDRINST is executed on a server, mailboxes for new recipients that are added to the server will be of the new type. For more information, see The Addr-Type Object and Gateway Setup Programs.

ADDRINST can be used to install a new address type or remove an existing one. Functions used by ADDRINST to install a new address type are also used by GWSETUP (the gateway setup program). These functions can be found in the EXCHINST.LIB library.

For usage information, type ADDRINST /? at a command prompt.

Note Each gateway is linked with a single proxy generation DLL for each address type. If you create a new DLL and install it using ADDRINST, it will replace any existing proxy addresses of the selected address type.

To build ADDRINST
  1. Change to the directory containing the ADDRINST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU

  2. Type NMAKE.


ADDRINST Syntax and Parameters

To run ADDRINST

Type the following on the command line:

ADDRINST /SITEDN=<site distinguished name> /NAME=<display name> /MACHINE=<computer type> /TYPE=<address type> /PROXYDLL=<proxy generation DLL> /SERVER=<server computer name> /GWPROXY=<gateway site proxy address> [/DELETE] [/HELP or /?]

ADDRINST Parameters

Flag | Settings
/SITEDN= | Specifies the organization name plus the site name. For example: /SITEDN=/o=Microsoft /ou=APPS-WGA
/NAME= | Specifies the display name of the new address type. For example: EDK
/MACHINE= | Specifies the type of computer on which the proxy generation DLL is installed. For example: i386, MIPS, ALPHA
/TYPE= | Gives the address type, such as EDK, EX, or PROFS.
/PROXYDLL= | Gives the full pathname of proxy generation DLL unless you are in the directory where the file resides, in which case the simple name is also correct. For example: /PROXYDLL=C:\EXCHSRVR\ADDRESS\EDK \i386\PROXYGEN.DLL.
/SERVER= | Specifies the server computer name.
/GWPROXY= | Specifies the site proxy address for the gateway. For example: EDK:@mysite.microsoft.com
/DELETE | Deletes this address type rather than installing it.
/HELP or /? | Displays Help information.


Installing an Addr-Type Object in the Directory

You install an Addr-Type object in the Microsoft Exchange Server directory using the PROXYGEN.DLL that is included in the \BKOFFICE\BIN directory. Installing an Addr-Type object has the following effects:

  • The Addr-Type object exists in the directory and administrative operations can be performed on it.
  • As new users are installed, they automatically receive e-mail addresses of this type.
  • Existing users receive new e-mail addresses of this type.
To install an Addr-Type object in the directory
  1. Copy a proxy generation DLL (for example, PROXYGEN.DLL) onto the correct directory on the Microsoft Exchange Server computer. Each server has a top-level shared directory called \\<server name>\ADDRESS. The directory path is composed of the path to the ADDRESS directory, a directory name that matches the address type, and a directory name that matches the computer type. For example:

    CD /D C:\EXCHSRVR\ADDRESS

    MD EDK

    CD EDK

    MD I386

    CD I386

    XCOPY \BKOFFICE\BIN\PROXYGEN.DLL

  2. To install an Addr-Type object with the EDK address type on the MYSERVER server using the PROXYGEN.DLL library, type the following command on one line:

    ADDRINST /SITEDN=/o=Microsoft /ou=APPS-WGA /NAME=EDK /MACHINE=i386 /TYPE=EDK /PROXYDLL=\\MYSERVER\ADDRESS\EDK\I386\PROXYGEN.DLL /SERVER=MYSERVER /GWPROXY=EDK:@MICROSOFT.COM

To delete an Addr-Type object
  1. To delete an object under the same conditions, type the following command all on one line:

    ADDRINST /SITEDN=/o=Microsoft /ou=APPS-WGA /NAME=EDK /MACHINE=i386 /TYPE=EDK /PROXYDLL=\\MYSERVER\ADDRESS\EDK\I386\PROXYGEN.DLL /SERVER=MYSERVER /GWPROXY=EDK:@MICROSOFT.COM /DELETE

  2. Verify that the object has been deleted by opening a mailbox and making sure that it contains no address of the specified address type.

Note Because the operation of creating new e-mail addresses is asynchronous, the event log should be examined for task completion before performing any command that requires new proxy addresses to be installed.


EXCHINST.LIB Functions

The EXCHINST.LIB library contains the following functions.

Function | Purpose
CbMultiSz | Gives a count of bytes in a REG_MULTI_SZ string, not including a terminating NULL
HrGetRegistryValue | Obtains a Windows NT Registry value and allocates memory to hold it.
FCsvGetField | Extracts the field requested if given a record, a field separator, and a field number.
FCsvGetRecord | Fills the buffer with a single line read from the file if given a buffer, the buffer's length, and a file handle.
HrEDKExportObject | Exports an object from a server.
HrEDKImportObject | Imports an object into a server.
HrDeleteObject | Deletes an object from a Microsoft Exchange Server
HrEDKObjectExists | Checks if an object exists in the directory.
HrEDKEnumAttrib | Enumerates the given attribute.
HrEDKEnumDNs | Enumerates the DN(s).
HrEnumOrganizations | Enumerates the organization name(s).
HrEnumSites | Enumerates the site name(s).
HrEnumContainers | Enumerates the container name(s).
HrInstallService | Installs a service associated with a Microsoft Exchange Server object.
HrGetRegistryString | Gets a string value from the registry.
HrGetServiceServerName | Gets the Microsoft Exchange Server name associated with the service.
HrGetServiceSiteDN | Gets the site DN of the Microsoft Exchange Server object associated with the service.
HrGetServiceCommonName | Gets the common name of the Microsoft Exchange Server object associated with the service.
HrGetServiceObjectGUID | Gets the object GUID associated with the service.
HrGetServiceProductGUID | Gets the product GUID associated with the service.
HrGetServiceDisplayName | Gets the display name associated with the service.
HrGetServiceExecutableName | Gets the executable file name associated with the service.
HrGetServiceAccountName | Gets the account name associated with the service.
HrRemoveService | Removes a service.
HrNameContained | Determines if the name is in the list.
HrEDKAddServiceToLinkage | Adds service name to the export value in the key.
HrInstallServicePerfMon | Installs service performance monitoring.
HrDeleteContainedKeysInternal | Deletes keys recursively. Also passed in lpszwName for storage.
HrDeleteContainedKeys | Enumerates the subkeys of a key and deletes them one by one recursively.
HrRemoveRegistry | Removes the registry for the service.
HrRemoveName | Removes the service name from the export list and signals if now empty.
HrRemoveServicePerfMon | Removes service performance monitoring.
HrInstallGateway | Installs a gateway into a given site.
HrRemoveGateway | Removes a gateway from a given site.
HrGatewayExists | Checks if a gateway exists on a given site.
HrInstallMailboxAgent | Installs a mailbox agent into a given site.
HrRemoveMailboxAgent | Removes a mailbox agent from a given site.
HrMailboxAgentExists | Checks if a mailbox agent exists on a given site.
HrInstallAddressType | Installs an Addr-Type object into a given site.
HrRemoveAddressType | Removes an Addr-Type from a given site.
HrAddressTypeExists | Checks if an Addr-Type exists on a given site.
HrGetAddressTypeVersion | Gets the version of an Addr-Type object in a given site.
HrInstallAddressTemplate | Installs an address template into a given site.
HrRemoveAddressTemplate | Removes an address template from a given site.
HrAddressTemplateExists | Checks if an address template exists on a given site.
HrInstallAdminExtension | Installs an Administrator extension into a given site.
HrRemoveAdminExtension | Removes an Administrator extension from a given site.
HrAdminExtensionExists | Checks if an Administrator extension exists on a given site.
HrGetAdminExtensionVersion | Returns the version of an Administrator extension in a given site.
HrInstallContainer | Installs a container in the directory.
HrRemoveContainer | Removes a container from the directory.
HrContainerExists | Checks if a container exists in the directory.
HrInstallAddressTemplate Container | Installs an address template container in the directory.
HrRemoveAddressTemplate Container | Removes an address template container from the directory.
HrAddressTemplateContainer Exists | Checks if an address template container exists in the directory.
HrAddDelGatewayProxy | Adds or deletes a site proxy address for the given site.
HrInstallGatewayProxy | Installs a site proxy address into a given site.
HrRemoveGatewayProxy | Removes a site proxy address from a given site.
FHasAdminPrivs | Returns TRUE if the current user is an administrator.
HrInstallMessageConverter | Installs a message conversion DLL.
HrRemoveMessageConverter | Deletes a message conversion DLL.
HrAdminProgramExists | Checks if the Administrator program has been installed on the local computer.
HrSetGatewayBit | Sets the gateway bit on a given server.


ADDRINST Sample Code

The following source files for the ADDRINST sample application are included in this SDK:

  • ADDRINST.C
  • EXCHPROF.C
  • EXCHINST.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


BACKTEST: Creating Backup Files

The BACKTEST sample application demonstrates how to create a backup and restore utility for Microsoft Exchange Server files. A default backup and restore utility is part of Microsoft Exchange Server software, but BACKUP demonstrates how to use the backup and restore application programming interfaces to create your own backup and restore utilities. BACKUP contains utilities to back up the directory information and the information store. It can also be used to perform remote backups.

BACKTEST is a simple application that does not contain all the functionality you would probably design in such an application for commercial use. It is provided as an example of functionality that can be presented.

To build BACKTEST
  1. Change to the directory containing the BACKTEST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\BACKTEST

  2. Type NMAKE.


BACKTEST Syntax and Parameters

To run BACKTEST

Type the following on the command line:

BACKTEST -T<MDB|DSA> [-S <Server to back up>] -[B <File to hold backup>] [-R <size of buffer > 8000 bytes>| r | R] [-I ][/HELP or /?]

BACKTEST Parameters

Flag | Settings
-T | Specifies backup type. This parameter should be set to MDB for information store backups and to DSA for directory backups. For example: -T MDB
-S | Specifies name of the server to be backed up. For example: -S edkdocs20
-B | Specifies name of the backup file.
-R | Specifies the size of the buffer. Users can select a size (always greater than 8000 bytes) or they can select r or R, which randomly selects a size between 0 and cbReadHintSize (defaults to 65536). For example: BACKTEST -T:MDB -B:Output.bak -R:50000 – Or – BACKTEST -T:MDB -B:Output.bak -R:r
-I | Specifies an incremental backup. Circular file logging must be disabled during incremental backups because they are not compatible.
/HELP or /? | Displays Help information.

For both BACKTEST and RESTTEST, flags may be preceded with a slash(/) or a dash(-). There must be a space or a colon after each flag and before its parameters.

Backups can be either incremental or full. Restores can be full or incremental as well, but incremental restores cannot be done on a database until after a full restore has been done. A number of incremental restores may be applied consecutively without a full restore, but they must be done in order. Also, the computer must not be restarted until all the incremental restores have been applied.

Note Selecting a buffer size less than 8000 bytes causes unpredictable results.

To run RESTTEST

Type the following on the command line:

RESTTEST -B <backup file> [-S <server to restore>]

RESTTEST Parameters

Flag | Settings
-B | Specifies backup file. This file should be created with the BACKTEST command. For example: -B backt3
-S | Specifies name of the server to be restored. If this flag is not entered, the GetComputerName function is called to provide the name of the server. For example: -S edkdocs20


Backing Up Data with BACKTEST

To back up data using BACKTEST
  1. To back up the information store of the EDKDOCS20 server, type the following command:

    BACKTEST -T MDB -S edkdocs20 -B backt1

    The following messages appear during the backup process. Note that BACKTEST can also be used to give performance information.

    Back up E\\edkdocs20\C$\exchsrvr\MDBDATA\PRIV.EDB
EcBackupOpenFile took 157 milliseconds
Read 1056768 bytes from the file, 0.728s 1451.604396 kb/second.
Back up F\\edkdocs20\C$\exchsrvr\MDBDATA\PUB.EDB
EcBackupOpenFile took 123 milliseconds
Read 1056768 bytes from the file, 0.752s 1405.276596 kb/second.
Back up !\\edkdocs20\C$\exchsrvr\MDBDATA\\edb00002.log
EcBackupOpenFile took 36 milliseconds
Read 5242880 bytes from the file, 4.057s 1292.304659 kb/second.
Back up (\\edkdocs20\C$\exchsrvr\MDBDATA\PRIV.pat
EcBackupOpenFile took 35 milliseconds
Read 8192 bytes from the file, 0.040s 204.800000 kb/second.
Back up (\\edkdocs20\C$\exchsrvr\MDBDATA\PUB.pat
EcBackupOpenFile took 40 milliseconds
Read 8192 bytes from the file, 0.023s 356.173913 kb/second.
All logs and files backed up.
ecResult: The operation was successful
 (0/0x0)
  2. Verify that the backup was performed by checking that the backup file is not empty. For a final check, restore the backed up data.
To restore backed up data
  1. To restore the information store of the EDKDOCS20 server that was backed up, type the following command:

    RESTTEST -B backt1 -S edkdocs20

  2. Verify the restore by starting the Administrator program and checking that the backed up data is displaying (rather than the previous data).


BACKTEST Sample Code

The following source files for the BACKTEST sample application are included in this SDK:

  • BACKTEST.C
  • RESTTEST.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


CFGCODE: Generating a Packed Property Structure

The CFGCODE sample application demonstrates how to create a packed property structure that can be unpacked using the HrCfgUnpackData function. It uses a text file containing a list of MAPI properties, and produces a file containing the binary packed property structure. You can specify the name of the input file section to read from, and a configuration name to be placed at the front of the resulting packed (binary format) property structure. For more information, see Creating the Directory Object.

The file you create with CFGCODE can provide default extension data for a server application.

For usage information, type CFGCODE /? at the command prompt.

To build CFGCODE
  1. Change to the directory containing the CFGCODE source files:

    \BKOFFICE\SAMPLES\EXCHANGE\CFGCODE

  2. Type NMAKE.


CFGCODE Syntax and Parameters

To run CFGCODE

Type the following on the command line:

CFGCODE <Infile> <Outfile> [SECTION=<section of INI file>] /NAME=<configuration name to store in packed data> [/HELP or /?]

CFGCODE Parameters

Flag | Settings
<Infile> | Specifies name of the .INI file containing the list of properties to be packed. Example: CFGCODE.INI
<Outfile> | Specifies name of the output file to which the packed configuration data should be written. Example: CFGCODE.DAT
/SECTION= | Specifies name of the [Section] in the .INI file. Example: [Mysection].
/NAME= | Specifies the configuration name to store as a heading within packed data.
/HELP or /? | Displays Help information.


Generating a Packed Property File

To generate a file containing a binary packed property structure
  1. Write an input file that contains the information to be packed. The format of this text file is described in The CFGCODE Input File.
  2. Run CFGCODE, specifying the name of the input file, a name for the output file, and a configuration name using the /NAME switch. Output files often use the .DAT extension. You also specify a section of the input file with the /SECTION= switch. Extension-data owner tags are described in the section Using the Extension-Data Attribute.


The CFGCODE Input File

Input to CFGCODE is from a text file in the format of an .INI file. It contains a section header and a list of MAPI properties. The properties can be of the following MAPI property types:

  • PT_LONG
  • PT_BOOLEAN
  • PT_SYSTIME
  • PT_STRING8
  • PT_BINARY

Example: Input File to Test CFGCODE

The following is the text of the SAMPLE.INI input file. It is included with the Microsoft Exchange Server SDK and can be used to test the CFGCODE sample application. MAPI properties in this file are read from the [MySection] section:

;
; Sample INI file for CfgCode.Exe
;

[MySection]
0fff0102=01 23 45 67 89 ab cd ef
0005000b=1
00090003=255
3001001e=Accounting
30080040=1996/02/26 13:28:47

[AnotherSection]
0fff0102=fe dc ba 98 76 54 32 10
0005000b=1
00090003=255
3001001e=Marketing
30080040=1996/02/26 13:28:50

In this example, the [MySection] section is read only if the /SECTION= flag is set to [MySection] on the CFGCODE command line. Because only one section can be read from the input file at a time, the [AnotherSection] section is ignored. If the /SECTION= flag is set to [AnotherSection], the [MySection] section will be ignored.

Example: Input File to Display SGWADMIN Data

The following is another example of an input file. It shows the data used by SGWADMIN, which is the sample gateway's Administrator extension DLL. In this example, the first four digits of the property tags number them sequentially; the final four digits identify the MAPI property type as specified in MAPIDEFS.H. For example, PT_TSTRING is defined as 001e, which is used for all the string values in this file.

MAPI property tags are specified in eight-digit hex values. Because the values of MAPI property tags can be represented in the last four digits, you can choose arbitrary values for the first four digits.

[SGWData]
; Enable inbound processing
0001000b=1
; Enable outbound processing
0002000b=1
; Number of inbound processing threads
00030003=1
; Number of outbound processing threads
00040003=1
; Number of messages processed per inbound thread
00050003=1
; Number of messages processed per outbound thread
00060003=1
; Inbound submit interval
00070003=1000
; Outbound submit interval
00080003=1000
; Inbound polling interval
00090003=-1
; Outbound polling interval
000a0003=-1
; Address type
000b001e=EDK
; System Administrator Display Name
000c001e=System Administrator
; System Administrator Email Address
000d001e=sysadmin
; Inbound directory
000e001e=\in
; Outbound directory
000f001e=\out
; Inbound conversion
0010001e=SAMPLEGW.INBOUND
; Outbound conversion
0011001e=SAMPLEGW.OUTBOUND


CFGCODE Output

In the preceding example, CFGCODE packs data into a file that initializes the sample gateway property page of a gateway's directory object. Many of the values that can be found in the example file text are visible when you display this property page, as shown in the following figure.

The sample gateway property page


CFGCODE Sample Code

The following source file for the CFGCODE sample application is included in this SDK:

  • CFGCODE.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


CRARUN: Creating a Custom Rule Action

Microsoft Exchange Server rules are evaluated against each message coming into a folder or mailbox. The CRARUN sample application is a client-side rule extension that launches an application on the client. See Installing the CRARUN Launch Application and Running the CRARUN Launch Application.

To build CRARUN
  1. Change to the directory containing the CRARUN source files:

    \BKOFFICE\SAMPLES\EXCHANGE\CRARUN

  2. Type NMAKE.

To install the CRARUN sample application, the installation of the CRARUN sample application needs REGINI.EXE, which is found in the Windows NT Resource Kit. This means that you must first modify the registry manually using the REGEDT32.EXE utility.

To prepare the registry for installing CRARUN
  1. Start REGEDT32.EXE.
  2. Under the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Exchange\Client, create a new key called Custom Actions.
  3. Under this Custom Actions key, create a value called Launch and assign to it a value of

    4.0;path\crarun.dll;1;00000101001100

    where path is replaced by the full path name, including the drive letter, to CRARUN.DLL.


Installing the CRARUN Launch Application

To install the Launch custom rule action at the client
  1. Change to the directory containing the CRARUN source files:

    \BKOFFICE\SAMPLES\EXCHANGE\CRARUN

  2. Replace the directory with your source file directory by typing a command similar to this:

    INSTALL C:\BKOFFICE\SAMPLES\EXCHANGE\CRARUN

    You should receive the following acknowledgment:

    00 0000  KeyName:
\registry\machine\software\Microsoft\Exchange\Client\Custom
 ActionsUpdated value for Key:
\registry\machine\software\Microsoft\Exchange\Client\Custom
 Actions\Launch = 'REG_SZ
"4.0;c:\exchsdk\samples\exchange\crarun\crarun.dll;1;0000010
1001100"'
Custom Launch Rule Installed!
To verify that the custom rule action was installed
  1. Choose Windows NT Diagnostics from the Administrative Tools group.
  2. Choose Registry Editor from the Tools menu in the Windows NT Diagnostics dialog box. Several windows representing Windows NT Registry keys appear.
  3. From the HKEY_LOCAL_MACHINE on Local Machine window, choose SOFTWARE. Choose EXCHANGE\CLIENT\CUSTOM RULE ACTIONS and click once. The CRARUN.DLL custom rule action DLL should appear.


Running the CRARUN Launch Application

Once you have installed the CRARUN Launch application, you can use it to set up a rule that starts an application of your choice when it fires.

To run the Launch application
  1. Start the Microsoft Exchange Client.
  2. From the Tools menu, select Inbox Assistant. A screen such as the following is displayed:

  3. Click Add Rule. The Edit Rule dialog box appears.

  4. Click in the Custom box. Pull down the combo box. The Launch custom rule should appear. Select Launch.
  5. The Program to Launch dialog box appears. Select a program to launch if the rule fires, for example, C:\WINNT\NOTEPAD.EXE.

  6. Click OK in the Program to Launch dialog box.
  7. Select a condition under which you want the rule to fire, for example, From a certain user. Then click OK in the Edit Rule dialog box.
  8. You should see the custom rule in the Conditions box of the Inbox Assistant dialog box. Click OK.

  9. Optionally, test the condition that fires the rule. For example, send a message from the selected user to the profile that contains the custom rule. The rule should fire; in this case, NOTEPAD.EXE should automatically start.


CRARUN Sample Code

The following source files for the CRARUN sample application are included in this documentation:

  • CRARUN.CPP
  • ENTRY.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


DIRSYNC: Importing and Exporting Mailboxes

The DIRSYNC sample application demonstrates how to transfer mailboxes and custom recipient information between foreign systems and a container on Microsoft Exchange Server. It also shows how to use the directory access functions to build a transfer agent. Microsoft Exchange Server software includes a directory replication process for transferring directory information between servers at a site, and a directory replication connector to extend that automatic process between sites. There is also a directory synchronization process to transfer information between Microsoft Exchange Server and Microsoft Mail 3.X systems. DIRSYNC can be used to transfer information between Microsoft Exchange Server and other foreign mail systems.

DIRSYNC can be manually called to perform the following actions:

  • Export incremental updates of mailbox attributes from a container on Microsoft Exchange Server to a foreign system.
  • Export attributes of all mailboxes from a container on Microsoft Exchange Server to a foreign system.
  • Import incremental updates about mailbox changes or custom recipient changes from a foreign system to a container on Microsoft Exchange Server.
  • Import attributes of all mailboxes or custom recipients from a foreign system to a container on Microsoft Exchange Server.

DIRSYNC uses Windows NT Registry key values and directory attributes to determine which information to export or import. Each time DIRSYNC is called for export, it uses the USNChanged directory attribute to determine whether any changes have been made since the last export. For more information, see Exporting and Importing Changed Objects.

When the DIRSYNC sample application is used for export, the parameters specified can change the basic DIRSYNC operation. When the /EXPFULL flag is specified, the attributes for the entire set of mailboxes in that container are exported. If the /SUBS flag is specified, attributes for mailboxes in subcontainers of the selected container will also be exported. The /EXPLIST command-line flag allows you to specify which directory attributes you want to export. If /EXPLIST is not used, only the distinguished name (the name plus the full path, called the DN) of the mailbox is exported. For more information, see Building a New DIRSYNC Instance.

When the DIRSYNC sample application is used for import, DIRSYNC accepts a file created by the foreign system or database. This file must be in the exact format expected by DIRSYNC. An explanation of this syntax and an example of a DIRSYNC import file are included in Formatting DIRSYNC Import and Export Files.

When changes are imported by DIRSYNC into the directory, the state parameters for DIRSYNC are updated. DIRSYNC keeps a list of all the imported changes to assure that these changes will not be exported back to the foreign system. This list is used at the next export session and at that time is automatically erased.

Note For reliable ambiguous name resolution (ANR) when creating custom recipients, separate fields are required for last name, first name, and display names.


Building a New DIRSYNC Instance

The information used by DIRSYNC to execute its commands comes from one or both of the following sources:

  • Windows NT Registry
  • Command-line settings

Because DIRSYNC stores its configuration information in the registry, an instance name is generally used to give access to all the parameters in that instance. This instance name points to a location in the registry where the DIRSYNC configuration information is stored. If you specify an instance by its name only, DIRSYNC will look for its data in the following registry key:

HKEY-LOCAL-MACHINE\SOFTWARE\MS EXCHANGE SAMPLES\DIRSYNC\<instance-name>

The instance name is not necessary if all required information is supplied on the command line, or if the /KEY command-line flag is used to point to a registry key where instance data is stored.

You can use the the Windows NT Registry to create and view instances, or you can run DIRSYNC with the /SET command-line flag. If you use the /SET flag, parameters entered from the command line are copied into the registry, but the requested operation is not performed. Without the /SET flag, DIRSYNC creates a transient instance that uses command-line flags, but does not update the registry.

If you have not used the /SET flag, have not included all the information on the command line, and type an instance name that does not exist in the registry, DIRSYNC prompts you to create a new instance. If you answer Y, DIRSYNC writes to the registry key, but performs no operation — as if you had used the /SET flag. Answering N to this question exits the program.

To build DIRSYNC
  1. Change to the directory containing the DIRSYNC source files:

    \BKOFFICE\SAMPLES\EXCHANGE\DIRSYNC

  2. Type NMAKE.

The following procedure shows how to set up a new instance of DIRSYNC without using the /SET command-line flag and with /SET.

To set up a new DIRSYNC instance in the Registry
  1. Choose a name for your new instance.
  2. Type DIRSYNC and the instance name:

    DirSync <instance name>

    If you type the following command and use an unknown instance name, DIRSYNC displays this message:

    The instance <Instance-Name> is unknown. Create a new instance? (Y/N)
  3. Type Y in response.

    If you type N, DIRSYNC terminates immediately. If you type Y, DIRSYNC creates the new registry keys and all the default values, exits, and displays the following message:

    New NT Registry key created for instance HR-Database:
HKEY_LOCAL_MACHINE\SOFTWARE\EDK Samples\DIRSYNC\<Instance-Name>
  4. Display and change the required and optional parameters for this instance as you prefer by editing the registry keys as shown below. Spaces are allowed within instance names, as long as the command-line parameter is surrounded by quotes. For example: DIRSYNC "Instance Name With Spaces."
To set up a new DIRSYNC instance with the /SET command
  1. Type in all parameters to be set for the new instance and the /SET parameter. For example:

    DIRSYNC <instance name> /SET /EXPORT /SITEDN=/O=ORGANIZATION/OU=SITE
    /CONTAINER=Recipients /DSA=server1 /EXPLIST=
    Obj-Class,Common-Name,Display-Name,
    USN-Changed/EXPFILE=C:\EXPORT.OUT

  2. Verify that the instance has been created by editing the Windows NT Registry as shown in the next procedure.

To display and edit the new DIRSYNC instance
  1. Choose Windows NT Diagnostics from the Administrative Tools group.
  2. Choose Registry Editor from the Tools menu in the dialog box. Several windows representing Windows NT Registry keys appear.
  3. From the HKEY_LOCAL_MACHINE on Local Machine window, choose SOFTWARE. Choose Microsoft Exchange Server SDK Samples\DIRSYNC and click once.
  4. Click the directory icon for your new instance. All registry keys with their current values appear. Check that all the keys are correctly set.


DIRSYNC Registry and Command-Line Flags

Most DIRSYNC command-line flags correspond to values in the Windows NT Registry. When an instance is selected, the key values found in the registry are used to perform the DIRSYNC function. Command-line parameters override the registry (instance) values. Command-line flags can also be used to change the registry values if the /SET flag is used. The following table shows the corresponding registry values for DIRSYNC command-line flags. Any value listed as mandatory is required and can be supplied either from the registry or on a command line. Values listed as optional are not required and must be supplied from the registry.

The following command-line flags can be stored as part of the Windows NT Registry key. This key has the following path: HKEY_LOCAL_MACHINE\SOFTWARE\MS Exchange SDK Samples\DIRSYNC\<Instance>

Command-Line Flags Corresponding to the Instance Registry Key

Key Value | Command-Line Flag | Setting
Basepoint | /BASEPOINT= | Mandatory. Distinguished name (DN) of place in directory information tree (DIT) from which to start export—usually the DN of the Microsoft Exchange Server site. Example: /o=Organization/ou=Site.
Container | /CONTAINER= | Mandatory. Relative distinguished name (RDN) of container below the Basepoint from which to start the export. For example: Recipients.
DSA | /DSA= | Mandatory. Directory service agent (DSA) to which DIRSYNC should connect for import or export. Usually same as Microsoft Exchange Server name.
Export File | /EXPFILE= | Mandatory for export. Fully qualified name of file to which export information is written.
Export List | /EXPLIST= | Optional. Schema attributes to be exported, expressed as a comma-separated list. Example: Obj-Class,Common-Name,Display-Name. If this flag is not specified, only the DN for an object is exported.
Full Export | /EXPFULL /NOEXPFULL | Optional. Boolean flag indicating that the entire set of recipients should be exported, regardless of when objects were last changed. /NOEXPFULL = Exports changed objects (default) /EXPFULL = Exports all objects
Home Server | /HOMESERVER= | Optional. Specifies the default server to which imported mailbox information is to be added.
Import File | /IMPFILE= | Mandatory for import. Fully qualified name of file from which import information is read.
MV Append | /MVAPPEND /NOMVAPPEND | Optional. Boolean flag indicating that newly imported values for multivalued properties are to be appended to the existing properties. /NOMVAPPEND = Overwrites existing multivalued properties with new values. Default, /MVAPPEND = Appends new multivalued properties to existing ones.
NT Create | /NTCREATE /NONTCREATE | Optional. /NTCREATE creates a new Windows NT account for each added mailbox. If the Assoc-NT-Account attribute is specified, then that name is used. Otherwise, a default name is generated. The password is the same as the account name, padded with x if necessary to bring the length to the minimum required by the system. If no domain is given, the logon domain is used. /NONTCREATE negates /NTCREATE.
NT Delete | /NTDELETE /NONTDELETE | Optional. /NTDELETE deletes the associated Windows NT account of every mailbox that is being deleted. If the mailbox has no associated account, no account is deleted but the mailbox is still deleted. /NONTDELETE does not delete the mailboxes. Default.
Object Type | /OBJCLASS= | Optional. Type of directory objects created by import operations. Remote = Creates custom recipients (default) Mailbox = Creates a mailbox object
Progress Dialog | /PROGRESS /NOPROGRESS | Optional. Boolean flag indicating that a progress dialog should be displayed. Affects export only because import operations do not support a progress dialog /NOPROGRESS = No progress dialog (default) /PROGRESS = Display progress dialog
Server | /SERVER= | Optional. If set, server from which mailboxes will be exported.
Sub-containers | /SUBS /NOSUBS | Optional. Boolean flag indicating that export operations should recursively include subcontainers. /NOSUBS = Only exports specified container (default) /SUBS = Recursively exports all subcontainers starting with specified container
Type | /EXPORT /IMPORT /BOTH | Mandatory. Indicates instance type. No type specified (default) /EXPORT Exports instance /IMPORT = Imports instance /BOTH = Exports and imports instance

The following command-line flags can be stored as part of the instance Windows NT Registry key. This key has the following path: HKEY_LOCAL_MACHINE\SOFTWARE\MS Exchange SDK Samples\DIRSYNC\<Instance>\State.

Command-Line Flags Corresponding to the State Registry Key

Value | Command-Line Flag | Setting
Imported Object List |  | Binary table of imported USNs used to coordinate incremental imports and exports. This table is cleared after every export.
Last USN | /USN | Value of the most recent USN-Changed attribute exported. Setting this value to zero before running DIRSYNC forces the entire container to be exported (as will setting the Full Export flag).

The following command-line flags can only be entered from the command line.

DIRSYNC Command-Line Flags with No Windows NT Registry Equivalent

Command-Line Flag | Setting
/SET | Creates a new instance or modifies an existing instance. The Windows NT Registry is updated, but no export operation is performed.
/KEY=<Registry key> | Specifies an instance with an alternate registry location. Used instead of an instance name.
/DISPLAY | Displays the current registry settings for the instance or /KEY.
/? /HELP | Displays full Help information.


Importing and Exporting with DIRSYNC

Building and running DIRSYNC demonstrates a basic mechanism for synchronizing directories between a Microsoft Exchange Server system and a foreign mail system, or between Microsoft Exchange Server and a nonmail database. For example, the DIRSYNC agent can be integrated into a mail gateway application that coordinates address books between Microsoft Exchange Server and a foreign system such as PROFS.

The DIRSYNC sample application creates a file for export, or incorporates the changes from an import file to the directory. (Note: How the export file is used, or how to create the import file, is determined outside the scope of this sample application). The import and export files are identical, so if there is a Microsoft Exchange Server system at each end, DIRSYNC can be used both to export and import changes.

The following instructions explain how to build a gateway, run DIRSYNC to create an export file, and use DIRSYNC to import that file into the other system to incorporate its changes into the address book for two Microsoft Exchange Server sites. For purposes of this example, the two sites are created within the same organization. The following objects are created:

  • Testorg organization
  • Site1 site
  • Server1 server at Site1
  • Site2 site
  • Server2 server at Site2

In this example, the sample gateway is installed on Server1 and Server2 to connect the sites together for DIRSYNC.

To create a gateway for DIRSYNC
  1. Gather the necessary information for creating the gateway:
    • Organization name
    • Site name
    • Display name for gateway
    • Distinguished name (DN) for gateway
    • Service account name
    • Password for service account
  2. Install the sample gateway on both Server1 and Server2 following the instructions found in Sample Gateway and Applications.
  3. In the Address Type field, type the address type for the other site. For example, if one site is EDK and the other is SMTP, the SMTP site will have EDK typed in this field and the EDK site will have SMTP typed here. A proxy generation DLL that generates addresses of the other type must be associated with each site. For more information, see the Gateway Programmer's Reference.

    For this example, set the address type of both servers to EDK, which allows the PROXYGEN.DLL to be used as the proxy generation DLL.

  4. Verify that the sample gateway has been created on both servers by finding it in the Connections container within the Microsoft Exchange Server Administrator program for each site. See the Microsoft Exchange Server Administrator's Guide for more information.
  5. Create the following mailboxes:
    • For Server1: Mailbox 11, Mailbox 12, Mailbox 13.
    • For Server2: Mailbox 21, Mailbox 22.
To create a mailbox
  1. Start the Administrator program and connect it to the server on which you plan to create the mailbox.
  2. Change to the Recipients container.
  3. From the File menu, choose New Mailbox.
  4. Enter the information for the new mailbox. You can attach it to an existing Windows NT account or create a new account.
  5. Verify that the new mailbox has been created by finding it in the Recipients' container.

The following procedure demonstrates how to connect the two sites together through the gateway.

To connect two sites together through their gateways
  1. Start the Administrator program and connect it to Server1.
  2. Open the Connections container.
  3. Double-click the gateway icon to view its property sheet.
  4. Select the Sample Gateway property page. Find the Directory entry in the Outbound column. Change this entry to be the inbound directory of the other site. This path consists of the share name for the gateway plus \IN. For example: \\Server2\SAMPLEGW\IN.
  5. Follow the same procedure on Server2, connecting it to \\Server1\SAMPLEGW\IN. When you have finished, the OUT directory for each server should match the IN directory for the other server.

The following procedure demonstrates how to create a custom recipient on Server2 for Mailbox11. and a custom recipient on Server1 for Mailbox21. This allows the mailboxes to send test messages across the gateway.

To create a custom recipient
  1. At Server1, open the Recipients container and double-click Mailbox11. Select E-Mail Addresses.
  2. Find the EDK address type for the foreign system. The address is Mailbox11@Site1.Testorg.com.
  3. Start the Administrator program on Server2.
  4. Open the Recipients container.
  5. From the File menu, select New Custom Recipient.
  6. Fill in the fields for the custom recipient to match Mailbox11 information. The address of the custom recipient is the address you found on Server1, Mailbox11@Site1.Testorg.com. The address type is EDK.
  7. Click OK.
  8. Verify that the custom recipient has been created by making sure it appears in the Recipients container.
  9. Create a custom recipient on Server1 for Mailbox21 following the same procedure. This allows test messages to be sent in the opposite direction.

To make sure the gateway is operating properly, send several messages back and forth from Mailbox11 on Server1 through the gateway to Mailbox21 on Server2. When you start Microsoft Exchange client on the receiving computer, you should be able to see, open, and read the messages.

After the gateway is operating between the two sites, begin synchronization by exporting all existing mailboxes from one server to the other, then updating that server as changes occur.

To synchronize two sites
  1. Set up a new instance called INSTANCE1 (see the previous procedure). Use either the /SET command or the command line. This new instance should export information about mailboxes that have changed on Server1 to Server2. For example, export the Common-Name and Display-Name attributes for each mailbox to a file called SYNC1.
  2. Use INSTANCE1 to export all the existing mailboxes. This step should be followed even though custom recipients already exist at the other site. Add the /EXPFULL parameter on the command line (because this is the first export), but do not add it to the registry (because /EXPFULL will be used only once). For the first export, type the following command:

    DIRSYNC /EXPFULL INSTANCE1

  3. Import the attributes you exported from Server1 to Server2. At Server2, set up a new instance, INSTANCE2, to import the attributes that were exported from Server1 by INSTANCE1 (that is, Common-name and Display-name). Use the same name for the import file, SYNC1, that you used for the export file in INSTANCE1. Copy SYNC1 from Server1 to Server2. Type the following command:

    DIRSYNC INSTANCE2

    This command causes custom recipients for each mailbox exported from Server1 to be added to Server2.

  4. Verify that the custom recipients have been added by opening the Recipients container of the Administrator program on Server2 and viewing each mailbox.
  5. On Server2, create INSTANCE3 to export changes to Server1. Again, export the Common-Name and Display-Name for each mailbox. Select a different name for the export file than you selected for the export file from Server1. For example: SYNC2.
  6. Export all the mailboxes from Server2 to Server1 using INSTANCE3 along with the /EXPFULL parameter on the command line:

    DIRSYNC /EXPFULL INSTANCE3

  7. On Server1, create INSTANCE4 to import the changes from Server2 to Server1. Use the same file name, SYNC2, for your import file.
  8. Import the changes by copying SYNC2 from Server2 to Server1. Type the following command:

    DIRSYNC INSTANCE4

  9. Make some incremental changes on Server1. For example, add a new mailbox, Mailbox14. Change the display name for Mailbox12 on Server1. Delete Mailbox11 on Server1.
  10. Export the incremental changes using INSTANCE1 but not including the /EXPFULL parameter. Type the following command:

    DIRSYNC INSTANCE1

  11. Import these changes at Server2 by copying the newly created SYNC1 file from Server1 to Server2. Type the following command:

    DIRSYNC INSTANCE2

  12. Create incremental changes at Server2 in the same way you created changes at Server1. Export these changes to a new SYNC2 file by typing the following command:

    DIRSYNC INSTANCE3

  13. Import these changes at Server1 by copying the new SYNC2 file to Server1. Type the following command:

    DIRSYNC INSTANCE4

After you have established an import and export instance at each server they can be used to synchronize the two servers as further changes occur.

Should one server become disabled, another server at the site can be used for synchronizing, but the entire process — including the export of all the mailboxes — must be repeated between the servers. This is necessary because the attributes used to determine which mailboxes to export are specific to the now disabled server and the old instances cannot be used successfully.

Using DIRSYNC with Multiple Instances

DIRSYNC can be used to demonstrate how a single directory synchronization agent can coordinate requests from several sources, such as from two instances of the same gateway or from different gateways, with each source represented by a separate Windows NT Registry instance.

You can save multiple instances of DIRSYNC calls in the Windows NT Registry, but some precautions should be taken when running DIRSYNC with multiple instances:

If you are making incremental updates, create a different instance to run DIRSYNC from another container. Otherwise, DIRSYNC will use the state information stored from the first container and this may produce unpredictable results. However, if you request a full update with the /EXPFULL flag, you can use a single DIRSYNC instance to export from multiple containers or multiple directories.


Using Nonmail Databases

While DIRSYNC is primarily used to synchronize an organization's directories, it can also be configured to synchronize the address book changes for a nonmail database. For example, a company could develop a DIRSYNC agent that automatically creates Microsoft Exchange mailboxes for new employees when their records are entered into the Human Resources database.

DIRSYNC is designed to export from or import to a standard file. However, you can change the DIRSYNC source to export to a database or to pass information to a foreign mail system's DLL instead of to a text file. To do this, you must rewrite the DIRSYNC source file functions that open, close, and read from or write to a file. The export functions include HrOpenExport, HrWriteExport, and HrCloseExport. The import functions are HrOpenImport, HrReadImport, and HrCloseImport. These functions are defined in the DSYNCOMM.C source file.

For example, you may be using the functions of a foreign mail system with a DLL that includes functions such as AddUsers or RemoveUsers. To automatically update the foreign system with DIRSYNC calls, you can change the HrWriteExport function to call the AddUsers function and add the specified users to the foreign system at that point, instead of writing the Add User information to a file. Likewise, the HrWriteExport function can call DeleteUsers and delete the specified users from the foreign system instead of writing the information to a file.


Formatting DIRSYNC Import and Export Files

The DIRSYNC sample application writes exported data to files and reads imported data from files. Although DIRSYNC communicates with the directory service using directory access functions, the file format it requires for import operations (and generates during export operations) differs from that used by the directory access functions.

Example: DIRSYNC File Format

The following is a sample of the DIRSYNC file format, which is based on the Microsoft Mail 3.2 IMPORT utility file format:

# Sample DIRSYNC import/export file

A /o=Microsoft/ou=WGA/cn=Recipients/cn=JerryWh
- Display-Name:Jerry Wheeler

M /o=Microsoft/ou=WGA/cn=Recipients/cn=West Coast/cn=KevinY
- Display-Name:Kevin Yim

D /o=Microsoft/ou=WGA/cn=Recipients/cn=KevinY

Each line is prefixed by a character that indicates how the line should be processed.

Prefix | Type | Notes
A | Add | Export: New directory entry. Import: Add new directory entry.
M | Modify | Export: Modified directory entry. Import: Modify directory entry.
D | Delete | Export: Deleted directory entry. Import: Delete directory entry.
- | Attribute | Directory object attribute.
# | Comment | Comment line. The rest of the line after the hash character is ignored.

EXAMPLE: Syntax of Export or Import File

Here is an example of the import/export file syntax used by the DIRSYNC sample application:

data-list :
data-section
data-section data-list

data-section :
add-section
modify-section
delete-section
comment-line

add-section :
add-line attribute-section

modify-section :
modify-line attribute-section

delete-section :
delete-line

attribute-section :
attribute-line
attribute-line attribute-section

add-line :
A space-character RDN EOL

modify-line :
M space-character RDN EOL

delete-line :
D space-character RDN EOL

attribute-line :
- space-character attribute-label : attribute-value (opt)  EOL

comment-line :
# string EOL

EOL :
CR LF

attribute-value :
constant
string
hex-string
quoted-string

quoted-string :
" string "

hex-string :
\x hex-string-data

hex-string-data :
hex-character
hex-character hex-string-data

hex-character : one of
0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f

Important Do not enter spaces between attribute names, the colon delimiter, and attribute values.


DIRSYNC Sample Code

The following source files for the DIRSYNC sample application are included in this SDK:

  • DIRSYNC.C
  • DSYNCOMM.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


DSEXPORT: Exporting Directory Objects

The DSEXPORT sample application demonstrates how to perform a simple directory export operation by calling the BatchExport function. Its source code provides an outline of how to fill the entries in the structure associated with BatchExport, and can be used to demonstrate results of various BatchExport calls.

Both DIRSYNC and DSEXPORT provide source code templates that can be used to develop more complicated export applications, but the two applications use different mechanisms. DIRSYNC can only be used to export mailbox attributes, while DSEXPORT can export any directory object. For more information about BatchExport, see Using Directory Access Functions and BEXPORT_PARMS.

For usage information, type DSEXPORT /? at the command prompt.

To build DSEXPORT
  1. Change to the directory containing the DSEXPORT source files:

    \BKOFFICE\SAMPLES\EXCHANGE\DSEXPORT

  2. Type NMAKE.


DSEXPORT Syntax and Parameters

To run DSEXPORT

Type the following on the command line:

DSEXPORT /FILE=<name of file to export to> [/SERVER=<name of server to restrict objects to be exported>] /DSA=<name of directory service agent> /BASEPOINT=<DN of directory basepoint for export> [/CONTAINER=<name of container to begin extraction>]
[/ONLY_BASEPOINT] [/DELETE] [/ALL_RECIPIENTS] [/DIST_LIST] [/MALBOX] [/REMOTE_ADDRESS] [/CLASSES=<list of object classes separated by the %symbol for export.>] [/ALL_CLASSES] [/HIDDEN] [/SUBTREE][/HELP or /?]

DSEXPORT Parameters

Flag | Settings
/FILE= | Gives name of file to receive exported information.
/SERVER= | Restricts exports to objects on this server.
/DSA= | Gives name of directory service agent (DSA) used to extract directory objects.
/BASEPOINT= | Gives DN of directory basepoint object.
/CONTAINER= | Gives RDN of Directory container beneath BASEPOINT from which to start extraction.
/ONLY_BASEPOINT | Exports only the BASEPOINT itself.
/ALL_RECIPIENTS | Exports all recipients.
/DIST_LIST | Exports distribution list recipients. Default is NO.
/MAILBOX | Exports mailbox recipients. Default is NO.
/REMOTE_ADDRESS | Exports remote address recipients. Default is NO.
/CLASSES | Lists object classes for export, separated by the % symbol. Overrides /DIST_LIST, /MAILBOX, /REMOTE_ADDRESS, ALL_CLASSES.
/ALL_CLASSES | Exports all classes.
/HIDDEN | Exports hidden objects.
/SUBTREE | Recursively collects objects from all containers beneath /BASEPOINT/CONTAINER.
/HELP or /? | Displays full Help information.


Exporting Directory Attributes with DSEXPORT

To export directory attributes with DSEXPORT
  • To export all the recipients from the North America site of the Litware organization, type the following DSEXPORT command line:

    DSEXPORT /FILE=fran1.csv /DSA=BERKELEY /BASEPOINT=/o=Litware/ou="North America" /ALL_RECIPIENTS

  • To export only the distribution lists from the basepoint "o=BLACK11 /ou=Site1", type the following command on one line:

    DSEXPORT /FILE=export.csv /DSA=BERKELEY, /BASEPOINT=/o=BLACK11/ou=Site1 /DIST_LIST

  • To export mailboxes and remote recipients from the basepoint "/o=REDD22 /ou=Site10", type the following command on one line:

    DSEXPORT /FILE=export5.csf /DSA=BERKELEY, /BASEPOINT=/o=REDD22/ou=Site10 /MAILBOX /REMOTE_ADDRESS

  • To export objects of the mailbox and distribution lists class from the basepoint "/o=WHITE1 /ou=Site26" to the EXMAILBOX.CSV export file, type the following command on one line:

    DSEXPORT /file=exmailbox.csv /dsa=BERKELEY /BASEPOINT=/o=WHITE1/ou=Site26/CLASSES=MAILBOX%DL

  • To export hidden mailboxes residing on the server named BERKELEY1, type the following command on one line:

    DSEXPORT /FILE=export.csv /DSA=BERKELEY /SERVER=BERKELEY1 /BASEPOINT=o=m/ou=b /MAILBOX /HIDDEN

Note When exporting a distribution list or a custom recipient, avoid using the /SERVER flag because such objects do not have the Home-Server attribute and cannot be seen if /SERVER is passed.

When you have run DSEXPORT, you will have created an export file that will be stored at the file name indicated. The format of the export file is shown in the following example, which lists exported attributes and information for each recipient.

Obj-Class,First Name,Last name,Display Name,Alias Name,
Directory Name,Primary Windows NT Account,Home-Server,E-mail
address,E-mail Addresses,Members,Obj-Container,Hide from AB
Mailbox,3,,3,3,3,ALLISON'S\3,A-ALLISONP2,,
MS:MICROSOFT/ALLISON2/3%SMTP:3@Allison2.Microsoft.com%X400:
c=US;a= ;p=Microsoft;o=Allison2;s=3;,,Recipients,
Remote,11,,11,11,11,,,SMTP:1@EX.COM,
MS:MICROSOFT/JEFFREY2/11%X400:c=US;a= ;p=Microsoft;o=Jeffrey2;s=11;%SMTP:1@EX.COM
,,Recipients,

In this export operation, fifteen attributes are exported per recipient. In some cases, the attributes contained no values, and are marked by consecutive separators (commas).

All correctly exported files must be in this exact format. For more information about formats, see Formatting DIRSYNC Import and Export Files.

For more information about export and import file formats, see File Formats.


DSEXPORT Sample Code

The following source file for the DSEXPORT sample application is included in this SDK:

  • DSEXPORT.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


DSIMPORT: Importing Directory Objects

The DSIMPORT sample application demonstrates how to perform a directory import operation by calling the BatchImport function. It provides a simple skeleton that demonstrates how to fill the entries in the structure associated with BatchImport. It also demonstrates the results of BatchImport calls.

Both DIRSYNC and DSIMPORT provide source-code examples that can be used to develop more complex import applications, but the mechanism used for the import is not the same. Furthermore, DIRSYNC can only be used to import mailbox and custom recipient attributes, while DSIMPORT can import any directory object. For more information about BatchImport, see Using Directory Access Functions, Importing Data into Microsoft Exchange Server, and BIMPORT_PARMS.

For usage information, type DSIMPORT /? at the command prompt.

To build DSIMPORT
  1. Change to the directory containing the DSIMPORT source files: \BKOFFICE\SAMPLES\EXCHANGE\DSIMPORT
  2. Type NMAKE.


DSIMPORT Syntax and Parameters

To run DSIMPORT

Type the following on the command line:

DSIMPORT /FILE=<name of file to import from> /DSA=<name of directory service agent> /BASEPOINT=<DN of directory basepoint for import> [/CONTAINER=<name of container to import from>] [/HELP or /?]

DSIMPORT Parameters

Flag | Settings
/FILE= | Gives name of import file to receive information.
/DSA= | Gives name of directory service agent (DSA) used to import directory objects.
/BASEPOINT= | Gives DN of directory basepoint object.
/CONTAINER= | Gives RDN of Directory container beneath BASEPOINT to which to import.
/HELP or /? | Displays full Help information.


Importing Directory Attributes with DSIMPORT

To import directory attributes with DSIMPORT
  1. Prepare the import file or determine the name of the import file and make sure it is in valid format. For example:
    Obj-Class,Common-Name,Mail-Nickname,Obj-Container,Home-Server,
Delivery-Mechanism,Members,Assoc-NT-Account,Obj-Admins,Obj-Users,
Display-Name,Given-Name,Surname,Target-Address,Hide-From-AB
Mailbox,joeh,joeh,Recipients,BERKELEY,0,Corporate,,,REDMOND\
a-teresa%REDMOND\willh,Joe Howard,Joe,Howard,,0
Mailbox,annd,annd,Recipients,BERKELEY,0,,,,REDMOND\
Klein,Alison Anderson,Amy,Devon,,0
Mailbox,chrisb,chrisb,Recipients,BERKELEY,0,,,,,
Chris Bauknecht,Chris,Bauknecht,,0
Mailbox,kimh,kimh,Recipients,BERKELEY,0,,,,REDMOND\v-kimh,
Kim Hightower,Kim,Hightower,,0
  2. Type the DSIMPORT command line:

    DSIMPORT /DSA=BERKELEY /BASEPOINT=/o=Litware/ou="North America" /CONTAINER=Recipients /FILE=fromHR.csv

    This command imports entries listed in the FROMHR.CSV sample file into the BERKELEY server's directory. The import operation points to the basepoint (which is in the Litware organization and on the North America site) and adds the new mailboxes to the Recipients container under this basepoint. The quotation marks around the site name are necessary because the site name contains a space.


DSIMPORT Sample Code

The following source file for the DSIMPORT sample application is included in this SDK:

  • DSIMPORT.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


EXTDATVW: Viewing and Editing Extension Data

The EXTDATVW sample application creates an Administrator program extension that allows you to view and edit the values of an Extension-Data attribute of a Microsoft Exchange Server directory object. EXTDATVW is implemented as an Administrator extension DLL (EXTDATVW.DLL).

To use EXTDATVW, the Administrator extension DLL must be installed and EXTDATVW must be attached to the directory object. This adds the Ext Data Viewer property page to the object's property sheet. For more information about installing extension DLLs, see Installing the Administrator Extension DLL. For general information about Administrator extensions, see Administrator Program Extensions.

To build EXTDATVW
  1. Change to the directory containing the EXTDATVW source files:

    \BKOFFICE\SAMPLES\EXCHANGE\EXTDATVW

  2. Type NMAKE.

To install the Administrator extension DLL, use the EXTNINST sample application.


Installing EXTDATVW with EXTNINST

Use the EXTNINST installation utility to install the EXTDATVW sample application.

To run EXTNINST

Type the following on the command line:

EXTNINST /SITEDN=<distinguished name>
/DISPLAY_NAME=<display name> /MACHINE=<machine name>
/NAME=<admin extension name> /SERVER=<server computer>
/EXTDLL=<DLL name>[/DELETE] [/HELP or /?]

EXTNINST Parameters

Flag | Settings
/SITEDN= | Gives the site distinguished name (DN). For example: /SITEDN=/O=Microsoft/OU=Northwest
/DISPLAY_NAME= | Gives the display name for the Administrator extension DLL. This name will be displayed in the Administrator program under Configuration\Add-ins. For example: /DISPLAY_NAME="Extension Data Viewer"
/MACHINE= | Gives the computer type for the Administrator extension DLL. For example: /MACHINE=i386
/NAME= | Gives the name of the Administrator extension DLL. This name will be used by objects that wish to use this extension. It becomes part of the Common Name attribute for the extension and part of the full pathname for the extension. For example: /NAME=EXTDATVW
/EXTDLL= | Gives the full pathname of the Administrator extension DLL. For example, to use the compiled version of the EXTDATVW.DLL library: /EXTDLL=C:\EXCHSDK\BIN\EXTDATVW.DLL
/SERVER= | Gives the name of the server for this extension DLL. For example: /SERVER=EDKDOCS20
/DELETE | Deletes the named extension.
/HELP or /? | Displays full Help information.


Viewing and Changing Properties with EXTDATVW

To install EXTDATVW using EXTNINST

The following is a valid command line:

EXTNINST /SITEDN=/o="Ferguson & Bardell"/ou=NAmerica-N
/DISPLAY_NAME="Extension Data Viewer" /MACHINE=i386
/NAME=EXTDATVW /EXTDLL=C:\BKOFFICE\BIN\EXTDATVW.DLL
/SERVER=SANFRANCISCO01

To attach EXTDATVW to a directory object
  1. Copy the Administrator extension DLL (EXTDATVW.DLL) to the appropriate ADD-INS directory on the Microsoft Exchange Server computer. Each server has a top-level shared directory called \\<server name>\ADD_INS. The directory path is composed of the path to the ADD-INS directory, a directory called EXTDATVW, and a directory whose name matches the computer type. For example, type the following to copy the already compiled version of the DLL:

    CD C:\EXCHSRVR\ADD-INS

    MD EXTDATVW

    CD EXTDATVW

    MD I386

    CD I386

    COPY \BKOFFICE\BIN\EXTDATVW.DLL

    To copy the version you built in DEBUG mode, change the last statement to:

    COPY \BKOFFICE\SAMPLES\EXCHANGE\EXTDATVW\WIN32\DEBUG\EXTDATVW.DLL

  2. Start the Administrator program using the /RAW switch.
  3. Select the directory object whose extension data you want to view.
  4. Choose the Raw Properties option from the File menu.
  5. Select All in the List Attributes of Type box.
  6. In the Object Attributes box, click the Extension-Name property and then, in the text box labeled Edit Value, type ExtDatVw.
  7. Click Add and then click OK.

Once EXTDATVW is installed, you can view the new property page (called Ext Data Viewer) for the directory object.

To run EXTDATVW
  1. Double-click the directory object whose extension data you want to view or edit.
  2. Click the tab for the Ext Data Viewer property page. You will see a page with all attributes blank.
  3. Type the owner tag of the value you want to examine in the Extension-Data attribute. The Extension-Data attribute is a multivalued property composed of owner tags and extension data. Extension data consists of properties for the object. It may have a single or multiple value. Owner tags are case-sensitive. For example, distinct values called SGWData and SGWdata can coexist in the same Extension-Data attribute.

    If you do not know the owner tag of the extension data you want to examine, you can edit the Extension-Data attribute for the object to locate this information.

For more information on owner tags and the structure of the Extension-Data attribute, see Using the Extension-Data Attribute.

To edit the Extension-Data attribute
  1. In the Administrator program with the /RAW flag set, select the directory object whose extension data you want to view.
  2. Under the File menu, select Raw Properties.
  3. Select Extension-Data and click Editor.
  4. Select Text from the Value list. You should see the owner tag for the first value of the extension data in the box.

Important If you receive an error message indicating embedded NULL characters in the text, this indicates that the value is a Unicode string. In such a case, you must remove the padding zeroes before you will see the text value. If you remove any zeroes, it is important not to save the altered information.


Viewing Extension Data with EXTDATVW

The Ext Data Viewer property page for the GWSAMPL object is shown in the following figure.

The Ext Data Viewer property page for the GWSAMPL application


Editing Extension Data with EXTDATVW

The following options are available on the Ext Dat Viewer property page.

Extension Data Text Box

Displays the data types and values of the data fields within the currently open value in the multivalued Extension-Data property, which are displayed in the text box.

Refresh Button

Displays the saved values of the fields shown in the Extension Data text box. EXTDATVW will display a dialog box asking whether to save changes first if the values displayed have not yet been saved. To save changes, click Yes, then click Apply.

Add Button

Adds new fields to the value displayed in the Extension Data text box. Select a data field in the Extension Data text box, then click Add. This adds a new data field in the position immediately before the selected field. Click Apply to save the new value.

Modify Button

Modifies a data field. Click the Modify button to edit the value of that data field. This option displays the Edit Value dialog box. Type the new value for the data field in the dialog box. After changing the value, click Apply to save changes.

Delete Button

Deletes a data field. First select the data field, then click the Delete button. Click Apply to execute the delete operation.


EXTDATVW Sample Code

The following source files for the EXTDATVW sample application are included in this documentation:

  • ADMIN.C
  • EXTDATVW.C
  • EDITDLG.C
  • PRVALARY.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


FIMPORT: Importing Folder Information

The FIMPORT sample application demonstrates how to import information into one or more Microsoft Exchange Server folders using bulk import methods. It can be used to:

  • Import bulk data into one or more folders on Microsoft Exchange Server.
  • Create folder content for testing and general use.
  • Provide a framework for building other folder import tools.
  • Demonstrate how to create and use of named properties on messages.
  • Demonstrate how to use the MS_EXCHANGE_01 property on messages. For more information, see Using the MS_EXCHANGE_01 Property.

FIMPORT creates folder content from an external .CSV file that contains a column for each property to be set on the messages in the folder. Each line in the file corresponds to a message to be changed. The file can be used to append, replace, or update the contents of the folder. FIMPORT opens the destination folder in the information store and updates each message. A progress display is updated after each item.

Two sample input files are included with the FIMPORT sample application. The FIMPORT1.CSV file shows how FIMPORT can be used to update any kind of information in a public folder, in this case the price and availability of auto parts. The FIMPORT2.CSV file shows how FIMPORT can be used to update messages in a public or private folder.

To build FIMPORT
  1. Change to the directory containing the FIMPORT source files:

    \BKOFFICE\SAMPLES\EXCHANGE\FIMPORT

  2. Type NMAKE.


FIMPORT Syntax and Parameters

To run FIMPORT

Type the following on the command line:

FIMPORT /FILE= <filename of .CSV file> /APPEND | /UPDATE | /REPLACE [/FOLDERPATH=<complete path of folder>] /CLASS=<message class> /PROFILE=<profile for store logon> [/[NO]SETREAD] [/[NO]EFD] [/[NO]PROGRESS] [/HELP or /?]

FIMPORT Parameters

Flag | Settings
/FILE= | Specifies file name of the .CSV file to import.
/APPEND | Default. Appends the content of the .CSV file to the folder. Cannot be used with /UPDATE or /REPLACE.
/UPDATE | Replaces the associated properties in the messages from the folder with the properties from the columns in the .CSV file. The replacement is carried out starting with the first message in the folder.
/REPLACE | Replaces the existing messages in the folder with the contents of the .CSV file.
/FOLDERPATH= | Specifies the path of the folder where messages will be placed. If this property is not set then the folder path must be specified in the first line of the file.
CLASS= | Specifies the message class of messages to be placed in the folder.
/PROFILE= | Specifies the profile to be used for the logon to the information store.
/[NO]SETREAD | Sets the read flag on each new message. /NOSETREAD causes the message to appear as unread.
/[NO]EFD | Creates the MS_EXCHANGE_01 property and sets it to TRUE on each new message. /NOEFD does not create the MS_EXCHANGE_01 property.
/[NO]PROGRESS | Displays a progress dialog box. /NOPROGRESS causes this dialog not to be displayed.
/HELP or /? | Displays full Help information.


Importing Folder Messages with FIMPORT

To import folder messages
  1. Create several folders or choose several existing folders.
  2. Create a .CSV file that changes the information in the selected folders, or use the FIMPORT1.CSV or FIMPORT2.CSV sample files.
  3. Type a command similar to the following:

    FIMPORT /FILE=FIMPORT2.CSV /APPEND /FOLDERPATH="Personal Store - 12-9.pst\Joe's Market App" /CLASS=IPM.NOTE /SETREAD /EFD

    This command causes the information from the FIMPORT2.CSV file to be appended to the existing messages.

    The /FOLDERPATH and /CLASS parameters are entered both on the command line and in the first line of the FIMPORT2.CSV file. In cases like this, the command-line information overrides the information in the file.

  4. To verify that the messages have been placed in the folders, edit the folders in the specified path to verify that the message has been appended.


Using the .CSV File

FIMPORT logs on to MAPI using the profile specified in the command line. It opens the .CSV formatted text file specified in the command line, parses the first line of the .CSV file for additional parameters, and parses the second line of the file for column headings.

FIMPORT determines from a table of MAPI and Microsoft Exchange Server message properties whether each column in the .CSV file refers to a standard message property or to a named property. For named properties, the property type is governed by a prefix on the column header, and defaults to TEXT. Then FIMPORT appends, updates or replaces the information in each message with the information from the file.

The text of the FIMPORT2.CSV file that serves as input to FIMPORT is as follows:

Command, Folderpath=@DEFAULT\@PR_IPM_INBOX_ENTRYID, Class=IPM.Note
pr_subject, pr_body, attach, s:Message Number In French
Message Number One,Here is the first message.,fimport2.txt,Un
Message Number Two,Here is the second message.,fimport2.txt,Deux
Message Number Three,Here is the third message.,fimport2.txt,Trois

CSV File Format

The first line of the .CSV file is an optional command line that is interpreted along with the typed command line. The second line of the .CSV file, which is required, is a definition of the columns with each column representing a property that will be replaced in each message of the destination folder. The remainder of the file consists of the values for each column. The format is as follows:

<File> == [<Firstline>] <Secondline> <CSVBody> EOF

<Firstline> == ["COMMAND,"]

[<Operation> ","]

[FOLDERPATH=<Folder path> ","]

[CLASS=<MessageClass> ","]

[SETREAD ","]

[EFD]

EOL

<Secondline> == <ColumnList> EOL

<CSVBody> == <Thirdline> [<CSVBody>]

<Thirdline> == <PropValueList> EOL

<ColumnList> == <Column> "," [<ColumnList>]

<PropValueList> == <PropValue> "," [<PropValue>]

<Column> == [<TypePrefix>] <PropName>

<PropName> == any valid property tag string - for standard properties they would typically be prefixed with PR

TypePrefix == L: | S: | T: | U:

Notes

The same number of terms should appear in <Secondline> as in <Thirdline>

Type prefixes

L - PT-LONG

S - PT-STRING

T - PT-SYSTIME

U - PT-UNICODE

B - PT-BOOLEAN

Default is PT-STRING

In the FIMPORT2.CSV sample file shown above, the first line of the file uses special characters signified by the @sign. These special characters cause the process to read the corresponding properties from the environment. The @DEFAULT entry causes the name of the default message store to be used. @IPM_* is a special equate that is passed in to HrMAPIFindFolderEx() which returns the designated property value. These characters can be used on the command line or in the first line of the file.

The ATTACH keyword, which is located in the second (column definitions) line of FIMPORT2.CSV as shown above, is a special value that can be used in place of a property name. It indicates that this column contains a list of files that will be attached to the message rather than a normal property value.


FIMPORT Sample Code

The following source file for the FIMPORT sample application is included in this documentation:

  • FIMPORT.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


INSTFORM: Installing a Sample Form

The INSTFORM sample application is a utility that demonstrates how to install or remove a Microsoft Exchange Server form. For more information about forms design, see the Microsoft Exchange Server Application Designer's Guide.

To build INSTFORM
  1. Change to the directory containing the INSTFORM source files:

    \BKOFFICE\SAMPLES\EXCHANGE\INSTFORM

  2. Type NMAKE.


INSTFORM Syntax and Parameters

To run INSTFORM

Type the following on the command line:

INSTFORM /INSTALL <cfgfile> [/REGISTRY=<valid registry> || /FOLDER=<valid folder path> /MSGSTORE=<message store containing this folder>] [/PROFILE=<valid profile for logon to registry> /PASSWORD=<password for specified profile>][/HELP or /?]

– Or –

INSTFORM /REMOVE <msgclass> [/REGISTRY=<valid registry> || /FOLDER=<valid folder path> /MSGSTORE=<message store containing this folder>] [/PROFILE=<valid profile for logon to registry> /PASSWORD=<password for specified profile>][/HELP or /?]

INSTFORM Parameters

Flag | Settings
<cfgfile> | Specifies file containing information about the form to be installed. Install only.
<msgclass> | Specifies message class of the form to be removed from the Windows NT Registry. Remove only.
/INSTALL | Specifies install action that installs the specified form in the indicated registry.
/REMOVE | Specifies remove action that removes the form with the specified message class from the indicated registry.
/REGISTRY= | Specifies which registry to install the form in. Possible values are PERSONAL, LOCAL, FOLDER, and ENTERPRISE. /REGISTRY=PERSONAL requires /PROFILE /REGISTRY=LOCAL does not require /PROFILE. /REGISTRY=FOLDER requires /FOLDER and /PROFILE. This registry is implied if /FOLDER is used. /REGISTRY=ENTERPRISE requires /PROFILE.
/FOLDER= | Gives folder path of the registry in which to install the form or from which to delete the form. This flag is required when /REGISTRY = FOLDER. If /FOLDER is used, /REGISTRY need not be stated and will be assumed to be /FOLDER.
/PROFILE= | Specifies profile for logging on to the registry. Required (except for local registry).
/PASSWORD= | Specifies password of the profile specified by the /PROFILE flag. Not required.
/MSGSTORE= | Specifies display name of the information store that contains the folder specified. This flag is only valid with folders. If not specified, the default information store will be used.
/HELP or /? | Displays Help information.


Installing the CHKRFORM Sample Form

The Microsoft Exchange Server SDK provides the WCHECK.EXE sample form that you can install using the INSTFORM sample application. It allows two people to play a game of checkers.

To install a form in a forms library, you must prepare a .CFG file that describes the form. The CHKRFORM.CFG is included in this SDK. For more information, see The CHKRFORM.CFG File.

To install the sample form in the personal forms library
  1. Change to the following directory:

    \BKOFFICE\SAMPLES\SAMPLES\EXCHANGE\INSTFORM

  2. Type the following command on one line:

    INSTFORM /INSTALL CHKRFORM.CFG. /REGISTRY=PERSON /PROFILE=<name of profile used to set up form>

  3. If the information displayed in the dialog box is correct, choose OK. The Installing Form message box appears.
  4. If installation succeeds, the following message appears:
    Form installed successfully.

To view the installed form
  1. Activate the Microsoft Exchange Client.
  2. Select Forms Manager from the Tools menu. The new form should be visible in the Personal Forms list box.

To install the sample form in a folder
  1. Change to the following directory:

    \BKOFFICE\SAMPLES\EXCHANGE\INSTFORM

  2. Type the following command on one line:

    INSTFORM /INSTALL CHKRFORM.CFG /FOLDER="TOP OF INFORMATION STORE\INBOX" /PROFILE=<name of profile used to set up form>

  3. If the information displayed in the dialog box is correct, choose OK. The Installing Form message box appears.
  4. If installation succeeds, the following message appears:
    Form installed successfully.

To verify installation in a folder
  1. Activate the Microsoft Exchange Client.
  2. Select the folder into which the form was installed.
  3. From the menu bar, select Compose. A new entry for CHEKRFORM should appear at the end of the list.

To install the sample form in the local forms library
  1. Change to the following directory:

    \BKOFFICE\SAMPLES\EXCHANGE\INSTFORM

  2. Type the following command on one line:

    INSTFORM /INSTALL CHKRFORM.CFG /REGISTRY=LOCAL

  3. If the information displayed in the dialog box is correct, choose OK. The Installing Form message box appears.
  4. If installation succeeds, the following message appears:
    Form installed successfully.

To verify installation in the local forms library
  1. Activate the Microsoft Exchange Client.
  2. Select Compose, then New Form. The CHEKRFORM form should be listed in the menu.

To install the sample form into the organization forms library
  1. Start the Microsoft Exchange Server Administrator program.
  2. From the Tools menu, choose Forms Administrator.
  3. Choose New from the Organization Forms Library dialog box.
  4. Click OK for Organization Forms Library Administrator in the Library folder name text box.
  5. The Organization Forms Library Administrator dialog box is displayed again. Make sure Organization Forms Registry is highlighted. Click Permissions.
  6. The Forms Library Permissions dialog box is displayed. Click Add.
  7. Add a user to the permissions list for installing forms. The Add Users dialog box is displayed. Click the name of a user you want to add from the left list box. Click OK.
  8. In the Forms Registry Permissions dialog box, the newly added user appears in the top list box, with the default role of Reviewer displayed. Click the Roles combination box and assign the Owner to the user. This gives that person the ability to add new forms into the organization form Registry. Click OK.
  9. Close the Organization Forms Library Administrator dialog box.
  10. At a command prompt, type:

    INSTFORM /INSTALL CHKRFORM.CFG
    /REGISTRY=ENTERPRISE /PROFILE=<user profile name>

    In this command, <user name> is the name of the user to whom you have just given Owner permission.

To verify installation in the Organization Forms Library
  1. Start the Microsoft Exchange Client.
  2. From the Tools menu, choose Options. Select the Microsoft Exchange Server property page.
  3. Click Manage Forms. The Forms Manager dialog box is displayed with additional controls. Select the library you want to view by clicking the Set button opposite that entry.
  4. In the list box on the left, double-click Games, then double-click Board Games. If the sample form was installed properly, you will now see Checkers Sample Form. Click the name of the form to view its properties.

    – Or –

    Another way to confirm successful installation: within the client interface, from the Compose dialog box, select New Form. The Chekrform form should appear under Organization.


The CHKRFORM.CFG File

[Description]
MessageClass=IPM.Checkers
CLSID={86174010-5030-0076-9912-00aa0038901b}
Category=Games
Subcategory=Board Games
DisplayName=Checkers Sample Form
Comment=Sample Checkers Form
LargeIcon=wcheck.ico
SmallIcon=wchecks.ico
Version=1.0
Locale=enu
Hidden=0
Owner=Exchange Server SDK
ComposeCommand=New Checkers Game ...

[Platforms]
Platform.2=NTx86

[Platform.NTx86]
CPU=ix86
OSVersion=WinNT3.5
file1=wcheck32.exe
registry1=LocalServer32 = %d\wcheck32.exe /f
registry4=InProcHandler32 = ole32.dll

[Properties]
Property1=BoardData
Property2=Turn
Property3=MoveNumber
Property4=BoardScore

[Property.BoardData]
Type=258
NmidInteger=26624
DisplayName=Board Data
SpecialType=0

[Property.Turn]
Type=3
NmidInteger=26625
DisplayName=Turn
SpecialType=0

[Property.MoveNumber]
Type=3
NmidInteger=26626
DisplayName=Move Number
SpecialType=0

[Property.BoardScore]
Type=3
NmidInteger=26627
DisplayName=Scoring Function Output
SpecialType=0

[Extensions]
WMS_Extension=WMS_Extension

[Extension.WMS_Extension]
Type=30
NmidPropset={00020D35-0000-0000-C000-000000000046}
NmidInteger=1
Value=11222000
;
; ----- position
; 0
; 1 read
; 2 reply
; 3 reply all
; 4 forward
; 5 print
; 6 save
; 7 on delivery
; ----- meaning
; 0==default
; 1==DoVerb
; 2==Disabled

[Verbs]
Verb1=1

[Verb.1]
DisplayName=checkers
Code=0
Flags=0
Attribs=0


INSTFORM Sample Code

The following source files for the INSTFORM sample application are included in this documentation:

  • CHKRFORM.CFG
  • INSTFORM.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


MBINST: Installing a Mailbox Agent

The MBINST sample application demonstrates how to install a Mailbox-Agent object in the Microsoft Exchange Server directory. To use it, Microsoft Exchange Server and the Microsoft Exchange Server SDK must both be active on the target computer. MBINST can be used to install the mailbox agent (MBA) created by the SMBAGENT sample application.

To build MBINST
  1. Change to the directory containing the MBINST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU

  2. Type NMAKE.


MBINST Syntax and Parameters

To run MBINST

Type the following on the command line:

MBINST /SITEDN=/o=<organization> /ou=<site> /DISPLAY_NAME=<display name for MBAGENT> /RELATIVE_DN=<DN relative to site information> /SERVER=<server name> /EXTNAME=<extension dll name> [/EXTDATA=<absolute path and file name of extension data>] [/ACCOUNT=<account name>] [/DELETE] [/HELP or /?]

MBINST Parameters

Flag | Settings
/SITEDN= | Specifies the mailbox agent site distinguished name (DN). This name has two parts: /o=<organization> and /ou=<site>. For example: /SITEDN=/o=Microsoft/ou=edkue.
/DISPLAY_NAME= | Specifies the mailbox agent display name. This name is displayed in the directory.
/RELATIVE_DN= | Specifies the mailbox agent relative distinguished name (RDN), which includes all elements of the DN except the organization and the site. You should place the mailbox agent in the Recipients container. It must have its own container below the Recipients container. For example: /RELATIVE_DN=/cn=Recipients/cn=SampleMBA Placing the mailbox agent in any container other than Recipients may produce unexpected results.
/SERVER= | Specifies the server computer name.
/EXTNAME= | Specifies the extension name. This property allows the extension to be used by directory objects by placing the /EXTNAME in their Extension-Name attribute.
/EXTDATA= | Gives the full path of extension data. For example: /EXTDATA=C:\BKOFFICE\BIN\SMBADMIN.DAT. The extension data is produced by running the Administrator extension. This parameter can be used to run the extension as a separate step, or to gather extension data from another source and link the resulting .DAT file.
/ACCOUNT= | Specifies the account name.
/DELETE | Deletes a mailbox agent.
/HELP or /? | Displays Help information.


Installing a Mailbox Agent with MBINST

To install a mailbox agent with MBINST
  1. To install the SampleMBA mailbox agent at the Microsoft Northwest site with the server EDKDOCS20, type the following at a command prompt:

    MBINST /SITEDN=/O=MICROSOFT /OU=NORTHWEST /DISPLAY_NAME=SMBAGENT /RELATIVE_DN=/CN=RECIPIENTS /CN=SAMPLEMBA /SERVER=EDKDOCS20
    /EXTNAME=SAMPLEMBA

  2. Use the SERVINST sample application to register the service so it can be managed through the Services dialog box of the Control Panel. See SERVINST: Installing a Service.
  3. Use the PROFINST sample application to install a profile that allows you to log on as the service and view the messages in the mailbox. See PROFINST: Installing a MAPI Profile.
  4. If the mailbox agent is to use an Administrator extension DLL, create a new directory and copy the DLL into the directory. Then use the EXTNINST sample application to install the DLL. See EXTNINST: Installing an Administrator Extension.
  5. To verify that you have correctly installed the mailbox agent, look at the Recipients container in the Administrator program. It should contain an entry for the mailbox agent.

This procedure creates a Mailbox-Agent object in the directory, and optionally assigns an Administrator extension DLL to it. A mailbox is created for the mailbox agent when a profile is created for it and it logs on for the first time.


MBINST Sample Code

The following source file for the MBINST sample application is included in this documentation:

  • MBINST.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


MBLSAMPL: Accessing Mailboxes

The MBLSAMPL sample application demonstrates how to create and use a mailbox logon that allows privileged access to mailboxes. It also demonstrates how the IExchangeManageStore interface allows privileged access to mailboxes and remote manipulation of objects in mailboxes where administrator privileges have been granted. Privileged access means an application can use MAPI calls to perform actions such as read, write, and move, on individual or multiple mailboxes in the information store.

MBLSAMPL also demonstrates the use of the MBLOGON.LIB library functions. MBLSAMPL passes the distinguished name (DN) of the user profile with administrator privileges and the DN of the server, and is returned a pointer into the information store. For more information, see Privileged Access to Mailboxes.

To build MBLSAMPL.EXE and MBLOGON.LIB
  1. Change to the directory containing the MBLSAMPL source files:

    \BKOFFICE\SAMPLES\EXCHANGE\MBLSAMPL

  2. Type NMAKE.

To run MBLSAMPL, you must use a profile that has administrator privileges on Microsoft Exchange Server. You can use an existing profile or create a new profile for this application.

For more information about using MAPI functions to create profiles or to manipulate objects in mailboxes, see the MAPI Programmer's Reference.


MBLSAMPL Syntax and Parameters

To run MBLSAMPL

Type the following on the command line:

MBLSAMPL <profile name> [<password>] [/HELP or /?]

MBLSAMPL Parameters

Flag | Settings
Profile | Specifies the MAPI profile name associated with this logon.
Password | Specifies the password for this profile, if one exists.
/HELP or /? | Displays Help information.


Viewing the Contents of Mailboxes with MBLSAMPL

To view the contents of mailboxes using MBLSAMPL
  1. Type MBLSAMPL and the MAPI profile name for a user profile with administrator privileges. If the profile name contains a space, enclose the entire profile name in quotation marks. Because MAPI profile passwords are not used on Windows NT Server, omit the PASSWORD parameter:

    MBLSAMPL <Admin>

    If this logon attempt succeeds, MBLSAMPL prompts you for the name of the server on which you want to perform MAPI operations:

    Enter the name of the SERVER that contains the mail box
or EXIT to terminate.

    Example: /O=Microsoft/OU=Test/CN=Servers/CN=ServerName

  2. Type the path leading to your server. For example:

    /O=Litware/OU="North America"/CN=Servers/cn=BERKELEY

    In the preceding syntax, the container designation /CN=Servers does not change and must be typed verbatim. The other parameters must match the actual names of nodes on the server's directory information tree (DIT).

  3. MBLSAMPL now prompts you for the name of the mailbox whose contents you want to view.
    Enter the name of the mail box to access
or EXIT to terminate

    Example: /O=Organization/OU=Site/CN=Container/CN=MailboxName

  4. Type the path leading to a mailbox containing messages you want to view. For example:

    /O=Litware/OU="North America"/CN=Recipients/cn=container1

    MBLSAMPL lists the subject lines of the messages in the mailbox. It then prompts you for the name of a server, which returns you to Step 2.

Note The MailboxName parameter refers to the distinguished name (DN) of the mailbox, which is unique and is generated at the time the mailbox is created. This name may or may not be the same as the mailbox's display name. To verify the DN for a mailbox from the Administrator program, view the raw property Obj-Dist-Name.

MBLSAMPL can be configured to take advantage of additional MAPI functionality. For example, it can access message properties such as the Subject, Body, To, CC, and Recipient fields. Using MBLSAMPL, you can log on to anyone else's mailbox within that information store or in any other server's information store for which you also have administrator privileges.

Note Do not attempt to log on to your own mailbox or any mailbox attached to the profile that executes MBLSAMPL. This can cause unpredictable results, including loss of information because there will be a conflict between the profiles. See Flag Settings for Privileged Access.

For MBLSAMPL, the only special permissions needed for administrator rights are Logon Rights for all mailboxes in the site. Add a Windows NT account with a View Only Admin role in the Administrator program for the site. No specific Windows NT Server rights are required.


MBLOGON.LIB Functions

The MBLOGON.LIB library contains the following functions:

Function | Purpose
HrMailboxLogon | Logon to a mailbox.
HrMailboxLogoff | Logoff a mailbox.


MBLSAMPL Sample Code

The following source files for the MBLSAMPL sample application are included in this documentation:

  • MBLSAMPL.C
  • MBLOGON.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


MBXSERV: Viewing Messages in a Mailbox

The MBXSERV sample application demonstrates how to create a property page attached to mailboxes that allows you to view the titles of all the messages in the mailbox, using a password for security. It can be used as an example of one component in a voice mail server application. For more information on this topic, see How a Voice Mail Server Works.

MBXADMIN.DLL is an Administrator program extension that adds a property page to a mailbox's property sheet. To use it, the Administrator extension DLL must be installed with EXTNINST: Installing an Administrator Extension installation program. After installation, MBXADMIN must be attached to the mailboxes, which adds the MBX Sample property page to the property sheets of all the mailboxes. To view the titles of all the messages in the mailbox, a user must run the MBXSERV application and access the mailbox by typing a password. For more information about installing the extension DLL, see Installing the Administrator Extension DLL. For general information about Administrator extensions, see Administrator Program Extensions.

To build MBXSERV
  1. Change to the directory containing the MBXSERV source files:

    \BKOFFICE\SAMPLES\EXCHANGE\MBXSERV

  2. Compile MBXSERV by typing NMAKE.
  3. Change to the directory containing the MBXADMIN.DLL Administrator extension DLL source files:

    \BKOFFICE\SAMPLES\EXCHANGE\MBXADMIN

  4. Compile MBXADMIN.DLL by typing NMAKE.

    Install the Administrator extension DLL by using the compiled EXTNINST sample application found in the \EXCHSDK\BIN directory.

To install MBXAdmin using EXTNINST
  1. Copy the Administrator extension DLL (MBXADMIN.DLL) to the appropriate ADD-INS directory on the Microsoft Exchange Server computer. Each server has a top-level shared directory called \\<server name>\ADD_INS. The directory path is composed of the path to the ADD-INS directory, a directory called MBX, and a directory whose name matches the computer type. For example:

    CD C:\EXCHSRVR\ADD-INS

    MD MBX

    CD MBX

    MD I386

    CD I386

    COPY C:\BKOFFICE\SAMPLES\EXCHANGE\MBXADMIN\WIN32\<build type>\MBXAdmin.DLL

  2. To use EXTNINST to install the mailbox, type a command similar to the following:

    EXTNINST /SITEDN=/O=MICROSOFT/OU=EDKUE DISPLAY_NAME=MBX /MACHINE=I386 /NAME=MBX /EXTDLL=C:\EXCHSRVR\ADD-INS\MBX\I386\MBXADMIN.DLL /SERVER=EDKDOCS20

    You should receive the message:

    Admin Extension installed successfully
  3. Verify that the Administrator extension has been installed by checking the Add-Ins container within the Configuration container in the Administrator program. You should see an icon for the Administrator extension DLL.
  4. Start the Administrator program using the /RAW switch.
  5. Select the Recipients directory object in the left pane, and then choose the Raw Properties option from the File menu.
  6. Check All in the List Attributes of Type box.
  7. In the Object Attributes list box, click the Extension-Name-Inherited property.
  8. In the Edit Value text box, type your object's name with the /NAME parameter. For example: MBX
  9. Click Add and then click OK.

    Once MBXAdmin is installed, you can view the new property page called MBX Sample on any mailbox property sheet. You must enter and then use a password to view the messages from any mailbox.

  10. Enable a password. To do this, double-click on the mailbox containing the messages you want to view. Select the MBX Sample property page. Type the password in the Password and Verify Password fields. This password need not be the same as the account password.


Viewing Messages in Mailboxes with MBXSERV

You can view the messages in any mailbox on the server with MBXSERV.

To run MBXSERV
  1. Type MBXSERV at the command prompt. The Choose Profile box appears.

  2. Pull down the Profile Name combo box and choose the profile for the mailbox you want to examine. The Vox Server Sample App dialog box appears. Enter your alias and your MBX password. Click the Get Mail button.

  3. If everything is valid, the subject lines appear for the messages that are currently in your Inbox. Any unread message in the Inbox will be displayed in bold. The MBXSERV sample application cannot read the messages.
  4. Add or delete some messages in the Inbox. Click Get Mail again. The list of messages should be updated.


MBXSERV Sample Code

The following source files for the MBLSAMPL sample application are included in this documentation:

  • MBLSAMPL.C
  • MBLOGON.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


POPPST: Creating a Customized Information Store

The POPPST sample application demonstrates how to create a new personal folder store (PST) and populate it with one or more test messages (optional). When POPPST creates a new PST, it does so by using a temporary profile that it deletes after PST creation. To create messages in this PST, you must provide an existing profile name for the PST (see examples that follow). For more information about adding information stores, see Opening an Information Store.

POPPST is a command-line program that uses input from an .INI file. POPPST requires one command-line argument, which is the name of the .INI file. For a description of the required format of the .INI file used with POPPST, see POPPST .INI File Format. For general information about .INI and other file formats, see File Formats.

The POPPST application also demonstrates functions of the NEWPST library.

To build POPPST
  1. Change to the directory containing the POPPST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\POPPST

  2. Type NMAKE.


POPPST Syntax and Parameters

To run POPPST

Type the following on the command line, replacing with your information.

POPPST IniFileName [/HELP or /?]

POPPST Parameters

Flag | Settings
inifilename | Specifies the full path name of the message file (.INI file).
/HELP or /? | Displays Help information.


Populating a Personal Folder Information Store

To populate a personal folder information store using POPPST
  1. Create or modify a POPPST.INI file for the PST you want to create or populate, or use the POPPST.INI file provided with the sample application. For information, see Formatting the POPPST.INI File.
  2. Type POPPST POPPST.INI. You will receive the following progress message:
    Processing <poppst.ini>. Please wait.

    If you supply the name of a recognizable .INI file and the command succeeds, POPPST displays the following success message:

    PST populated successfully.

    Providing the name of a bad .INI file produces the following message:

    ERROR: .INI file bad..INI could not be opened.

    Running POPPST without POPPST.INI (ie. running from \BIN or \WIN32\DEBUG) produces the following error message:

    ERROR: 1 error written to the event log
(Event Error states: Can't open file poppst..INI)

    An incorrect number of parameters produces this error:

    ERROR:  Parameter error.  Enter POPPST /? for Help.

    An .INI file without BODY.TXT produces the following error and warning messages:

    ERROR: 1 error written to the event log
WARNING: 1 warning written to the event log
(Event Error:  Internal program error: function OpenVirtualStreamOnFile(),
error code %%-2146762751)
(Event Warning: Using a temporary profile. No name
resolution will be performed)

    Running POPPST without using a valid profile produces the following warning message:

    WARNING: 1 warning written to the event log
(Event Warning: Using a temporary profile. No name
resolution will be performed)

    Using a valid profile with invalid TO, CC, BCC, or FROM user names produces these error messages:

    ERROR: 1 error written to the event log
Event Error: Could not resolve <field> name <user names>
message There are no more files.  ;error code %%-2137221233.

If you have successfully created a new PST, the <pstname>.PST file will appear in the directory from which the command was run. If you have populated an existing PST, the message should appear in the Inbox.


Formatting the POPPST.INI File

POPPST is used to create a new personal folder store (PST) and to populate it with messages. Alternately, you can use it to add test messages to a new PST if the NEWPST section is commented out and the PROFILE section is activated.

To replace the NEWPST section with the PROFILE section
  1. Remove the comment symbols (;) from the beginning of each line in the PROFILE section.
  2. Replace the name of the profile with an existing profile.
  3. Add comment symbols to the beginning of each line in the NEWPST section.

The POPPST.INI file below will create a new PST and populate it with one message:

;  poppst.ini
;  Sample INI input file forthe POPPST.EXE sample application
;
;  Notes: The [profile] and [newpst] sections are mutually exclusive.
;      See the poppst.cpp file for more .INI file syntax information
;  [profile]
;  NAME=User Twenty-two
;  PASSWORD=

[newpst]
NAME=Mailbox - Personal
ENCRYPTION=OFF
PASSWORD=
PATH=POPPST.PST

[message 1]
FROM=Jerry Wheeler
TO=None Two
BCC=Jerry Wheeler
FOLDER=Top of Information Store\Inbox
SUBJECT=POPPST Test Message 02/21/95-1
XTEXT=Body.Text
DATE=1996-02-01
TIME=10:25
PRIORITY=Normal
XATTACH=POPPST.INI

The default rights value for mail messages created with POPPST is set to READ. To create unread messages, you can modify the source code. Assuming you have just opened the message, you can use the MAPI IMessage::SetReadFlag method by adding code such as the following:

ASSERTERROR( lpMessage != NULL, "Invalid lpMessage!");
hr = MAPICALL(lpMessage)->SetReadFlag(lpMessage,
    CLEAR_READ_FLAG | MAPI_DEFERRED_ERRORS);
if( FAILED( hr))
    goto cleanup;
This will mark the message as unread.

You can also add additional messages. To view the new PST from the client, it must be associated with an active profile. See Running SMBAGENT.


NEWPST.LIB Functions

The NEWPST.LIB library contains the following functions:

Function | Purpose
HrCreatePersonalStore | Creates a new PST with properties determined by the input parameters in a temporary profile. The name and password of the temporary profile are returned to the user.
HrCleanupPSTGlobals | Releases objects used to create a new PST.


POPPST Sample Code

The following source files for the POPPST sample application are included in this documentation:

  • POPPST.CPP
  • NEWPST.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


POSTSMPL: Mail-Enabling an Application

The POSTSMPL sample application demonstrates how to add the mail-enabling functionality of Send and Post Message to a text editor. Several users can use POSTSMPL to route a document and incorporate their edits in a single file. This file can then be sent to another user or posted to a public or private folder from inside the text editor.

  • The Send Message option creates a mail message and attaches the currently open document to it.
  • The Post Message option creates a new mail message with the currently open document text.

When POSTSMPL is called, it opens a Text Edit box that allows the user to edit text using common toolbar commands. A summary page is included on the File menu, which allows users to fill in information that is used when the document is posted to the folder. Summary information can include the following:

  • Title
  • Author
  • Keywords
  • Subject
  • Comments

These five properties become standard MAPI properties when the document is posted and become the document heading.

To build POSTSMPL
  1. Change to the directory containing the POSTSMPL source files:

    \BKOFFICE\SAMPLES\EXCHANGE\POSTSMPL

  2. Type NMAKE.


Sending Edited Text with POSTSMPL

To send edited text with POSTSMPL
  1. Type POSTSMPL at a command prompt. The Choose Profile dialog box appears.

  2. Pull down the Profile Name combo box, if necessary, and select a profile for your messaging session. Click OK. A text edit box appears.

  3. Create a new file by typing text in the text edit box or open an existing file by choosing Open from the File menu.
  4. Save the contents by choosing Save from the File menu. The file must be saved before it can be posted or sent. If you change the file after it is saved, the changes will not be sent or posted unless the file is saved again.
  5. To include summary information with your file, select Summary Information from the File menu and fill in the properties.

  6. Choose Send from the File menu. A New Message box appears with your edited file as an attachment. Add any other text you wish to the message and select Send from the File menu or click the envelope-icon button.


Posting Edited Text with POSTSMPL

To post edited text with POSTSAMPL
  1. Create the message as directed in Sending Edited Text with POSTSMPL.
  2. Post the message to an existing folder by choosing Post Message from the File menu. The Select Folder dialog box appears.

  3. Select the folder in which you want to post the file. Click OK.

  4. To verify that the folder has been posted, edit the folder by selecting the new posting. Your edited text should appear.

To view the MAPI property values that were set on this message
  1. Activate the Microsoft Exchange Client.
  2. From the toolbar, select View, then Columns
  3. Select the columns representing the summary properties to verify the values.


POSTSMPL Sample Code

The following source files for the POSTSMPL sample application are included in this documentation:

  • POSTSMPL.CPP
  • FLDPICK.CPP
  • MAINFRM.CPP
  • POSTDATA.CPP
  • POSTDOC.CPP
  • POSTVIEW.CPP
  • STDAFX.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


PROFINST: Installing a MAPI Profile

The PROFINST sample application demonstrates how to create a MAPI profile for a server application. The server application can then use the profile to log on to MAPI. For more information about installing a server application, see Using a Batch File to Install SMBAGENT.

To build PROFINST
  1. Change to the directory containing the PROFINST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU

  2. Type NMAKE.


PROFINST Syntax and Parameters

To run PROFINST

Type the following on the command line:

PROFINST /SERVICE=<service name> /NAME=<profile name>
/TYPE=<profile type> [/DELETE] [/HELP or /?]

PROFINST Parameters

Flag | Setting
/SERVICE | Specifies service name, or displays name of service.
/NAME | Specifies profile name of the service.
/TYPE | Specifies profile type (GATEWAY or AGENT).
/DELETE | Deletes the profile.
/HELP or ? | Displays Help information.


Creating a MAPI Profile with PROFINST

To create a MAPI profile with PROFINST
  1. Create an object in the directory for the service using a utility such as MBINST or GWINST. See MBINST: Installing a Mailbox Agent and GWINST: Installing a Mail-Gateway Object.
  2. Install the server application as a service of Windows NT Server. See SERVINST: Installing a Service.
  3. To install the profile for the sample mailbox agent, type the following command all on one line:

    PROFINST /SERVICE=MB1 /NAME=MB1 /TYPE=AGENT

    In this example, a profile is created for a mailbox agent called MB1. The value of /SERVICE is the name assigned when the mailbox agent service was installed. The value for /NAME can be the Display-Name of the server application's directory object, or any name you choose.

  4. To install the profile for a gateway whose service name is GW1, type the following command all on one line :

    PROFINST /SERVICE=GW1 /NAME=GW1 /TYPE=GATEWAY

If the mailbox agent is to use an extension DLL, create a directory and copy the extension DLL into the directory. Install the DLL using the EXTNINST sample application. See EXTNINST: Installing an Administrator Extension.


PROFINST Sample Code

The following source file for the PROFINST sample application is included in this documentation:

  • PROFINST.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


RPTDRIV: Monitoring Message Delivery

The RPTDRIV sample application demonstrates how to generate delivery/nondelivery reports and read/unread reports about messages traveling across a gateway. It also demonstrates using the REPORT library functions. For a simple procedure for setting up and verifying a gateway, see Importing and Exporting with DIRSYNC.

To build RPTDRIV
  1. Change to the directory containing the RPTDRIV source files:

    \BKOFFICE\SAMPLES\EXCHANGE\RPTDRIV

  2. Type NMAKE.


Creating a Report Using RPTDRIV

RPTDRIV logs onto the messaging system as a gateway. This allows mail messages to be sent to RPTDRIV as if it were a gateway that the messages passed through. RPTDRIV reads each message, generates a report, and sends the report to the message originator.

To run RPTDRIV, a sample gateway must be installed. For installation information, see Sample Gateway and Applications.

To create a report with RPTDRIV
  1. Create a custom recipient with address type similar to the foreign system of the gateway. From the Microsoft Exchange Server Administrator program, select New Custom Recipient from the File menu. Type in the display name and the address type of the custom recipient. Verify that the custom recipient appears in the Recipients container.
  2. Type the following line at a command prompt:

    RPTDRIV NOTSERV <gateway-name>

    RPTDRIV is set up to intercept each message you send over the gateway, and read the subject line of the message to determine which type of report to return to the originator.

  3. Log on to a mailbox on the client.
  4. Submit a message to the custom recipient with subject line as described in the following table. A report of that type will be returned to you.

Note The subject must exactly match one of the choices shown in the following table for the report to be generated.

Subject Lines and Report Types

Subject | Description
NDR | Nondelivery report
DR | Delivery report
NRN | Nonreceipt notification
RN | Receipt notification


REPORT.LIB Functions

The NEWPST.LIB library contains the following functions:

Function | Purpose
HrEDKReportSubject | Returns a report subject.
HREDKReportMessageClass | Returns a report message class
HREDKSetReportMessageClass | Sets the report message class.
HrEDKEnvelopeMessageClass | Returns an envelope message class.
HrEDKCopyReportProps | Copies report properties.
HrReadReceipt | Creates a read/non-read notification report.
HeEDKCreateReadReceipt | Creates a RN/NRN report.
HrEDKCreateReadNotification Report | Creates a read notification report.
HrEDKCreateNonReadNotification Report | Creates a non-read notification report.


RPTDRIV Sample Code

The following source files for the RPTDRIV sample application are included in this documentation:

  • REPORT.C
  • RPTDRIV.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


RULEEDIT: Manipulating Rules

The RULEEDIT sample application demonstrates how to use an application to set, examine, and delete rules on a folder. For more information about rules, see About Rules and Sharing Information.

To build RULEEDIT
  1. Change to the directory containing the RULEEDIT source files:

    \BKOFFICE\SAMPLES\EXCHANGE\RULEEDIT

  2. Type NMAKE.


RULEEDIT Syntax and Parameters

To run RULEEDIT

Type the following on the command line:

RULEEDIT [/PROFILE=<profile name>] [<folder>] [/LIST || /FILE= <ini file>] [PROVIDER=<provider name>]

[/HELP or /?]

RULEEDIT Parameters

Flag | Settings
/FOLDER= | Specifies the full path name of the target folder. The correct syntax is: /FOLDER=<store name>\<folder path> or /FOLDER=INBOX
/LIST | Instructs RULEEDIT to list rules in the specified folder.
/FILE= | Specifies name of the .INI file containing information about actions to perform on the folder rules.
/PROVIDER= | Specifies rule provider name to use when listing or modifying rules on the folder.
/HELP or /? | Displays Help information.


Displaying Rules using RULEEDIT

When you run RULEEDIT with the /LIST switch, RULEEDIT displays the following values for each rule.

Values Displayed for Rules

Column | Description
Provider Name | Specifies the name of the provider used to create the rule.
Row number | Specifies the cursor position: continuous 0 - n. This represents the order in which rules are stored.
Rules state | Specifies whether the rules are Enabled (ST_ENABLED) or Disabled (ST_DISABLED).
Rule condition | Specifies an expression that represents the rule restriction
Rule action | Specifies the action(s) taken by the rule.
Rule level, Rule name | Shows internal rule attributes

Note If no provider name is specified from the command line, RULEEDIT will list rules for all providers.


Preparing the Command File

The RULEEDIT command file must contain several sections.

Initialization Section

The initialization section must appear first in the file and start with the [Initialization] header. The initialization section specifies general parameters used for the RULEEDIT session. These may include:

  • FOLDER=<folder name> Name of the folder in which the rules will be created. The syntax of this line is the same as the syntax of the /FOLDER command-line flag.
  • PROVIDER=<provider name> Name of the rule provider to use. If this value is not present in either the .INI file or the command line, the default MSFT:RuleEdit name will be used when inserting or deleting rules
  • PROFILE=<profile name> The MAPI profile used for logging to a store

Parameters specified in this section may be overwritten by setting the corresponding command-line flags.

Command Sections

These sections specify the individual rule creation, deletion, or listing commands that are to be executed during the RULEEDIT session. Each command section must start with a [Command#] header, where # is a unique number assigned to the command.

Note At this time individual command numbers specified in the .INI file are not used by the program and need not be unique. Commands are executed in the order they are listed in the file, not in the order of their numbers. It is recommended, however, that each command be assigned a unique number in the [Command#] header to maintain compatibility with future versions of RULEEDIT.

Valid Command Section Entries

Entry | Description
COMMAND= | Specifies a valid rule command, one of the following: DELETE|INSERT|LIST. For example, COMMAND=DELETE
POSITION= | Gives the rule position, a number designating a rule's position in the rule table. The rule command specified will be attempted at this position. This parameter is required only for INSERT or DELETE. For example, POSITION=0
aCTION= | Describes a rule action for a new rule. This parameter is needed only when COMMAND=INSERT. A list of possible actions is included in the following section. For example: ACTION=BOUNCE BOUNCE_MESSAGE_SIZE_TOO_LARGE
RESTRICTION= | Describes a rule restriction for the new rule. The restriction syntax used by RULEEDIT corresponds to the syntax used by the Rules interface. Only one restriction is allowed per command.


Rule Actions Recognized by RULEEDIT

Rule Actions and Parameters Recognized by RULEEDIT

Rule Action | Parameters
MOVE | COPY | Only one of these actions may be specified for any command. The parameter for both is the full pathname of target folder. For example: ACTION=MOVE /o=MICROSOFT/ou=NORTHWEST /cn="Public Folders" /cn="Next Week's Menu"
DELETE | No parameters.
REPLY | MSGID | Only one of these actions may be specified for any command. For REPLY, the parameter is replying text, for MSGID, the parameter is reply message identifier. For example: ACTION=REPLY "This is the last transmission."
FORWARD | DELEGATE | Only one of these actions may be specified for any command. The parameter for both is target recipient list. For example: ACTION=FORWARD "Eva Corets"
BOUNCE | Parameter is string value indicating reason for bounce. String values include: BOUNCE_MESSAGE_SIZE_TOO_LARGE | BOUNCE_FORMS_MISMATCH | BOUNCE_ACCESS_DENIED Only one bounce action can be contained in a single command. For example: ACTION=BOUNCE BOUNCE_ACCESS_DENIED
TAG | Property assignment. For example, ACTION=TAG PR_EMS_AB_DISPLAY_NAME="Shane S. Kim"
MARKREAD | No parameters.

Note If the rule being set must carry out several actions, you may specify several actions in a command section.


Rule Restrictions Recognized by RULEEDIT

The following are valid formats for rule restrictions used by RULEEDIT:

<SimpleCondition>

<Condition> | <Condition>

<Condition> & <Condition>

(<Condition>)

! <Condition>

<SimpleCondtion> ::= <StringCondition> | <NumericCondition>

<StringCondtion> ::= <Tag> ( = | # | } ) <StringLiteral>

<NumericCondition> ::= <Tag> ( # | = | > | < ) <NumLiteral>

<BoolCondition> ::= <Tag> = ( 1 | 0 )

<Tag> ::=<PR_xxxx of a property for a string value> |[ <HexNumber> ]

<NumLiteral> ::= <Decimal Number>

<StringLiteral> ::= <String enclosed in AND>

<HexNumber> ::= <StringOfHexDigits>

where the following rules apply:

  • | is logical OR. & is logical AND. ! is logical NOT.
  • AND and OR conditions group from left to right. They are always converted to binary operations. For example:

    A | B | C <=> ( A | B ) | C.

  • No precedence exists between AND and OR. For example:

    A | B & C | D <=> ( (A | B ) & ) C | D

  • The NOT operator always applies to the condition that immediately follows it. For example:

    : ! A | !B & ! ( !C | D ) <=> ( ( ! A ) | ( ! B ) ) & ( ! ( ( ! C ) | D ) )

  • = is equal.
  • # is not equal.
  • a } b is a contains
  • b. ::= is assignment

Note Unlike action entries, only one restriction entry may be present in a command section. If a rule is invoked on a complex restriction, the restriction must still be included in a single expression


The RULEEDIT Input File

The following is an example of a valid RULEEDIT input file:

[Initialization]
profile=Test User 1
folder=Public Folders\IPM_SUBTREE\Test Folder

[command 1]
command=insert
position=0
condition=PR_SUBJECT = "test public store actions"
action=bounce BOUNCE_MESSAGE_SIZE_TOO_LARGE

[command 2]
command=list
[command 3]
command=delete
position=0
[command 4]
command=list

If the execution of an input file is successful, a message such as the following is displayed:

Insert command at line 5 succeeded.

Listing of rules for provider 'MSFT:RuleEdit'
in folder 'IPM_Subtree\Test' in store 'Public Folders':

Row number = 10
Rule Condition = PR_SUBJECT = "test public store actions"
Rule Action 0 = Bounce with error code BOUNCE_MESSAGE_SIZE_TOO_LARGE
Rule Action 1 = Bounce with error code BOUNCE_FORMS_MISMATCH
Rule Action 2 = Bounce with error code BOUNCE_ACCESS_DENIED
Rule state flags = Enabled
Rule Level = 10
Rule Name =

Delete command at line 10 succeeded.

Rules table is empty.

Execution completed with no errors.

The following excerpt from the .INI file inserts a new rule at position 10:

[Initialization]
profile=Test User 1
folder=Public Folders\IPM_Subtree\Test Folder

[command 1]
command=insert
position=10
condition=PR_SUBJECT = "test public store actions"
action=bounce BOUNCE_MESSAGE_SIZE_TOO_LARGE
action=bounce BOUNCE_FORMS_MISMATCH
action=bounce BOUNCE_ACCESS_DENIED

The following .INI file lists all the rules on this Inbox:

[Initialization]
profile=Test User 1
folder=Public Folders\IPM_Subtree\Test Folder

[Command 2]
command=list

The following .INI file deletes the rule at position 5.

[Initialization]
profile=Test User 1
folder=Public Folders\IPM_Subtree\Test Folder

[Command 3]
command=delete
position=5


RULECLS.LIB Functions

Functions Contained in the RULECLS.LIB Library:

Function | Purpose
HrCopyActions | Makes a copy of an ACTIONS structure and all its subelements.
HrCopyRestriction | Makes a copy of an SRestriction structure and all its subelements.
HrFolderRulesGetProviders | Retrieves an array of rules provider names for a given folder.
HrFolderRulesOpen | Retrieves a pointer to an object which implements the IExchangeFolderRules interface defined in RULECLS.H.
HrActionToString | Retrieves a string representation of an ACTION.
HrRestrictionToString | Retrieves a string representation of an SRestriction.
HrStringToAction | Generates an ACTION structure that describes the action provided in *lpszString.
HrStringToRestriction | Generates an SRestriction structure that describes the restriction condition provided in *lpszString. The grammar for *lpszString is given in the header file RULECLS.H.
HrAdrListDisplayNamesToString | Retrieves a string representation of the display names in an ADRLIST.
HrAndRestrictionToString | Retrieves a string representation of an SAndRestriction.
HrContentRestrictionToString | Retrieves a string representation of an SContentRestriction.
HrCopyRestrictionArray | Copies an SRestriction array.
HrCreateReplyMsg | Creates a reply message for the reply action.
HrGetExplicitTag | Parses an explicit property tag token, returning results in *pti. A value for ulPropTag is returned in pti->dwValue.
HrGetExpressionToken | Parses a token in a condition expression, returning results in *pti. The types of token that may be parsed are defined by the TOKENTYPE enumeration.
HrGetFolderPath | Given the ENTRYID for a folder and a pointer to its store, retrieves its path name.
HrGetMoveCopyArgs | Parses the parenthetical expression following a move or copy action argument. Results are stored in the ACTION struct passed in as an argument.
HrGetNamedTag | Parses a named property tag token (PR_*), returning results in *pti. A value for ulPropTag is returned in pti->dwValue.
HrGetNumericLiteral | Parses a numeric literal token, returning results in *pti. A value for the numeric literal is returned in pti->dwValue.
HrGetStoreName | Given a pointer to an information store, retrieves its display name.
HrGetStringLiteral | Parses a string literal token, returning results in *pti. The user should allocate separate storage to save the string literal if it is to be converted to a MAPI property value.
HrNotRestrictionToString | Retrieves a string representation of an SNotRestriction
HrOrRestrictionToString | Retrieves a string representation of an SOrRestriction.
HrParseAction | Parses an action string.
HrParseCondition | Parses a restriction condition expression or parenthetical subexpression.
HrPrintToString | Writes the formatted string to the end of the supplied output string.
HrPrivateRestrictionToString | Retrieves a string representation of an SRestriction.
HrPropertyRestrictionToString | Retrieves a string representation of an SPropertyRestriction.
HrPropValueToString | Retrieves a string representation of an SPropValue.
lpszSkipNonWhiteSpace | Finds the first whitespace CHAR or '\0' in *pch.
lpszSkipWhiteSpace | Finds the first nonwhitespace CHAR in *pch.


RULEEDIT Sample Code

The following source files for the RULEEDIT sample application are included in this documentation:

  • RULEEDIT.CPP
  • RULECLS.CPP
  • RULECLSF.CPP
  • RULECLSI.CPP
  • ROWLST.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


SERVINST: Installing a Service

The SERVINST sample application demonstrates how to install a service of Windows NT Server on a local Microsoft Exchange Server computer or a Microsoft Exchange Client computer. After you create a new Microsoft Exchange Server service (a gateway or mailbox agent), you must install its profile, the service itself, and its extension DLL. For more information about installing a mailbox agent, see Using a Batch File to Install SMBAGENT.

To build SERVINST
  1. Change to the directory containing the SERVINST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU

  2. Type NMAKE.


SERVINST Syntax and Parameters

SERVINST has the following parameters.

To run SERVINST

Type the following on the command line:

SERVINST /SITEDN=<site distinguished name>
/OBJNAME=<object name> /OBJTYPE=<object type>
/SERVICE=<service name> /DISPLAY_NAME=<service display name>
/DEPENDENCIES=<service dependencies>
/EXE=<executable full pathname> /SERVER=<server computer name>
/ACCOUNT=<account name including domain> /PASSWORD=<account password>
[/DELETE] [/HELP or /?]

SERVINST Parameters

Flag | Settings
/SITEDN | Specifies the site distinguished name (DN), consisting of organization plus site. For example: /SITEDN=/o=Microsoft/ou=edkue
/OBJNAME | Specifies the object name for the service. This name can be the same as the display name.
/OBJTYPE | Specifies the object type (GATEWAY or AGENT). For example: /OBJTYPE=AGENT
/SERVICE | Gives the name to be assigned to the installed service, which becomes the final entry in the service key for the object. This name can be the same as the display name.
/DISPLAY_NAME | Displays the name of the installed service, which will be used in the service registry to refer to the object.
/DEPENDENCIES | Lists services that should be started before this service (separated by "%").
/EXE | Specifies the executable file name and path. For example: /EXE=C:\BKOFFICE\BIN\SMBAGENT.EXE
/SERVER | Specifies the server on which to install the service
/ACCOUNT | Gives the account name for the service. Be sure to include the domain name. For example: /ACCOUNT=REDMOND\EDKDOCS
/PASSWORD | Specifies the password for the service.
/DELETE | Deletes the service.
/HELP or ? | Displays Help information.


Installing a Service Using SERVINST

SERVINST is used to install a service such as a mailbox agent or gateway. This allows the service to be controlled by the service control manager.

To install a mailbox agent service
  1. Create an object in the directory for the service using a utility such as MBINST or GWINST. See MBINST: Installing a Mailbox Agent and GWINST: Installing a Mail-Gateway Object.
  2. To install a mailbox agent, fill in the parameters with the information particular to that mailbox agent. For example, type the following command to install a mailbox agent named MB1 at the Microsoft Northwest site:

    SERVINST /SITEDN=/o=Microsoft /ou=Northwest /DISPLAY_NAME=MB1 /OBJNAME=SampleMBA /OBJTYPE=AGENT
    /SERVICE=MB1 /EXE=C:\BKOFFICE\SAMPLES\EXCHANGE\WIN32\DEBUG\SMBAGENT.EXE
    /SERVER=MYSERVER /ACCOUNT=MYDOMAIN\<username> /PASSWORD=<password>

  3. Verify that each service has been installed by checking for its name in Services under the Control Panel.
  4. Use the PROFINST sample application if you want to create a profile for the service to use each time it starts. Such a profile allows you to examine the mailbox for a service. See PROFINST: Installing a MAPI Profile.
  5. If the mailbox agent or gateway is designed to use an extension DLL, create a directory and copy the extension DLL into the directory. Use the EXTNINST sample application to install the DLL. See EXTNINST: Installing an Administrator Extension.

After installing a service, you can control it with the Windows NT service control manager. Using SERVINST has no effect on objects in the directory.


SERVINST Sample Code

The following source file for the SERVINST sample application is included in this documentation:

  • SERVINST.C

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


SMBAGENT: Creating a Sample Mailbox Agent

The SMBAGENT sample application demonstrates how to use a mailbox agent to provide a mailbox agent service. SMBAGENT becomes a mailbox agent that enables users to perform the following tasks:

  • Create one or more discussion topics.
  • Subscribe to one or more existing topics.
  • Submit articles to existing topics.
  • Automatically receive new messages from other subscribers.
  • Request information about a given topic such as a topic list, members of the topics, or an introduction to the topic.

SMBAGENT performs a service similar to an Internet list server. When a user posts a message to SMBAGENT, the message is forwarded to all users who have subscribed to the message's topic. SMBAGENT uses the MAPI message-transfer functions to manage the flow of incoming and outgoing messages.

SMBAGENT is configured as a service on a public or private information store. The mailbox agent will always have a mailbox, but will also have a public folder if configured on a public information store. Users can send messages to SMBAGENT and receive messages from the mailbox agent as well. All messages sent to SMBAGENT follow a predefined format which SMBAGENT processes, thereby providing its list of services. For more information, see SMBAGENT Command Syntax.

To join a topic group, users type commands such as JOIN and the topic name in the subject line of an e-mail message.


SMBAGENT Build and Install Options

Several options are available to you for building SMBAGENT and installing the mailbox agent. You can build all the executables files of the mailbox agent together or separately. Sample applications can be placed in the directories required for MBSETUP installation by executing the makefile in the MBSETUP directory, or they can be manually moved to the correct directories. If you use the batch file or keyboard commands to install the mailbox agent, it is not necessary to move the files.

Three installation methods are available:

  • Sample mailbox setup program You can use MBSETUP (the sample mailbox agent setup program) to install the mailbox agent. Its interactive user interface allows you to install the server without manually entering the four keyboard commands. This option allows you to answer questions on the forms, rather than type in command line instructions.
  • Keyboard commands You can type in keyboard commands to call each sample application.

· Batch file You can create a batch file to complete the four install steps. This procedure is illustrated with a sample batch file and instructions for keyboard commands.


Building Mailbox Agent Elements

Files necessary to create the mailbox agent can be built as a set by executing the makefile under \BKOFFICE\SAMPLES\EXCHANGE, or each individual sample application can be built.

To build all the files necessary to create a mailbox agent
  1. Change to the directory that contains the source code for the sample applications:

    \BKOFFICE\SAMPLES\EXCHANGE

  2. Type NMAKE.

    This process takes 45 minutes or more, depending on the performance of your computer. At least 12 MB of disk space is required.

To build SMBAGENT.EXE
  1. Change to the directory containing the SMBAGENT source files:

    \BKOFFICE\SAMPLES\EXCHANGE\SMBAGENT

  2. Type NMAKE.
To build SMBADMIN.DLL
  1. Change to the directory containing the SMBADMIN source files:

    \BKOFFICE\SAMPLES\EXCHANGE\SMBADMIN

  2. Type NMAKE.

    If you have not changed the SMBAGENT or SMBADMIN source files, you can prepare your files for the MBSETUP install program by executing the makefile in the MBSETUP directory.

To prepare files for MBSETUP install using MBSETUP makefile
  1. Change to the MBSETUP directory:

    \BKOFFICE\SAMPLES\EXCHANGE\MBSETUP

  2. Run the NMAKE command using the /F flag and the MBSETUP.MAK input file:

    NMAKE /F MBSETUP.MAK

The process will use the default settings for the BLDTYPE and TARGETDIR environment variables unless you include these parameters on the command line. To view the environment variables, type SET at the command prompt.

Executing this makefile will automatically change the MBSETUP.INF file and move your files from their present directory location to the directory from which they are to be installed.

If you have changed any of the files or if your directory structure is not standard, you may want to move the files to the target directory individually and edit the MBSETUP.INF file. In that case, change the MBSETUP.INF file by following the steps in the following procedure.

To change file sizes and move files for the MBSETUP setup utility
  1. Examine the MBSETUP.INF file.

    \BKOFFICE\BIN\SAMPLEMB\MBSETUP.INF contains the following lines:

    [Local]
1, smbagent.exe,,,, 1996-06-29, !DECOMPRESS,,, !READONLY,,,,,,
876444,,,,, !VITAL

[Server]
1, smbadmin.dll,,,, 1996-06-29, !DECOMPRESS,,, !READONLY,,,,,,
23484184,,,, !VITAL

    The numbers 876444 and 23484184 are the file sizes of SMBAGENT.EXE and SMBADMIN.DLL, respectively, in this example file. The numbers will vary for different versions of the MBSETUP.INF file. If these numbers do not match the actual sizes of the files on disk, errors will occur when you attempt to install SMBAGENT.

  2. Find the actual file sizes. Change to the directory containing the file:

    \BKOFFICE\SAMPLES\SMBAGENT\WIN32\DEBUG

    Type DIR to list the files in this directory. Check the size of SMBAGENT.EXE and change the MBSETUP.INF file if the numbers do not match. Then find the actual file size for the SMBADMIN.DLL file by changing to the directory containing the file:

    \BKOFFICE\SAMPLES\SMBADMIN\WIN32\DEBUG

    Type DIR. Note the file's size and change the size in the MBSETUP.INF file if needed. If the numbers in the MBSETUP.INF file do not match the actual sizes of the files on disk, errors will occur when you try to install SMBAGENT.

  3. Move the SMBADMIN.DLL and SMBAGENT.EXE files to the \BKOFFICE\BIN\SAMPLEMB directory. Replace files of the same name located in the directory. You may wish to keep a copy of the replaced file in case you need to build and run it later.


Using MBSETUP to Install SMBAGENT

To use the MBSETUP setup utility to install the sample mailbox agent, the files must be moved to the correct directories prior to running the program. Do this by executing the makefile in the \BKOFFICE\SAMPLES\EXCHANGE\MBSETUP directory, or by moving the files yourself. See the previous section if you did not complete this step.

To install SMBAGENT using MBSETUP
  1. Gather the information necessary to install the mailbox server. The required information includes:
    • Display name (address-book entry) for the service
    • Service name used to start and stop service, which may or may not be the same as the display name
    • Service logon account
    • Password for that account
    • Installation directory path
    • Container for installation of the mailbox agent. Using any container other than the Recipients container for this installation can produce unexpected results.
  2. Confirm the organization name and the site name, which will be generated from the system information.
  3. Double-click the Sample Mailbox Agent Setup icon in the Microsoft Exchange Server SDK group on your desktop. This installs both SMBAGENT and SMBADMIN, and adds default configuration data to the directory. SMBAGENT should be installed in the Recipients container.
  4. In the Microsoft Exchange Server Administrator program, look in the Recipients container and find the newly installed service. Double-click the service to display its property sheet, then click on the Options tab. In the Options dialog box, enter a name for the topic root folder and a topic root folder comment. Also enter a time value in milliseconds for the Poll Inbox option. For example, enter 100,000 milliseconds to indicate that the service should poll its inbox every 10 seconds. Entries must be greater than 60,000.


Using Keyboard Commands to Install SMBAGENT

The Sample Mailbox Agent Setup program automatically installs the mailbox agent. The mailbox agent can also be installed in individual steps using keyboard commands. You may want to choose this option if you are debugging your application.

To install a new service using keyboard commands
  1. Install the service's object into the Windows NT Registry. Use MBINST to install a mailbox agent and GWINST to install a gateway. See MBINST: Installing a Mailbox Agent and GWINST: Installing a Mail-Gateway Object.
  2. Use the SERVINST sample application to install the service in Services under the Control Panel. See SERVINST: Installing a Service.
  3. To examine the mailbox for SMBAGENT, use the PROFINST sample application to install a profile for the service. See PROFINST: Installing a MAPI Profile. Alternately, you can add the SMBAGENT mailbox to an existing profile so that this profile opens both mailboxes. See Running SMBAGENT for an explanation of the procedure.
  4. Copy the extension DLL into the required directory. This directory should be below the add-ins directory. Execute these commands in order:

    CD <directory path to add-ins>\add-ins

    MD SAMPLEMBA

    CD SAMPLEMBA

    MD <computer name>

    CD <computer name>

    XCOPY C:\BKOFFICE\BIN\SMBADMIN.DLL

  5. Use the EXTNINST sample application to install an extension DLL. See EXTNINST: Installing an Administrator Extension.


Using a Batch File to Install SMBAGENT

The following batch file consists of calls to the Microsoft Exchange Server sample applications listed above. The batch file uses the same sample applications as the keyboard commands. You can use the batch file to install your mailbox agent.

To install a new service using a batch file

Prepare a file similar to the following and execute it on your server computer.

@echo off
rem test smba inst utilities from exchsdk
rem =====================================================================

rem check for Help request
if .%1.==.-?. goto usage

rem check if deleting
set deletemode=
if .%1.==.. goto start
if .%1.==.delete. goto delete
if .%1.==.DELETE. goto delete
rem shouldn't fall through to here, show usage
goto usage

:delete
rem wants to delete
set deletemode=/delete

:start
echo checking for Organization and Site environment variables...
if .%Organization%.==.. goto usage
if .%Site%.==.. goto usage
if .%projroot%.==.. set projroot=c:\exchsdk
echo Organization is %Organization%
echo Site is %Site%
echo Projroot is %projroot%
echo delete status is %deletemode%
echo.

echo setting temporary variable for password
set userpassword=slapshot

echo moving to %projroot%\bin subdirectory
c:
cd %projroot%\bin

echo.
echo installing mailbox agent...
%projroot%\bin\mbinst /SITEDN=/o=%Organization%/ou=%Site%
/DISPLAY_NAME=SampleMBA /RELATIVE_DN=/cn=Recipients/cn=SampleMBA
/SERVER=%COMPUTERNAME% /EXTNAME=SampleMBA
 %deletemode%

echo.
echo installing service (mailbox agent)...
%projroot%\bin\servinst /SITEDN=/o=%Organization%/ou=%Site%
/OBJNAME=/cn=Recipients/cn=SampleMBA /OBJTYPE=agent
/SERVICE=SampleMBA /DISPLAY_NAME=SampleMBA /DEPENDENCIES=
/EXE=%projroot%\bin\smbagent.exe /SERVER=%COMPUTERNAME%
/ACCOUNT=%USERDOMAIN%\%USERNAME% /PASSWORD=%userpassword%
%deletemode%

echo.
echo installing extension (configuration) data (mailbox agent)...
%projroot%\bin\extninst /SITEDN=/o=%Organization%/ou=%Site%
/DISPLAY_NAME=SampleMBA /MACHINE=i386 /NAME=SampleMBA
/EXTDLL=%projroot%\bin\smbadmin.dll /SERVER=%COMPUTERNAME%
%deletemode%

if .%1.==.delete. goto continue
cd\exchsrvr\add-ins
md SampleMBA
cd SampleMBA
md i386
cd i386
xcopy %projroot%\bin\smbadmin.dll .

:continue
cd %projroot%\bin

echo ----------------------------------------------

goto done

:usage
echo Installing the Sample Mailbox Agent
echo example: mbtest  [(delete)]
echo add delete if removing the smba
echo Mailbox agent will be named SampleMBA
echo.
echo Environment: these environment variables must be set to their
proper values
echo Organization=Microsoft
echo Site=Site6
echo projroot=[root directory for SDK] NOTE: this one is set when you
install SDK
echo.
echo Assumptions:
echo server name is same as computer name: %computername%
echo addrtype is EDK
echo user domain and name are %userdomain% and %username%

:done
set userpassword=
set deletemode=
echo All done.


Running SMBAGENT

To run SMBAGENT as a service
  1. Double-click the Services icon in the Control Panel. Select the service you installed, then click Start to start the service.
  2. When SMBAGENT is running, establish a topic. Send messages to the topic to test whether the messages have been correctly distributed.

To establish a topic with SMBAGENT
  1. Select New Message from the Compose menu on the Microsoft Exchange Client. The New Message dialog box appears.
  2. In the To field of the dialog box, type the name of the mailbox agent. If you used the batch file to install the mailbox agent, your server name will be SAMPLEMBA.
  3. In the Subject field of the dialog box, type NEW and the topic name. For example, NEW INTERNET PROGRAMMING.
  4. In the body of the message, type the introductory message. Note that the introductory message can be included as an attachment, but SMBAGENT will not accept a link to the file. For example,

    This topic allows enlisted members to ask questions about
    internet programming and have them answered by other
    members of the group. Each member can also distribute any
    interesting articles regarding internet programming.

  5. Wait for a response. The following message should appear:
    The requested topic has been created

To join a new topic
  1. On the Microsoft Exchange Client, select New Message from the Compose menu. The Microsoft Exchange New Message dialog box appears.
  2. In the To field of the dialog box, type the mailbox agent name.
  3. In the Subject field of the dialog box, type TOPICS.
  4. Send the message by selecting Send from the File menu.
  5. Wait for a response from the mailbox agent. You should receive a message containing a list of topics.
  6. Select New Message from the Compose menu on the Microsoft Exchange Client. The New Message dialog box appears.
  7. In the To field of the dialog box, type the mailbox agent name you selected.
  8. In the Subject field of the dialog box, type JOIN <your topic>. For example, JOIN INTERNET PROGRAMMING.
  9. Send the message by selecting Send from the File menu.
  10. Wait for a response from the mailbox agent. You should receive this message:
    You have been enlisted in the requested topic.  Attached is the introduction message

    The introduction message included in the previous message should be returned to you.

To post a message to a new topic
  1. Select New Message from the Compose menu on the Microsoft Exchange Client. The New Message dialog box appears.
  2. In the To field of the dialog box, type the mailbox agent name.
  3. Type POST <your topic> in the Subject field of the dialog box.

    In the message field, type the information to post.

  4. Send the message by selecting Send from the File menu,.
  5. Wait for a response from the mailbox agent. You should receive the following message:
    The message has been successfully posted for the requested topic

    If you have joined the topic, you should receive a copy of the new message. All subscribers who have joined the topic should receive this new posting.

    While running SMBAGENT, you may want to examine the messages in the mailbox for the mailbox agent. If you install a profile for the mailbox agent, you can simply open this mailbox by logging on to the Microsoft Exchange Client using its profile. For a procedure, see PROFINST: Installing a MAPI Profile.

    Alternately, you can add the SMBAGENT mailbox to another profile.

To add the SMBAGENT mailbox to another profile
  1. Log on to the Microsoft Exchange Client using the profile you would like to modify.
  2. From the Tools menu, choose Options.
  3. From the Services tab, choose Properties. From the Properties tab, choose Advanced.
  4. Click Add next to the Open these Additional Mailboxes: dialog box. The Add Mailbox dialog box appears.
  5. Type the display name for SMBAGENT in the box. Click OK.
  6. In the Advanced tab, click Apply. Then click OK. Close the options box.
  7. Exit from the Microsoft Exchange Client, then log in again. The mailbox agent's mailbox should appear in the left pane of your viewer.


SMBAGENT Command Syntax

Each message submitted to SMBAGENT must contain only one command keyword, followed by the <topic name>. Commands and topic names are specified in the subject field of the message. The message body is ignored except in the case of the NEW and POST commands, where it contains information to be copied to the specified area.

The maximum length of a topic used with SMBAGENT is 100 characters.

Recognized SMBAGENT Commands and Actions

Command | SMBAGENT Actions
NEW <topic name> [Introductory Note] | Creates a new topic by creating a topic folder and copying the message body into the folder's associated data area. This hidden message becomes the topic's introduction and will contain the complete list of topic subscribers.
JOIN <topic name> | Adds the sender's e-mail address to the subscriber list of the topic and sends the introductory note back as part of the confirmation message.
POST <topic name> [Posting] | Verifies the subscriber against the subscriber-list and, if verified, saves the posting (entire message body) as a message in the topic folder. This posting is then redistributed to the current subscribers of the topic.
LEAVE <topic name> | Deletes the sender from the current subscriber list of the specified topic and, if the last subscriber, deletes the topic.
INTRO <topic name> | Returns the introductory message for the specified topic.
TOPICS | Returns a list of all topics to which the sender is currently subscribed.
MEMBERS <topic name> | Returns a list of the member for the specified topic.

SMBAGENT confirms each message by returning the requested information with an explicit confirmation message to the sender. In cases where SMBAGENT cannot return the information, an error message is returned to the sender.

Confirmation Messages

Action | Response
NEW | The requested topic has been created.
JOIN | You have been enlisted in the requested topic. Attached is the introduction message.
POST | The message has been successfully posted for the requested topic.
INTRO | Attached is the introduction for the requested topic.
LEAVE | You have been removed from the subscriber list for the requested topic.
TOPICS | The message body contains a list of all topics.
MEMBERS | The message body contains the membership for the requested topic.

For all messages, the original message is included at the top of each confirmation message. An additional message (the topic introduction) is attached at the end of the Join and Intro confirmation messages. Error messages contain only one attachment, the original message, at the top of the message.

Error Messages from SMBAGENT Commands

Error type | Error Message
No command | ERROR: Missing the command keyword.
Bad command | ERROR: Unrecognized command keyword.
Command only | ERROR: Missing the topic name.
Create attempt | ERROR: The topic already exists.
Nonexistent | ERROR: The topic does not exist.
Nonsubscriber | ERROR: You are not a subscriber of the specified topic.
Join attempt | ERROR: You are already a subscriber of the specified topic.
Corrupt topic | ERROR: Can't open the topic folder. (May be missing associated data.)
Topic too long | ERROR: Topic name too long. (Topic names must be less than 100 characters.)
Init Failure | ERROR: Can't initialize the root topic folder. Contact your administrator.
General Error | ERROR: General Sample Mailbox Agent Error. Contact your administrator.


SMBAGENT Folder Architecture

Because SMBAGENT uses the MAPI folder hierarchy, a separate database is not built to save postings for discussion topics. Instead, when a user requests a new topic, SMBAGENT creates a new subfolder for the topic within the specified message store. The folder hierarchy of the SMBAGENT information store is shown in the following figure.

The information store folder structure used by SMBAGENT

As this illustration shows, folders in this hierarchy contain either documents or other folders, as described in the following table.

Folder | Contents
Mailbox Root Folder | Inbox, Outbox, and Topics Folder
Inbox | Messages addressed to SMBAGENT
Outbox | Messages submitted by SMBAGENT
Topics Folder | Mailbox agent topic subfolders
Topic Subfolder | Topic-specific information and articles
Undelivered Messages | Messages that cannot be delivered

Every SMBAGENT installation contains a mailbox. Some also contain public folders. If the option is chosen to create a public folder, this folder will serve as a public list of all the topics and postings. The public folder points to the mailbox. The actual information resides at the mailbox.

Each topic subfolder contains one or more messages. The topic's creator, subscriber list, and an introductory message are stored in the associated message area. Thereafter, articles submitted to each topic are saved as messages in the appropriate topic subfolder, along with their associated information, such as author, date, and attachments.

The introductory messages contain information about each topic and how to use it. When a user joins a topic, SMBAGENT locates the introductory message for that topic, changes its recipient list, and transmits it to the user who just joined.

SMBAGENT uses the introductory message to maintain a list of members for each topic. As new members join a topic, their names are added to the recipient list of the introductory message. SMBAGENT stores recipient names in a message's recipient list instead of a distribution list. SMBAGENT uses this method because standard MAPI does not provide table modification functions, and a distribution list is a table.


SMBAGENT Operation

All messages submitted to SMBAGENT are placed in the Inbox folder by the message transfer agent (MTA). SMBAGENT receives notification of each new message from Microsoft Exchange Server through MAPI. When notification is received, the Inbox is searched for new messages. SMBAGENT also implements a polling mechanism that checks the Inbox, even if it has not received notifications. This polling allows messages to be found if problems such as server outages have prevented notification. The default polling frequency is set to one minute, but this can be modified by SMBADMIN. The value NONE turns polling off.

Commands such as JOIN or LEAVE cause SMBAGENT to update information in the existing introduction message for the appropriate topic. Other commands, such as POST, cause the mail agent to generate a message for storage in one of the topic subfolders.

The relationship between SMBAGENT, Microsoft Exchange Server, and a Microsoft Exchange Client is shown in the following figure.

SMBAGENT application architecture

This figure shows Microsoft Exchange Server and SMBAGENT on a single server computer. SMBAGENT uses MAPI to communicate with Microsoft Exchange Server and send and receive information. Microsoft Exchange Client users send commands to SMBAGENT by sending mail messages.

When a message arrives at the SMBAGENT mailbox on Microsoft Exchange Server, SMBAGENT reads the message's Subject property to determine which command to execute. SMBAGENT responds by posting mail messages to Microsoft Exchange Server, which forwards the messages to appropriate recipients.

A user who registers interest in a topic becomes a member of that topic. As messages from members are received, SMBAGENT archives them according to their discussion topic. SMBAGENT can also connect to and store postings in public folders.

The Sample Mailbox Agent will return a General Error message when an attempt is made to create a new topic with an Intro message that includes a link.


Obtaining Access to SMBAGENT Topics

By default, the mailbox agent itself is set as the owner of all folders and files associated with SMBAGENT, and will have owner access to all files. Additional logons can be granted access as owner or administrator. Default user rights (which apply to any user who is not specifically granted another access) are set to the rights associated with the Reviewer role, that is, to ReadAny, which gives read permission to any message in the folder, but not edit, create, or delete access.

Access Permissions to Public Folders Created by SMBAGENT

Access Permissions | Rights to SMBAGENT Public Folder
READ= | frightsReadAny (read all messages)
WRITE | frightsEditAll (modify and save changes for all messages)
CREATE | frightsCreate (create message)
DELETE= | frightsDeleteAny (delete all messages)
OWNER | frightsOwner (allows deletion of folders and modifications to ACL tables)
CONTACT | frightsContact (name is displayed as contact in the folder's Summary property page)

As subfolders are created, the access control list (ACL) created for the root folder is inherited by the subfolders. That is, all users explicitly granted permissions in the root folder also have these rights on the subfolders. An exception is the default user access permissions, which are always ReadAny for subfolders (although the default permission may be changed for the root folder).

Changing default user access permissions is not recommended because problems multiply when users have Edit, Create, and Delete permissions to the folders and messages. Problems that may occur include the following:

  • Folders created by any other means than through the NEW command will not have an associated Intro message and recipient list. These folders generate errors when messages are posted.
  • Messages posted directly to the topic folder rather than through the POST command will not be delivered to other subscribers, and the other subscribers will not be notified of their presence.
  • Deleted folders will cause general errors until the service is restarted or a new configuration is applied.
  • Changing ACLs affects new folders and messages only. ACLs on existing folders and messages are not changed.


SMBAGENT Sample Code

The following source files for the SMBAGENT sample application are included in this documentation:

  • ACL.C
  • COMMANDS.C
  • MESSAGES.C
  • SMBAGENT.C
  • TFLDARY.C
  • TOPCACHE.C
  • TOPICS.C
  • EDITEXT.CPP
  • GLOBAL.CPP
  • SMBADMIN.CPP
  • TESTDLG.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


TOOLFORM: Creating a C or C++ Form

The TOOLFORM sample application demonstrates how to create a form using C or C++, as well as how to install and use that form. A form created with C or C++ will perform more quickly but will not be as easy to modify as a form created with the Microsoft Exchange Forms Designer.

TOOLFORM is itself a form created using C++ and Microsoft Foundation Classes (MFC). A similar form could be created using C and MFC.

For general information about forms design, installation, and management, see Forms. Additional information can be found in the Microsoft Exchange Server Application Designer's Guide.

TOOLFORM is a simple form that lacks much of the functionality of other Microsoft Exchange Server forms. For example, the recipient is hard-coded and is called "Tools." The form's purpose is to demonstrate required C++ development tasks and the resulting performance advantage. The source code can be modified to produce a form similar to other Microsoft Exchange Server forms.

To build TOOLFORM.EXE
  1. Change to the directory containing the TOOLFORM source files:

    \BKOFFICE\SAMPLES\EXCHANGE\TOOLFORM

  2. Type NMAKE.

To verify that the form has built correctly
  1. Change to the directory containing the form (\BKOFFICE\SAMPLES\EXCHANGE\TOOLFORM\WIN32\<build type>)
  2. Type TOOLFORM. You should see a copy of the form.

To install the TOOLFORM form in the Forms Library, use the INSTFORM sample application, or use the standard form install procedure on the Microsoft Exchange Client.

Before you run INSTFORM, edit the .CFG file to reflect where the .EXE file resides in the directory tree. Under the section for your development platform ([Platform .NTx86] for example), edit the file1= entry so that it indicates where the .EXE file is, or move the .EXE file to the directory in the file1= entry of the .CFG file. Then run INSTFORM. Syntax and parameter information is found in INSTFORM Syntax and Parameters.

To install the TOOLFORM Form in the Personal Forms Library
  1. To install the form in the personal forms library, type a command similar to the following:

    INSTFORM /INSTALL C:\EXCHSDK\SAMPLES\EXCHANGE\TOOLFORM\TOOLFORM.CFG
    /REGISTRY=PERSONAL /PROFILE=<user profile name>

  2. Verify that the TOOLFORM form has been installed by opening and sending the form.

To verify successful installation of TOOLFORM
  1. Start the Microsoft Exchange Client.
  2. Create a new mailbox called Tools if you do not have such a mailbox. This form may only be sent only to a destination mailbox called Tools unless the source code is modified.
  3. From the Tools menu, choose Options. Select the Microsoft Exchange Server property page.
  4. Click Manage Forms. The Forms Manager dialog box is displayed with additional controls.
  5. Select the library you want to view by clicking the Set button opposite that entry.
  6. From the Compose dialog box, select New Form. Under Organization, select the Toolform form. The form opens.
  7. Fill in the fields of the form
  8. Send the form to Tools.


TOOLFORM Sample Code

The following source files for the TOOLFORM sample application are included in this documentation:

  • FORM.CPP
  • FORMDATA.CPP
  • FORMFACT.CPP
  • FORMMAPI.CPP
  • FORMPRST.CPP
  • FORMUNK.CPP
  • MAINFRM.CPP
  • TOOLDOC.CPP
  • TOOLFORM.CPP

Other source files may be found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


TRACK: Tracking and Auditing Messages

The TRACK sample application demonstrates message tracking across a gateway. It also demonstrates the use of EDKTRACK.LIB functions, which are used to track and audit delivery reports (DR) and nondelivery reports (NDR) that are generated by the gateway or passed through the gateway. For more information about tracking message transfer, see Mapping Message Identifiers.

TRACK writes message-tracking information to a file. First, you enter the data that pertains to a message at a command line. Then the application writes the information to a file using the HrWriteTrackLog function from EDKTRACK.LIB. The message can then be read by another application.

To build TRACK.EXE
  1. Change to the directory containing the TRACK source files:

    \BKOFFICE\SAMPLES\EXCHANGE\TRACK

  2. Type NMAKE.
To run the TRACK application

Type TRACK at a command prompt and enter the requested information. To use EDKTRACK.LIB library functions, compile them together with an actual gateway. Then, every message that passes through the gateway in either direction is tracked. The TRACK sample application stands in for a gateway. TRACK provides data to be written to a log, although TRACK does not store actual messages in the log.


EDKTRACK.LIB Functions

The EDKTRACK.LIB library contains the following functions:

Function | Purpose
HrTrackInitLog | Initializes the gateway event tracking module (the library).
HrTrackWriteLog | Logs a gateway tracking event (the movement of a message or a report).
HrTrackUninitLog | Uninitializes the gateway event tracking module.


Events Monitored by TRACK

Event | Meaning
tevtMessageBackboneTransferIn | Backbone message going to Microsoft Exchange Server
tevtMessageBackboneTransferOut | Backbone message going to a foreign system
tevtMessageGatewayTransferIn | Gateway message going to Microsoft Exchange Server
tevtMessageGatewayTransferOut | Gateway message going to a foreign system
tevtReportGatewayTransferIn | Gateway message going to Microsoft Exchange Server
tevtReportGatewayTransferOut | Gateway message going to a foreign system
tevtReportGatewayGenerated | Report of gateway activity

For more information about events monitored by TRACK, see the \BKOFFICE\INCLUDE\RPCPUB.H file.


TRACK Sample Code

The following source files for the TRACK sample application are included in this documentation:

  • EDKTRACK.C
  • TRACK.C

Other source files are found under the \BKOFFICE\SAMPLES\EXCHANGE and \BKOFFICE\INCLUDE directories.


Application Debugging

Choosing the best debugging methods and tools are an important part of the development process for any Microsoft Exchange Server application. For example, the most efficient way to begin debugging a server application is to run it as a Windows NT Server console application, which allows you to step through your code from the first instruction. Then, when the application is running smoothly, you can attach the Microsoft Visual C++ debugger to the running process.


Debugging a Service

Debugging a service presents certain unique problems. For example, the Visual C++ debugger is normally connected to a service that is running. However, you may need to collect debugging information early in the development cycle before the service can be run. One solution is to run the service as a console application.


Debugging a Service as a Console Application

The easiest way to begin debugging a service of Windows NT Server is to artificially run it as a console application — in other words, at a command prompt . This method allows you to step through your code from the first instruction, provides more complete access to the Visual C++ debugger, and supplies a window for viewing MAPI messages.

To set up your service as a console application, you need to handle the return codes from the service control manager and then take the appropriate code path in your startup code.

In other words, when an application runs as a service of Windows NT Server, the service control manager is usually called to find the application's main function. If the process is artificially running as a console application, calls to the service control manager fail. This is when you should branch, and call your main function explicitly.

To run your application as a console application, you must include the WINWRAP.LIB library in your makefile. This will handle the service control manager calls. If you do not include this library, look at the library's source code and make the necessary changes to your application's main function.

For sample code that illustrates this mechanism, see the sample gateway application GWSAMPLE.C. To run the sample gateway as a console application under the Visual C++ debugger, include the notserv startup parameter in your process. To run your executable, choose Settings from the Project menu, and then choose Debug.

Note The notserv argument must always be the first argument specified.


Connecting the Debugger to a Running Service

Running your service as a console application will not be useful if problems appear only when the application is run as a service. In this case, the best way to debug it is to start the application as a service and attach to the Visual C++ debugger while the service is running. To do this, start the service, obtain the process identifier, and then connect the debugger to the running process.

To find the process identifier and connect to the Visual C++ debugger
  1. Install PVIEW.EXE from the Windows NT Resource Kit.

    Caution This utility is not identical with the utility of the same name distributed with Microsoft Visual C++ and the Platform SDK. It is an extended version with more functionality. The correct version displays the window title Process Explode, rather than Process Viewer.

  2. Start the service to be debugged. The service must be running before you can find its process identifier.
  3. Start a command prompt or open an existing command prompt. Be sure that it is the only command prompt currently active.
  4. Change directory to the installed location of PVIEW.EXE.
  5. Type PVIEW.
  6. In the drop-down list box near the top left of the PVIEW screen, find and select the process IDENTIFIER corresponding to CMD.EXE.
  7. In the PVIEW dialog box, select Token. Click Process.
  8. In Privileges, move SetDebugPrivilege from the Disabled box to the Enabled box. Click OK.
  9. Connect Visual C++ to the running service. Note that when you use the process identifier from the Windows NT Server version of PVIEW.EXE, the process identifier is in decimal not hexadecimal. Start Visual C++ with the command line:

    START MSDEV /P nnn

    where nnn is the process identifier in decimal or hexadecimal notation.


Debugging Initialization Routines

Usually, the simplest way to use the debugger is to attach it to a running service. However, if you are debugging the service's initialization routines because the service won't start, you may not be able to connect the debugger to your application before the problem appears. To debug initialization routines, you can forego the debugger entirely and use the log file, or insert hard-coded breakpoints in your code. You can also set up a specialized environment within the debugger to debug initialization routines.

To use the debugger with an initialization routine, you must first edit the Windows NT Registry so that the service control manager will start both the debugger and the service. Set the value of the ImagePath environment variable to contain a command line that executes the service under a debugger. As an example, the following procedure shows how to debug the Schedule service (one of the default services of Windows NT Server).

To debug the Schedule service
  1. Start the REGEDT32.EXE program and locate the following registry key:
    \\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Schedule
  2. Change the associated value entry for ImagePath from:
    %SystemRoot%\System32\AtSvc.Exe

    to the following:

    msvc %SystemRoot%\System32\AtSvc.Exe
  3. In the Control Panel, choose Services. Select the Schedule service and choose StartUp. In the Log On As field of the Service dialog box, click Allow Service to Interact with Desktop. Click OK.
  4. In the Services dialog box, click Start. Visual C++ should start immediately.
  5. Activate the Visual C++ window to begin the debugging process.


About the Registry Editor

Windows NT stores its configuration information in a database (the registry) that is organized in a tree format. Registry Editor enables you to inspect and modify the registry.

To run Registry Editor
  1. Click Start, and then click Run.
  2. Type regedt32 in Open.

To run Registry Editor from Windows NT Explorer, double-click Reget32.exe in the %SystemRoot%/System32 folder.


Debugging Administrator Extension DLLs

The following steps show how to debug and set a breakpoint in an Administrator extension DLL in Visual C++ Version 4.0.

To set debug breakpoints for extension DLLs
  1. Start Visual C++.
  2. From the File menu, choose Open, and select the EXCHSRVR\BIN\ADMIN.EXE file.
  3. From the Project menu, choose Settings.
  4. On the Debug page, add the name and full path of your extension DLL in the Additional DLLs dialog box.
  5. Open your extension DLL source and set the breakpoints.
  6. To start the Microsoft Exchange Server Administrator program and begin debugging, choose Debug, choose Go, or press F5.
  7. Check Yes for OK not to have debugging information for this file.
  8. Use the Administrator program to open a directory object on which your extension DLL is installed.
  9. The Administrator program calls your DLL. The debugger will now stop at any breakpoints you have set.


Debugging Proxy Generation DLLs

Proxy generation DLLs are used to generate proxy addresses, which are addresses of foreign system users as expressed on Microsoft Exchange Server. Debugging proxy generation DLLs requires a few extra steps because the library is loaded dynamically only when needed. To trace a proxy generation DLL in the Microsoft Visual C++ debugger, you must load the calling program into Visual C++. All calls into the proxy generation DLL are made from the System Attendant service of Microsoft Exchange Server, which is implemented by MAD.EXE.

  1. On a computer running Microsoft Exchange Server, check that the System Attendant Service is running. In Control Panel, click Services, then find Microsoft Exchange System Attendant. If Status is not Started, click Start.
  2. Connect the debugger to this service (see Connecting the Debugger to a Running Service). The process identifier of the System Attendant service is found by searching for MAD.EXE in the table of running processes.
  3. Check Yes for OK not to have debugging information for this file.
  4. Start the Administrator program.

    At this point, you will not be able to set any breakpoints in your code because your DLL is not yet loaded. The System Attendant service will only load your proxy generation DLL when it is required by the process. Because you are connecting to MAD.EXE when it is already running rather than starting MAD.EXE in the debugger, specifying your proxy generation DLL in the Project Settings menu box under the Additional DLLs box will cause no action.

    If you need not begin tracing within your initialization code, continue following the steps in this procedure to debug your DLL.

  5. Using the Administrator program, perform an action that will cause your proxy generation DLL to be called. For example, create a new mailbox and switch to its E-Mail Addresses page.

    The Administrator program calls MAD.EXE. This loads your DLL and calls its initialization routines, as well as any routines relevant to the action you just performed.

  6. After your proxy generation DLL is loaded, open its source and set the breakpoints.
  7. Using the Administrator program, perform additional actions that will call your proxy generation DLL. Now the debugger will stop at your breakpoints.

If you must begin tracing at your initialization code, set a hard-coded breakpoint in that code. After your proxy generation DLL is loaded by performing one of the previously described actions, the hard-coded breakpoint will be hit. You can trace your code in the debugger from that point.


Tools for Debugging

A number of specialized debugging tools are available from MAPI, the Microsoft Exchange Server Administrator program, and the Microsoft Exchange Server SDK. They include the following:

  • Environment variables for debugging You can set values for the environment variables EDK_DEBUG_FILE, EDK_ASSERT, and EDK_DEBUG to control runtime debug logging. See Setting Environment Variables.
  • MAPI debug DLLs MAPI provides a debug version of its DLLs. They are used to find and fix memory leaks, as well as to perform other debugging tasks.
  • The message store viewer This MAPI utility (MDBVU32.EXE) shows all the properties of a message or any object in the information store. For more information, see Using the Message Store Viewer.
  • Microsoft Exchange Server Administrator The Microsoft Exchange Server Administrator program provides several debugging tools. For example, the Raw Properties screen allows you to look at and change properties on directory objects. This screen is an option on the File menu of the Administrator program. For more information, see Using the Raw Properties Screen.
  • Track Message sample application This application (TRACK.EXE), which is provided by the Microsoft Exchange Server SDK, tracks message flow between applications. It can be used to determine the origin and destination of messages as your application processes them. For more information, see TRACK: Tracking and Auditing Messages.


Using the ExchSDKd Library

The Microsoft Exchange Server SDK contains a library called ExchSDKd.LIB, which includes a collection of macros and asserts that can be very useful when debugging a server application. Many calls, such as the ASSERTERROR and DEBUGPUBLIC macros, can be inserted in the code as it is written. They then provide debugging information, as well as future data. The best way to become familiar with available calls is to study the ExchSDKd library and header file source code.

Using ExchSDKd Asserts

The asserts contained in the ExchSDKd library are not typical. Their default behavior is not to stop the process, or even to cause warnings or error messages, but rather to print silently to a log file. These log files are stored in the system's temporary directory and are given unique names each time the application is run.

You can use the asserts as they were designed and read the log file they produce, or you can change their behavior: They can be modified to cause a prompt to appear, cancel the process, or start the debugger when they execute. Environment variables that can be used to change the name and path of the log file and the debug output printed by the log file are located in the ExchSDKd source file EDKLOG.C.

Using ExchSDKd Memory Wrappers

ExchSDKd contains memory wrappers that allow you to control your application's memory allocation. Use these functions to find and fix memory problems. These functions wrap standard memory allocation functions such as malloc and MAPI functions such as MAPIAllocateBuffer.

Using ExchSDKd Macros

The ExchSDKd library includes macros for testing the validity of pointers. Use these macros to check for nonnull values or for the correct values or data types. For example, you can check for IUnknown pointers, which identify the object as a MAPI or WIN32 object.

The assert macros include the following:

  • ASSERTERROR
  • TEST_IUNKNOWN_PTR
  • TEST_READ_PTR
  • TEST_WRITE_PTR
  • TEST_STRING_PTR
  • TEST_FUNCTION_PTR


Using Component Parameter Checking

Because MAPI and Microsoft Exchange Server service providers implement strict parameter checking, they often return the MAPI_E_INVALID_PARAMETER error code, which can help with debugging. You can use this mechanism to make sure the parameters you are passing are valid. Parameters are checked first, within the call, and the parameters of nested structures are checked at the same time. This and similar error codes can help you determine whether the object you are passing contains valid properties and parameters.

MAPI_E_INVALID_PARAMETER does not always pinpoint errors, especially when your code deals with MAPI objects that contain other objects. This is a general error return that can apply to many sub-objects of a complicated object, such as a message. For example, this error may imply that parameters are invalid, or that properly constructed structures were allocated incorrectly, such as when an incorrect allocator function has been used. For more information, see the MAPI Programmer's Reference.

Based on the information returned to you with this error code, you can devise a strategy for finding and fixing the error. One possibility is to use the message store viewer to inspect the objects involved. This tool provides a representation of any object in the information store, shown in a way that accurately depicts its programmatic elements. It may help you find and fix a problem with an incorrect object parameter.


Checking Error Returns

When an error is returned, checking the error code can save time, even if the error seems obvious. For example, an error returned from MAPIAllocate_Buffer would seem to indicate insufficient memory, but actually this could be caused by several different problems, including an invalid parameter in the call. Checking the exact error returned is important.

Windows NT Server, OLE, MAPI, and Microsoft Exchange Server use a unified error structure, which means their error codes are defined in the same format.

  • Windows NT Server and OLE error codes are defined in the WINERROR.H header file.
  • MAPI error codes are defined in MAPICODE.H.
  • Microsoft Exchange Server error codes are defined in the EDKCODE.H header file.

In these error codes, the first four bytes are the facility code. The final four bytes identify a specific error. Most common Windows NT Server error codes are between 0 and hex 100. MAPI error codes start at hex 0102 (0xnnnn0102). For a description of how these 32-bit error codes are built and the macros used to construct them, see the MAPICODE.H header file.

You can usually find the error code by searching for the final four digits in the previously listed header files. If the search turns up more than one match, check the facility code to determine which component generated the error. First check the Microsoft Exchange Server codes for a match, then the MAPI codes, and finally the Windows NT Server codes.

A given error code can be returned by more than one component, such as both Windows NT Server and MAPI. In general, if a MAPI function returns the error, MAPI generated the error. If the MAPI function is simply passing through an error from a call MAPI made to Windows NT Server, the facility code usually identifies the error as one generated by Windows NT Server.

Microsoft Exchange Server functions also return HRESULTs. For information on these functions and their return values, see Functions.


Using a DEBUG Version of MAPI

By default, the RETAIL version of MAPI is installed on your development computer. You can replace the standard DLLs with the DEBUG version of the MAPI DLLs, which are located on the distribution medium. Installing the DEBUG MAPI DLLs changes the behavior of your MAPI-compliant application so that it displays asserts for many different conditions, and provides other valuable testing information.

The volume of output produced by the DEBUG version of MAPI can be alarming, especially if you apply it to a function that already runs smoothly. The MAPI DEBUG version will point out obscure problems that may not have previously appeared, such as memory leaks. It points out MAPI objects that have not been freed, and memory that was allocated but not released. This internal method is more specific than most outside memory checkers.

Please note that the steps for installing DEBUG MAPI DLLs on Windows NT Server differ from those used for Windows 95.

To install debug MAPI DLLs for Windows NT Server
  1. Change to the debug MAPI DLL directory on the distribution medium drive:

    CD MSTOOLS\MAPI\WINNTRT\CHECKED

  2. Copy the files into the SYSTEM32 directory:

    COPY *.* C:\WINNT\SYSTEM32

To install debug MAPI DLLs for Windows 95
  1. Change to the following directory on the development computer:

    CD C:\MSTOOLS\BIN

  2. Run the N2D (normal-to-debug) batch file with no switches set:

    Type N2D

When you no longer need to test your application by running it with MAPI debug DLLs, you can reinstall the nondebug version.

You can reinstall standard MAPI DLLs from the \\MSTOOLS\MAPI\WINNTRT directory. These files have the same names as their debug counterparts in the MSTOOLS\MAPI\WINNTRT\CHECKED directory.

To simplify this task, you can write a batch file to copy the files.

To reinstall nondebug MAPI DLLs for Windows NT Server
  1. To use a batch file, enter the following lines into a text file, designating the distribution medium in the first line:

    CD MSTOOLS\MAPI\WINNTRT\CHECKED

    FOR %%F IN (*.*) DO:

    COPY ..\%%F C:\WINNT\SYSTEM32

  2. Run this file by typing its name at the command line.
  3. Save this file and use it if you need to reinstall the nondebug MAPI DLLs.

It is not necessary to use a batch file. You can enter these commands at a command prompt instead. Type the following :

FOR %F IN (*.*) DO COPY ..\%F C:\WINNT\SYSTEM32

Reinstalling MAPI DLLs for Windows 95 can also be done from a batch file or from the command line.

To reinstall nondebug MAPI DLLs for Windows 95
  1. Change to the following directory on the development computer:

    CD C:\MSTOOLS\BIN

    This assumes that the MSTOOLS directory has been installed on the C drive.

  2. Run the D2N (debug-to-normal) batch file with no switches set:

    Type D2N

Setting Values in MAPIDBG.INI

The MAPI DEBUG DLLs and their behavior are controlled by the MAPIDBG.INI file. For Windows NT Server, this file is located in the %SYSTEMROOT% directory. For Windows 95, it is located in the %WINDR% directory.

Changing DEBUG MAPI DLL Behavior

You can change the behavior of the DEBUG DLLs. For example, you can modify the VirtualMemory DLL tag, the AssertLeaks or DumpLeaks DLL settings, and the FillMemory and FillByte DLL settings.

If set to 1, the VirtualMemory tag allocates memory and alerts you to memory overruns. If you do overrun memory, it will usually cause a general protection fault rather than allow random overrunning. The VirtualMemory tag clearly shows overrunning because memory is allocated in distinct blocks away from other allocations, and adjoining pages will also be protected. Do not use this setting in a nondebug environment. It is useful only for testing and debugging.

The AssertLeaks or DumpLeaks settings display message boxes that describe memory leaks, as well as MAPI objects that have not been freed. They also describe MAPI memory that is allocated but not freed when your application closes.

When you allocate or free memory, you can turn on memory fills using the FillMemory and FillByte settings. This allows you to clearly see what memory is freed or initialized.

You can set the following values in the MAPIDBG.INI file:

[General]
DebugTrace=<0/1>
AssertLeaks=<0/1>
AssertBadBlocks=<0/1>           ;Default is on.
VirtualMemory=<0/1/4>
MemoryFillRandom=<0/1>
CheckHeapOften=<0/1>
EventLog=<0/1>
VerboseSpooling=<0/1>
LowPrioritySpooling=<0/1>       ;Default is on.
[Memory Management]
VirtualMemory=<0/1/4>
AssertLeaks=<0/1>
DumpLeaks=<0/1>
FillMemory=<0/1>
FillByte=<0xNN>                 ;Where NN is some hex number.
SharedMemMaxSize=<# of bytes>   ;0 is default. Grow as big as necessary.
[MAPIX]
FlushRegistry=<0/1>             ;0 is default
[Remoting]
TraceCalls=<0/1>


Using the Raw Properties Screen

The Raw Properties screen is part of the Microsoft Exchange Server Administrator program. By setting data in the Raw Properties screen, you can establish values as they would be set by components you have not yet developed. Data is normally set and manipulated by your application or its setup program, and data is passed from one component to the next. Establishing this artificial environment allows you to test them while they are being developed. For example, you could debug an extension DLL by changing the underlying data.

To view the Raw Properties screen, select any object and choose Raw Properties from the File menu. Note that the Raw Properties screen is available only if you start the Administrator program with the /raw switch set.


Using Track Message

The Track Message tool is part of the Microsoft Exchange Server Administrator program. You can use it to debug applications that track the flow of messages. This utility determines the origin and destination of messages as they are processed by your application. To open the Track Message utility, select the Track Message option from the Tools menu in the Administrator program.


Using the Message Store Viewer

The message store viewer (MDBVU32.EXE) is a MAPI client application that helps you debug your application by providing a view of information in a mailbox or any other object in an information store. This application displays the following information:

  • A message or any other object in the exact format you will use in your application.
  • A message as a set of properties and a collection of calls that can be performed on that object.
  • A log of each MAPI action that has been performed against this object.
  • Nested elements, such as attachments, and allows you to view them separately.

The message store viewer can be used to set and change properties, as well as view them. This is useful if you are writing a message-processing application. The message store viewer shows which properties are available on each message, how you can use them, and in what format they will appear.

The message store viewer can also be used to debug messages. If you can successfully save a message but submitting it fails, you can save the message and look at all its properties with the message store viewer. This is far more efficient than writing code to dump the message's properties.

Displaying a Folder Using the Message Store Viewer

Follow these steps from the message store viewer menu to display a folder in a mailbox. The example displays the root folder of a gateway's mailbox:

To display a folder using the message store viewer
  1. From the Session menu, choose MAPILogonEx if this option has not been chosen for you automatically.
  2. Choose Profile. Unless you specified the MAPI_NEW_SESSION flag, select the profile your application uses to log on. If you are already logged on, this step is unnecessary.
  3. From the MDB menu, choose OpenMessageStore. Use this option to select the store provider to be opened from among those configured in your profile. Although a user's profile may contain the public store, the private store, and zero or more personal folders, only one choice may be available for a server application that uses only the Microsoft Exchange Server private server. Choose Open from the Public Folders menu to view the public information store.
  4. From the MDB menu, choose Open Root Folder or Open IPM Subtree. The Open IPM Subtree option is not available for gateways because a gateway object does not contain an IPM Subtree. Once you have opened the Root Folder, a screen such as the following is displayed:

View of a gateway's root folder using the message store viewer

The preceding screen shows the root folder of a gateway's mailbox. You can now view the contents of other folders in the gateway's mailbox. For example, to view the gateway's inbox, double-click MTS-IN in the Child Folders list box.

The Properties window shows which properties are set on the object. At the top of the Properties window, you may see properties that are numbered instead of labeled with property tags. These properties are customized by each provider, which in this case is the Microsoft Exchange Server store provider. Look in the header file for specific information on these properties. Custom properties for the Microsoft Exchange Server information store are defined in the EDKMDB.H file. Custom properties for the Microsoft Exchange Server directory are defined in the EMSABTAG.H file. Standard MAPI properties are identified by name rather than number.

If you're processing messages, the message store viewer displays the message's exact appearance and properties. For instance, the utility will show you that a delivery report or nondelivery report differ in appearance and, therefore, have a different set of properties than a regular message.


Directory Operations

The Microsoft Exchange Server directory contains information about mailboxes, distribution lists, servers, processes, and applications. It provides a unified, structured view of all users and resources within the Microsoft Exchange Server system. For more information about the structure and characteristics of the directory, see About the Directory.

The directory schema is the description of all the object classes and objects within a directory together with with their attributes and inheritance structure. For more information, see About the Directory Schema.

For information on the security model used in the Microsoft Exchange Server directory, see About Directory Security.

The Microsoft Exchange Server directory can share its object addressing and configuration information with other mail systems. Several methods are available to transfer directory information between Microsoft Exchange Server organizations and foreign systems. For more information, see Sharing Directory Information.


Working with the Directory

Two sets of functions and one Internet protocol are available for working with Microsoft Exchange Server directory objects:

  • Directory access functions The directory access functions are specific to Microsoft Exchange Server. Applications that use directory access functions run on Windows NT Server computers on which the Microsoft Exchange Server Administrator program is installed. They are not available to Windows 95 clients. You can use directory access functions to create, manipulate, delete, export, and import directory objects. You can also use them to move user information from Windows NT Server and Novell NetWare accounts into the Microsoft Exchange Server directory. For more information, see Using Directory Access Functions.
  • MAPI The MAPI address book interface can be used to perform many of the same tasks that you can perform with the directory access functions. Because MAPI is independent of the underlying directory service, your application will work with any MAPI-compliant directory service. For more information, see Using MAPI with Directory Objects.
  • LDAP You can also access the directory through the LDAP protocol. See Using the LDAP Protocol.

For a comparison of using the first two methods, see Comparing MAPI with Directory Access Functions.


Using Directory Access Functions

The directory access functions combine and automate several maintenance tasks. For example, with a single call, you can create a mailbox object, create and associate a Windows NT account and associate the mailbox object to it, add proxy addresses, assign user privileges, add the mailbox to distribution lists, and set its other attributes.

Several groups of functions and structures are often used together to perform a single task or a group of tasks. These sets of functions and structures are listed in the following tables, grouped by functionality type.

Functions for Exporting Directory Information

Operation | Purpose | Functions and Structures
Batch export | Exports objects from the directory. Exported data is defined by members of the BEXPORT_PARMS structure. | BEXPORT_PARMS BatchExport DAPI_FNErrorCallback DAPI_FNExportEntry
Line export | Exports individual objects from the directory. | DAPIStart DAPIRead DAPIEnd
Get configuration information | Returns configuration information about the site associated with the active server. | SITE_INFO DAPIGetSiteInfo

Functions for Importing Directory Information

Operation | Purpose | Functions and Structures
Batch import | Imports objects specified in an import file into the directory. | BIMPORT_PARMS BatchImport
Line import | Imports individual objects supplied by the caller into the directory. | DAPIStart DAPIWrite DAPIEnd

Functions for Extracting Windows NT Server User Accounts

Operation | Purpose | Functions and Structures
Windows NT Server export interface | Exports multiple objects to an import file by reading a list of users from a Windows NT Server database. The resulting import file can then be used by batch import. | NTEXPORT_PARMS NTExport

Functions for Extracting Novell NetWare User Accounts

Operation | Purpose | Functions and Structures
Novell NetWare export interface | Exports multiple objects to an import file by reading a list of users from a NetWare server. The resulting import file can then be used by batch import. | NWEXPORT_PARMS NWExport

Functions for Performing Administrative Tasks

Operation | Purpose | Functions and Structures
Progress display | Controls display of the progress of an ongoing operation. | CALLBACKPROGRESS EndProgressProc InitProgressProc ResetProgressProc UpdateProgressProc UpdateProgressTextProc
Error handling | Controls the interpretation, display, and handling of error events. | DAPI_EVENT
Preinitialization | Loads the directory schema in a background process. If, for example, your application needs to gather information from the user, this function allows you to load the schema as a background process while the user is typing, so that processing can begin as soon as the user is finished. | SchemaPreload


Files Used with Directory Access Functions

The following header files provide directory access functionality.

Directory Access Files

File | Description
DAPI.H | Contains structure and function declarations.
DAPI.LIB | Contains export library that modules must link to in order to use directory access functions.
DAPI.DLL | Contains directory access functions.
DAPIMSG.H | Contains the output from the message compiler, which are the error and warning codes that directory access functions work with. These are string resources in DAPI.DLL.


Sample Applications Using Directory Access Functions

Several sample applications included with the Microsoft Exchange Server SDK use the directory access functions. Observing the code in these applications shows how to use the directory access functions. Because these sample applications are functional, you can also use them as they are or program new functionality into them. They include the following:

  • DIRSYNC: Importing and Exporting Mailboxes Uses the directory access functions to transfer address and other information between foreign systems and Microsoft Exchange Server.
  • DSEXPORT: Exporting Directory Objects Exports objects into a file, using command-line parameters.
  • DSIMPORT: Importing Directory Objects Imports objects from a file, using command-line parameters.


Importing and Exporting with Directory Access Functions

The most basic directory operations can be performed by calling the BatchImport or BatchExport functions, specifying a minimum amount of information, and using default settings.

Note The most important task when using directory access functions is to set the parameters used in function calls, such as the BEXPORT_PARMS structure used with the BatchExport function. For more information, see Structures.

To invoke a basic export operation
  1. Export selected objects into a file using the BatchExport function. Designate the export file by setting the pszExportFile member of the BEXPORT_PARMS structure, which is the only parameter to BatchExport. In this file, you can use a header line that indicates which attributes to export and that will be read by the export function call. This function then exports its data to the export file by overwriting its contents, if any. The header line is preserved. In other words, the BatchExport function both reads from and writes to the export file.
  2. Designate the location in the directory information tree (DIT) from which objects are to be exported by specifying the basepoint container (with the pszBasePoint member and the pszContainer member) and the server (with pszServerName). See Controlling Export with BasePoint, Container, and Export Flags.

You can perform more complex export operations and tailor them to your specific needs, whether you are exporting every recipient in the DIT or a single object. You extend the capabilities of the directory access functions by setting values for control flags — an array of flags that comprise the dwFlags member. You can also assign values to other fields in the BEXPORT_PARMS structure. Some of these options are listed here:

  • Export data back to your application instead of a file by using export callbacks. To do this, specify the callback function in the pfnExportEntry member of the ExportCallback structure (of type EXPORT_CALLBACK), which is passed to BatchExport in BEXPORT_PARMS. This mechanism overrides the default behavior, which is to write the exported data to a file. For more information on callback functions, see Using Directory Access Callback Functions.
  • Specify attributes to be exported programmatically in the pAttributes member instead of reading them from a file.
  • Perform error handling with the error callback mechanism and the ErrorCallback member.
  • Enable progress display with the progress callback mechanism and the ProgressCallBacks member.
  • Restrict the export to classes of objects that you specify in the rgpszClasses member.
  • Restrict the export to changed objects, specified with ulUSNBase. This restriction uses update sequence numbers (USNs), which are explained in Exporting and Importing Changed Objects.
  • Export a single object by defining an empty string for the pszParentContainer member and setting the DAPI_EXPORT_BASEPOINT_ONLY flag. Refer to the pszParentContainer and pszBasePoint members, and the DAPI_EXPORT_BASEPOINT_ONLY flag.

In some cases, you need to combine the use of a parameter with a specific flag. For example, pass in a value for ulUSNBase to restrict an export to objects that have changed.

You can also fine-tune import operations. Here are several examples:

  • Import a single object using the DAPIWrite function. This operation allows you to create, modify, or delete an object in the DIT.
  • Use an existing mailbox to provide default attributes when importing new mailboxes. Do this by setting the pszCreateTemplate member to the distinguished name (DN) of the template mailbox. Refer to the pszCreateTemplate parameter, and see Using Template Objects.
  • Configure the directory import system to automatically create a new Windows NT Server account when it imports a new recipient. Do this by setting the DAPI_CREATE_NT_ACCOUNT flag when calling either the BatchImport or the DAPIStart function. See Creating an Associated Windows NT Account. You can also associate this new recipient with an existing Windows NT Server account.

Note Characters used in a distinguished name (DN) or in any string used to build a DN (such as pszBasePoint and pszContainer) must be in the 0x0020 to 0x007E range. Any characters outside this range are first mapped to ANSI. DNs are further mapped to 7-bit ASCII characters. When a function such as DAPIWrite has to map characters, it returns a warning.


Using Directory Access Callback Functions

Certain directory access functions let you use callback functions, which provide added control. For example, an application can receive exported data directly instead of having the data exported to a file on the disk. To do this, the application specifies an export callback function when the BatchExport function is called. When the BatchExport function executes, it calls the callback function once for each entry it exports, passing it a pointer to the exported data. This functionality lets you use the BatchExport function for line-by-line exporting.

The three different kinds of callback functions are specified in the parameters passed in calls to export functions. For example, the BatchExport function takes one parameter, lpBexportParms (a pointer to a BEXPORT_PARMS structure), which contains parameters for directory export operations. BEXPORT_PARMS contains all three fields used to specify callback functions. If the pointer to the callback structure is left NULL, default behavior — described for each callback in this list — is invoked.

  • The ProgressCallBacks structure contains pointers to functions used to display the progress of the export operation. When the BatchExport function finishes executing an atomic export operation, it calls one or more of the progress callback functions, which, for example, can increment a counter or otherwise display progress information. Default behavior means that BatchExport displays progress information in a standard progress dialog box.
  • The ErrorCallback structure holds the address of a function to be called for each error encountered. Default behavior means that BatchExport writes errors to the Windows NT event log.
  • The ExportCallback structure holds the address of a function that is called once for each entry exported from the directory. When BatchExport calls this function, it passes a pointer to the exported data. Default behavior means that BatchExport exports data into an export file indicated by pszExportFile.

The NTExport and NWExport functions are used to export user accounts from Windows NT and Novell NetWare Servers respectively, so that that this data can later be imported into a Microsoft Exchange Server directory. These two functions are called in order with the NTEXPORT_PARMS and NWEXPORT_PARMS structures acting as parameters. These structures in turn contain the ProgressCallBacks and ErrorCallback members, as well as the ExportCallback member, which is used to point to an export callback function.

Callbacks can also be used when importing data. The BIMPORT_PARMS structure (which contains the ProgressCallBacks and ErrorCallback members) is used as a parameter for the BatchImport function. In this case, the appropriate functions specified in ProgressCallBacks are called each time a line is imported from the import file.


Exporting Objects

With directory access functions, you can write programs that export directory objects into an export file or retrieve information about objects into a structure. A typical use for an export file is synchronizing directories between a Microsoft Exchange Server site and a directory of a different type (such as a foreign mail system or a database). Directory data is exported from Microsoft Exchange Server into the file, which can then be delivered to the foreign system and imported by an application designed for that purpose.

The following illustration shows how data can be exported by generating an export file using the appropriate directory access functions.

Generating an export file using directory access functions

The directory access functions used for exporting enable you to export any attribute in the directory schema. Attributes to be exported are specified either with the pAttributes parameter and the DAPI_ENTRY structure, or as the first line of the export file.

The two primary functions used for exporting data are BatchExport and DAPIRead. With a call to BatchExport, data can be exported into an export file or retrieved into a structure; with DAPIRead, data can be retrieved only into a DAPI_ENTRY structure.

For information on exporting data into export files, see Using Export Files with BatchExport and Directory Access Function Files. For information on exporting data into structures, see Initializing Export Structures, Exporting Column Headers and Attribute Values, Choosing an Export Format, and Interpreting Exported Data.


Using Export Files with BatchExport

A call to the BatchExport function can specify an export file. If this file already exists, BatchExport overwrites the file. It also backs up the file if the DAPI_SUPPRESS_ARCHIVES flag is not set.

Attribute names specified in the file header are used only if pAttributes is NULL.

These guidelines for using export files are summarized in the following illustrations. The default set of attributes referred to in these illustrations is explained in Default Set of Export Attributes.

How BatchExport determines attributes to export

If pAttributes is NULL, the call to BatchExport exports attributes read from the first line in the export file. This file is not recognized as valid if the first line is not a valid sequence of attributes. In this case, BatchExport sets an error condition and either displays an error dialog box or calls the custom error handler if one is supplied, then overwrites the existing export file.


Default Set of Export Attributes

BatchExport exports a default set of attributes if:

  • You specify no attributes to export.
  • The pAttributes field is NULL.
  • Attributes cannot be determined through the header line of the specified export file.

The following export file shows these default export attributes used in an export operation. The header line lists the export attributes, and the following lines are two exported objects and their attributes:

Obj-Class,First Name,Last name,Display Name,Alias Name,Directory Name,
Primary Windows NT Account,Home-Server,E-mail address,
E-mail Addresses,Members,Obj-Container,Hide from AB
Mailbox,3,,3,3,3,ALLISON'S\3,A-ALLISONP2,,
MS:MICROSOFT/ALLISON2/3%SMTP:3@Allison2.Microsoft.com%X400:c=US;a= ;p=Microsoft;o=Allison2;s=3;
,,Recipients,
Remote,11,,11,11,11,,,SMTP:1@EX.COM,
MS:MICROSOFT/JEFFREY2/11%X400:c=US;a= ;p=Microsoft;o=Jeffrey2;s=11;%SMTP:1@EX.COM
,,Recipients,


Finding an Object in the Directory

To find an object in the directory, you can either use the DAPIWrite or BatchImport directory access function, or you can use the MAPI address book interface.

To add a directory object using DAPIWrite

Call the DAPIWrite directory access function. Pass DAPI_WRITE_CREATE in the dwFlags parameter to indicate you want to create an object. (If the object already exists, the call to DAPIWrite fails.) In the pAttributes and pValues parameters, pass pointers to DAPI_ENTRY structures that contain the names of attributes to be written to the directory and the values for those attributes, respectively.

To add a directory object using BatchImport

Call the BatchImport directory access function and specify an import file in the pszImportFile member of the BIMPORT_PARMS structure.

To find a directory object using MAPI functions
  1. Find the Global Address List.
  2. Call IMAPITable::Restrict on the Global Address List. To do this, you first build a restriction structure, specifying the properties you know about the object you want to find. You could, for example, include the Display-Name of the object in this restriction structure. This call returns a handle to a table, and an IMAPITable interface.
  3. Call IMAPITable::FindRows to find the specific row representing the object you want to find. The columns in the table correspond to the properties of the object, one of which is its entry identifier. You can then read this entry identifier and use it later to open the object.


Selecting Objects to Export

Although directory access functions do not provide generic filtering capabilities, you can use them to select objects (by query) to be exported from the directory, through the BatchExport function. To do this, you specify up to three attributes and the values they must contain for the object to be exported. These three attributes can be used as filtering criteria:

  • USN-Changed This sequential number indicates when the object was updated relative to other objects on the server. Filtering by this number allows all objects whose USN-Changed is greater than the specified number to be exported. In the BatchExport function call, this attribute is specified in ulUSNBase.
  • Object-Class Filtering by object class means exporting only recipients, only distribution lists, only containers, and so on. You can filter by any object class (or combination of classes) in the schema. Objects of different classes are exported in the order you specify. This fact is useful later when the order in which objects are imported may be significant. For example, you wouldn't want to export mailboxes and their containers, and then later import the mailboxes before importing their containers. In a call to the BatchExport function, this attribute is specified in the rgpszClasses parameter.
  • Home-Server Designates the home server of the object. The BatchExport function first looks for the distinguished name (DN) of a site in the pszHomeServer member of the BEXPORT_PARMS structure passed in the BatchExport call. If no site is specified in pszHomeServer, the site name is sought in the DN passed in the pszBasePoint member. If pszBasePoint also does not contain a site, the site name is taken from the DN of the server on which the export process is running.

Note Home-Server is a pseudo-attribute, which means it is not part of the directory schema, and can be used only by directory access functions. It was created so that you can define a list of servers for filtering the export operation, the same way you can filter changes by their relative update order with USN-Changed. For more information, see Using Directory Access Pseudo-Attributes.

The BatchExport function exports objects in all classes you specify. The export operation is then restricted by applying the USN-Changed and Home-Server filters. The BatchExport function does not let you filter objects with other attributes such as When-Changed and When-Created.

However, by providing a callback function you can do specialized filtering. Because data is passed to your callback function when it is called, you can filter on any criteria you want. You can then use those criteria to decide how to use the exported data, such as whether to write it to a file. Filtering objects or attributes in this manner involves overhead in reading the data from the directory information tree.

Importing objects does not involve filtering. All objects specified in the import file are imported.


Using Flags with Directory Access Functions

All the flags you can use with the directory access functions to control export and import operations are described in the following tables. The first table provides descriptions for all flags used with directory access functions, and the subsequent tables (Flags Used with Directory Access Batch Functions and Flags Used with Directory Access Non-Batch Functions) specify which functions each flag is used with.

DAPI_EVENT_MASK and DAPI_WRITE_MODE_MASK are not flags as such, but as masks used for determining the opcode for event filtering and write operations, respectively.

Directory Access Flag Descriptions

Flag | Value | Description
DAPI_EVENT_MASK | 0x00000007 | Bit-field containing event-filtering requested. If none of these bits are set, DAPI_EVENT_ALL is assumed.
DAPI_EVENT_MIN | 0x00000001 | Logs start and stop messages. No warning or error logging.
DAPI_EVENT_SOME | 0x00000002 | Logs start, stop, and error messages.
DAPI_EVENT_ALL | 0x00000004 | Logs start, stop, error, and warning messages.
DAPI_FORCE_SCHEMA_LOAD | 0x00000010 | Unloads previously loaded schema and rereads the schema. Default action is to use the cached schema if read from the same messaging domain.
DAPI_RAW_MODE | 0x00000020 | Imports or exports in raw mode, which means that import lines are taken literally. No attributes are inherited or constructed. Aliases for attribute and class names are not recognized.
DAPI_OVERRIDE_CONTAINER | 0x00000040 | The container specified in the parameter block overrides the contents of the container column. Default behavior is for the value specified in the Obj-Container column to override that specified in the parameter block.
DAPI_MODIFY_REPLACE_PROPERTIES | 0x00800000 | Causes existing data to be overwritten.
Flags Defined for Batch Operations Only (Ignored by DAPIRead and DAPIWrite) | Value | Description
DAPI_IMPORT_NO_ERR_FILE | 0x00000080 | Does not create an error file (applies only to the BatchImport function).
DAPI_YES_TO_ALL | 0x00000100 | Forces Yes response on any user-prompt question. For example: continue without proxy addresses.
DAPI_SUPPRESS_PROGRESS | 0x00000200 | Suppresses the display of progress thermometer on batch operations. The default is to display progress.
DAPI_SUPPRESS_COMPLETION | 0x00000400 | Suppresses the completion notification message box on batch operations.
DAPI_SUPPRESS_ARCHIVES | 0x00000800 | Suppresses the creation of archive copies of output files. Applies only to the BatchImport and BatchExport functions.
DAPI_IMPORT_WRITE_THROUGH | 0x00400000 | Commits write operations immediately. Lazy-commit only is applied in BatchImport, so that we can guarantee a flush on the last item.
Flags Defined for BatchExport | Value | Description
DAPI_EXPORT_MAILBOX | 0x00001000 | Exports mailbox recipients.
DAPI_EXPORT_CUSTOM | 0x00002000 | Exports remote address recipients.
DAPI_EXPORT_DIST_LIST | 0x00004000 | Exports distribution lists.
DAPI_EXPORT_RECIPIENTS | 0x00007000 | Exports all recipient objects.
DAPI_EXPORT_ALL_CLASSES | 0x00008000 | Exports objects of all classes.
DAPI_EXPORT_HIDDEN | 0x00010000 | Includes hidden objects in export. Default is no export if Hide-From-Address-Book is set.
DAPI_EXPORT_SUBTREE | 0x00020000 | Makes the export operation recursive to lower levels of the directory information tree.
DAPI_EXPORT_BASEPOINT_ONLY | 0x00040000 | Exports only the requested attributes from the named BasePoint object. All other export restrictions are ignored (class flags, rgpszClasses, pExportFilter, pszServerName). This flag implies IMPORT_SUPRESS_PROGRESS and IMPORT_SUPRESS_COMPLETION
Flags Defined for DAPIRead | Value | Description
DAPI_READ_DEFINED_ATTRIBUTES | 0x00100000 | Returns all attributes that are set for the current object. See Note 1 in Table Notes below for precedence with respect to pAttributes.
DAPI_READ_ALL_ATTRIBUTES | 0x00200000 | Returns all attributes that are defined for the class of the current object. If set, pAttributes is ignored. See Note 1 in Table Notes below for precedence with respect to pAttributes.
Flags That Control Windows NT Server Security Management | Value | Description
DAPI_RESTRICT_ACCESS | 0x01000000 | Applies a Windows NT security descriptor to created objects.
DAPI_CREATE_NT_ACCOUNT | 0x02000000 | Creates Windows NT accounts (valid only in Create/Modify mode).
DAPI_CREATE_RANDOM_PASSWORD | 0x04000000 | Generates random passwords for created Windows NT accounts. Ignored if the DAPI_CREATE_NT_ACCOUNT flag is not set.
DAPI_DELETE_NT_ACCOUNT | 0x08000000 | Deletes ASSOC-NT-ACCOUNT when deleting mailbox.
Flags Defined for DAPIWrite | Value | Description
DAPI_WRITE_UPDATE | 0x10000000 | Default. Modifies if the object exists, creates if it doesn't.
DAPI_WRITE_CREATE | 0x20000000 | Creates object; fails if the object exists.
DAPI_WRITE_MODIFY | 0x30000000 | Modifies object; fail if the object does not exist.
DAPI_WRITE_DELETE | 0x40000000 | Deletes the object.
DAPI_WRITE_MODE_MASK | 0x70000000 | A mask used to determine the exact mode setting specified. Combining dwFlags and this flag yields the mode opcode.

Flags Used with Directory Access Batch Functions

The following table lists the flags used with directory access batch functions NTExport, NWExport, BatchImport, and BatchExport. If you can specify a certain flag in a call to a given function, an x appears in the cell where the flag's row and the function's column intersect.

Directory Access Flags and Associated Functions (Batch Functions)

General Directory Access Flags | NT Export | NW Export | Batch Import | Batch Export
DAPI_EVENT_MIN | x | x | x | x
DAPI_EVENT_SOME | x | x | x | x
DAPI_EVENT_ALL | x | x | x | x
DAPI_FORCE_SCHEMA_LOAD |  |  | x | x
DAPI_RAW_MODE |  |  | x | x
DAPI_OVERRIDE_CONTAINER |  |  | x |
DAPI_IMPORT_NO_ERR_FILE |  |  | x |
DAPI_IMPORT_WRITE_THROUGH |  |  | x |
DAPI_MODIFY_REPLACE_PROPERTIES |  |  | x |
Flags Defined for Batch Operations Only | NT Export | NW Export | Batch Import | Batch Export
DAPI_YES_TO_ALL |  |  | x |
DAPI_SUPPRESS_PROGRESS | x | x | x | x
DAPI_SUPPRESS_COMPLETION | x | x | x | x
DAPI_SUPPRESS_ARCHIVES |  |  | x | x
Flags Defined for BatchExport | NT Export | NW Export | Batch Import | Batch Export
DAPI_EXPORT_MAILBOX |  |  |  | x
DAPI_EXPORT_CUSTOM |  |  |  | x
DAPI_EXPORT_DIST_LIST |  |  |  | x
DAPI_EXPORT_RECIPIENTS |  |  |  | x
DAPI_EXPORT_ALL_CLASSES |  |  |  | x
DAPI_EXPORT_HIDDEN |  |  |  | x
DAPI_EXPORT_SUBTREE |  |  |  | x
DAPI_EXPORT_BASEPOINT_ONLY |  |  |  | x
Flags Used to Control Windows NT Server Security Management | NT Export | NW Export | Batch Import | Batch Export
DAPI_RESTRICT_ACCESS |  |  | x |
DAPI_CREATE_NT_ACCOUNT |  |  | x |
DAPI_CREATE_RANDOM_PASSWORD |  |  | x |
DAPI_DELETE_NT_ACCOUNT |  |  | x |

Flags Used with Directory Access Non-Batch Functions

The following table lists the flags used with directory access non-batch functions DAPIStart, DAPIRead, DAPIWrite, and SchemaPreload. Currently, no flags are used with the DAPIGetSiteInfo function.

If you can specify a certain flag in a call to a given function, an x appears in the cell where the flag's row and the function's column intersect.

Directory Access Flags and Associated Functions (Non-Batch Functions)

General Directory Access Flags DAPI
Start 		DAPI
Read 		DAPI
Write 		Schema
Preload
DAPI_EVENT_MIN | x
DAPI_EVENT_SOME | x
DAPI_EVENT_ALL | x
DAPI_FORCE_SCHEMA_LOAD | x | x
DAPI_RAW_MODE | x | x
DAPI_OVERRIDE_CONTAINER | x
DAPI_MODIFY_REPLACE_PROPERTIES

 x 2 x
Flags Defined for DAPIRead DAPI
Start 		DAPI
Read 		DAPI
Write 		Schema
Preload
DAPI_READ_DEFINED_ATTRIBUTES | x 1 | x 1
DAPI_READ_ALL_ATTRIBUTES

 x 1 x 1
Flags Used to Control Windows NT Server Security Management DAPI
Start 		DAPI
Read 		DAPI
Write 		Schema
Preload
DAPI_RESTRICT_ACCESS | x 2 | x
DAPI_CREATE_NT_ACCOUNT | x 2,3 | x
DAPI_CREATE_RANDOM_PASSWORD | x 2 | x
DAPI_DELETE_NT_ACCOUNT

 x 2 x
Flags Defined for DAPIWrite DAPI
Start 		DAPI
Read 		DAPI
Write 		Schema
Preload
DAPI_WRITE_UPDATE | x
DAPI_WRITE_CREATE | x
DAPI_WRITE_MODIFY | x
DAPI_WRITE_DELETE | x

Table Notes:

1. A precedence level is defined for determining the set of attributes to export. This is the precedence order, from highest to lowest:

· pAttributes passed in the call to the DAPIRead function.

· pAttributes passed on the call to the DAPIStart function.

· If DAPI_READ_ALL_ATTRIBUTES is set in the call to either the DAPIRead function or the DAPIStart function, all attributes are exported. If DAPI_READ_DEFINED_ATTRIBUTES is set in both function calls, while DAPI_READ_ALL_ATTRIBUTES is not set in either, DAPI_READ_DEFINED_ATTRIBUTES takes precedence.

2. If set on DAPIStart, these flags may NOT be disabled on individual DAPIWrite calls.

3. DAPI_CREATE_NT_ACCOUNT implies DAPI_RESTRICT_ACCESS.


Controlling Export with BasePoint, Container, and Export Flags

To specify a location from which directory objects are to be exported with the BatchExport function, use the pszBasePoint and pszContainer members of the BEXPORT_PARMS structure as follows:

  • pszBasePoint Indicates the distinguished name (DN) of the messaging site or container that serves as the directory information tree (DIT) basepoint for export operations. The basepoint is the location in the DIT under which the calling application performs directory operations. A DN is the combination of an object's path and name in the hierarchical naming structure. Two examples of DNs are:
    /o=MyOrg/ou=MySite/cn=Recipients/cn=Me
/o=MyOrg/ou=MySite
  • pszContainer Specifies the container to be used for export operations. This container is below the level of the basepoint, as indicated by pszBasePoint. You can express it in the form of a relative distinguished name (RDN), a DN, or a partially qualified DN.

    An example of an RDN for pszContainer is:

    /cn=Recipients/cn=Me

    If used with the basepoint /o=MyOrg/ou=MySite, the container specified with the RDN /cn=Recipients/cn=Me is:

    /o=MyOrg/ou=MySite/cn=Recipients/cn=Me

    An example of an DN for pszContainer is:

    /o=MyOrg/ou=MySite/cn=Recipients

    If pszContainer is expressed as a DN, pszBasePoint is used if the container is specified on a per-object basis (Obj-Container is specified in the import file or in the structure passed in the pAttributes parameter of DAPIWrite).

    An example of partially qualified DN for pszContainer is:

    Recipients/cn=Subcontainer

    To unambiguously identify the container, the value for pszContainer expressed as a partially qualified DN is combined with the value for pszBasePoint.

If pszBasePoint in BEXPORT_PARMS is NULL, the BatchExport function starts object extraction from the current site object, which is the site where the specified DSA resides. If pszBasePoint in BEXPORT_PARMS is "" (a zero-length string), the BatchExport function uses the current organization object as the basepoint. If pszContainer is NULL, the export operation is executed as if pszContainer has the value of pszBasePoint. These special cases are summed up in the following table.

Export Points for Special Cases of pszBasePoint and pszContainer

Member | Value | Export Point
pszBasePoint | NULL | Site object of the active server.
pszBasePoint | "" | Organization object.
pszContainer | NULL | Treats the basepoint as the default export container (as if pszContainer acquires the value of pszBasePoint).


Setting Export Flags

You can set several flags to indicate the types of objects to be exported and specify further locations in the directory information tree (DIT) from which objects are exported. These flags are set in the dwFlags member of the BEXPORT_PARMS structure, which is passed in the lpBexportParms parameter in the BatchExport function call.

For example, unless the DAPI_EXPORT_BASEPOINT_ONLY flag is set, only objects below the basepoint may be exported. Because the organization is the highest object in a standard Microsoft Exchange Server DIT, it is not possible to export it without setting the DAPI_EXPORT_BASEPOINT_ONLY flag.

Flags Used with BatchExport to Customize Export Operations

Flag | Action
DAPI_EXPORT_MAILBOX | Exports mailbox recipients
DAPI_EXPORT_CUSTOM | Exports remote address recipients
DAPI_EXPORT_DIST_LIST | Exports distribution lists (DL)
DAPI_EXPORT_RECIPIENTS | Exports all recipient objects: DAPI_EXPORT_MAILBOX | DAPI_EXPORT_CUSTOM | DAPI_EXPORT_DIST_LIST
DAPI_EXPORT_HIDDEN | Includes hidden objects in export. The default is no export if Hide-From-Address-Book is set.
DAPI_EXPORT_SUBTREE | Makes the export operation recursive to lower levels of the DIT.
DAPI_EXPORT_ALL_CLASSES | Exports all objects (not only recipient objects).
DAPI_EXPORT_BASEPOINT_ONLY | Exports only the requested attributes from the named basepoint object. All other export restrictions are ignored (class flags, rgpszClasses, pszHomeServer). This flag implies DAPI_SUPPRESS_PROGRESS and DAPI_SUPPRESS_COMPLETION.


Specifying Export Points

The following diagrams show export locations for different settings of the pszBasePoint and pszContainer members of BEXPORT_PARMS, combined with various export flags used in a call to the BatchExport function.

For example, click Export Case 1 to see the export point if pszBasePoint is set to /o=Organization/ou=Site, pszContainer is set to Recipients 1 (a recipients container), and the DAPI_EXPORT_RECIPIENTS flag is set. As indicated in the diagram, this configuration causes BatchExport to export only two users — User 11 and User 12.

BatchExport Example Cases

Export Points | Value of pszBasePoint | Value of pszContainer | Flags Set
Export Case 1 | /o=Organization /ou=Site | Recipients 1 | DAPI_EXPORT_ RECIPIENTS
Export Case 2 | /o=Organization /ou=Site | Recipients 1 | DAPI_EXPORT_ ALL_CLASSES
Export Case 3 | /o=Organization /ou=Site | Recipients 1 | DAPI_EXPORT_ SUBTREE and DAPI_EXPORT_ RECIPIENTS
Export Case 4 | /o=Organization /ou=Site | Recipients 1 | DAPI_EXPORT_ SUBTREE and DAPI_EXPORT_ ALL_CLASSES
Export Case 5 | /o=Organization /ou=Site /cn=Recipients 1 | any value | DAPI_EXPORT_ BASEPOINT_ONLY
Export Case 6 | /o=Organization /ou=Site | NULL | DAPI_EXPORT_ ALL_CLASSES
Export Case 7 | /o=Organization /ou=Site | any value | DAPI_EXPORT_ BASEPOINT_ONLY
Export Case 8 | /o=Organization /ou=Site | NULL | DAPI_EXPORT_ SUBTREE and DAPI_EXPORT_ RECIPIENTS
Export Case 9 | /o=Organization /ou=Site | NULL | DAPI_EXPORT_ SUBTREE and DAPI_EXPORT_ ALL_CLASSES
Export Case 10 | "" | NULL | DAPI_EXPORT_ SUBTREE and DAPI_EXPORT_ ALL_CLASSES


Example: Export Case 1

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = Recipients 1
  • DAPI_EXPORT_RECIPIENTS flag is set.


Example: Export Case 2

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = Recipients 1
  • DAPI_EXPORT_ALL_CLASSES flag is set.


Example: Export Case 3

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = Recipients 1
  • DAPI_EXPORT_SUBTREE and DAPI_EXPORT_RECIPIENTS flags are set.


Example: Export Case 4

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = Recipients 1
  • DAPI_EXPORT_SUBTREE and DAPI_EXPORT_ALL_CLASSES flags are set.


Example: Export Case 5

BatchExport exports data from this point for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site/cn=Recipients 1
  • pszContainer = any value
  • DAPI_EXPORT_BASEPOINT_ONLY flag is set.


Example: Export Case 6

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = NULL
  • DAPI_EXPORT_ALL_CLASSES flag is set.


Example: Export Case 7

BatchExport exports data from this point for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = any value
  • DAPI_EXPORT_BASEPOINT_ONLY flag is set.


Example: Export Case 8

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = NULL
  • DAPI_EXPORT_SUBTREE and DAPI_EXPORT_RECIPIENTS flags are set.


Example: Export Case 9

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = /o=Organization/ou=Site
  • pszContainer = NULL
  • DAPI_EXPORT_SUBTREE and DAPI_EXPORT_ALL_CLASSES flags are set.


Example: Export Case 10

BatchExport exports data from these points for the following settings in the BEXPORT_PARMS structure:

  • pszBasePoint = ""
  • pszContainer = NULL
  • DAPI_EXPORT_SUBTREE and DAPI_EXPORT_ALL_CLASSES flags are set.


Initializing Export Structures

The BEXPORT_PARMS structure that is used as a parameter for the BatchExport function must be initialized to zero before use. You can do this by calling the Win32 ZeroMemory function. By zeroing this structure, you ensure that default processing is invoked for fields that are not filled in. For example, pointers to callback functions need to be nonzero if a callback is to be used. However, BatchExport interprets a zero pointer for an export callback function as a request for it to write to a file. If all the callback functions are zeroed and no export file is specified, the function call returns an error.


Exporting Column Headers and Attribute Values

When BatchExport calls the export callback function, it passes the ExportDataType parameter, which indicates whether the exported item contains column headers or attribute values. ExportDataType has the value EXPORT_HEADER when exporting column headers; ExportDataType has the value EXPORT_ENTRY when exporting actual data.

For each invocation of the BatchExport function, only the first export callback will have the EXPORT_HEADER value. In this callback, the data is to be interpreted as names of attributes, as specified in the first line of the export file. In subsequent callbacks, the value of the ExportDataType parameter is EXPORT_ENTRY, and the data contains values for the attributes. The order of exported attribute values matches the order of attribute names in the first export callback.

For example, you may want the value of the Comment attribute. If the Comment attribute is the sixth entry in the header array, the sixth entry of the value array of subsequent callbacks holds the attribute you want.


Choosing an Export Format

Using a callback function, you can export data in one of three ways:

  • Export data into a line whose items are delimited by commas or another specified character. Set the ulEvalTag control flag in the EXPORT_CALLBACK structure to TEXT_LINE. The data line format is the same as would be used if the data were written to an export file.
  • Export data into an array of structures. Set the ulEvalTag control flag to VALUE_ARRAY. Data is returned in its native type, with a few minor exceptions. For example, any attributes whose native type is object (such as distinguished names or OR names) is returned as a text representation of that object. Also, date fields are returned as UTC string representations of the date. Unsigned integer values are returned as integers.
  • Export data into an array of structures in "textized" format. Set ulEvalTag to TEXT_VALUE_ARRAY. All binary and nonbinary data is exported in string representations. Binary values are exported as strings of hex digits.


Interpreting Exported Data

The following illustration summarizes how to access the data exported to a callback function using the BatchExport function.

Exporting data into struct arrays

If the user has specified that data is to be exported as a value array (by setting ulEvalTag in the EXPORT_CALLBACK structure to VALUE_ARRAY), each attribute is exported as an appropriate data type. Each attribute is described by an ATT_VALUE structure. This structure contains a member variable called DapiType, which indicates the type of the exported value, and a union called Value, which contains the actual data.

The following code shows how DapiType is used to find the data type, and how the Value union is then referenced to access the data.

PATT_VALUE pAttValue = &pExportEntry->rgEntryValues[index];

switch (pAttValue->DapiType)
{
    case DAPI_STRING8:
        printf("%s\n", pAttValue->Value.pszA);
        break;
    case DAPI_UNICODE:
        printf("%S\n", pAttValue->Value.pszW);
        break;
    case DAPI_BINARY:
        printf("Binary data at %08lx\n", pAttValue->Value.lpBinary);
        break;
    case DAPI_INT:
        printf("%d\n", pAttValue->Value.iValue);
        break;
    case DAPI_BOOL:
        printf("%s\n", pAttValue->Value.bool ? "True" : "False");
        break;
    default:
        printf("Invalid DapiType: %d\n", pAttValue->DapiType);
        break;
}

In the preceding code example, index specifies which ATT_VALUE structure element in the array to read. For another example, see the DIRSYNC sample application file in the \BKOFFICE\SAMPLES\EXCHANGE directory.


Example: Using BatchExport

An application executes the BatchExport function to export Mail-Recipient objects. It requests the following attributes for each object: Object-Class, Common-Name, Display-Name, Proxy-Addresses, Members, and Home-Server. Because the Mail-Recipient objects happen to each have three proxy addresses on this server, the Proxy-Addresses attribute will hold multiple values. (Like Proxy-Addresses, the Members attribute is also multivalued, but in this case it has only one value.) Each of the other four requested attributes is single-valued. The structure of the data exported for a given Mail-Recipient object produces one callback and is shown in the following illustration.

Each export returns an array of ATT_VALUE structures

As this illustration shows, the requested attributes are returned in an array. If any of those attributes are multivalued, subsequent values are returned in further ATT_VALUE structures in a linked list. The linked list starts at the initial value of that attribute, which is a part of the ATT_VALUE array pointed to by rgEntryValues.


Lifetime of Values

Ownership of structures is synchronous for BatchExport function calls. When the BatchExport function calls the DAPI_FNExportEntry export callback function, the data in the DAPI_ENTRY structure remains valid only until the calling function returns. This is because the BatchExport function reuses the same structures when it exports data in its next export operation. Therefore, you must either write the data to a file or make a copy of it in memory. You cannot merely reference it with a pointer after returning from the callback.


Importing and Manipulating Objects

You can perform basic data import operations by calling the BatchImport function, specifying a minimum amount of information, and using default settings. This function can read a series of instructions from a file called an import file or import script. These instructions manipulate existing objects in the directory or import new objects into the directory. They are executed in a single bulk operation, with optional line-by-line control.

To execute a simple import operation
  1. Indicate the name of the import file with the pszImportFile member of the BIMPORT_PARMS structure.
  2. Indicate an import destination in the directory information tree (DIT) with the pszBasePoint and pszContainer members of the BIMPORT_PARMS structure.

From this basic operation you can add functionality by specifying additional parameters, setting control flags, or using a template object. Template objects are explained in Using Template Objects.

Instructions in the import script can create new objects in the directory, make changes to existing directory objects and their attributes, or both. Therefore, although the file is called an import file, it can be used to create, update, and delete objects.

Using an import file

An import file is an ASCII text file that contains attributes of objects for the data being imported or manipulated, as well as the data itself. Elements are separated by commas or another character. The file is self-defining, which means that the first line of the file contains the attribute names and the remaining lines contain the data. Any attribute associated with directory objects can be manipulated by directory access functions using an import file. For more information, see Files Used with Directory Access Functions and File Formats.

For each line in an import file, the import functions can perform the following types of actions:

  • Create or delete Microsoft Exchange Server mailboxes within the local site.
  • Create or delete Windows NT domain security accounts.
  • Generate random passwords when accounts are created.
  • Manipulate distribution lists (DL)s.
  • Create custom recipients.

Import files are used only for batch import in association with the BatchImport function. In contrast to BatchImport, the DAPIWrite function uses the pAttributes member as a parameter that is a pointer to a DAPI_ENTRY structure containing names (such as Proxy-Address, Comment, Home-Server, or Display-Name) of attributes to be imported. DAPIWrite also uses the pValues member as a pointer to a DAPI_ENTRY structure containing the actual attribute values to be set on the DIT entry.

Note Multivalued properties can be imported two ways. The imported data can overwrite the existing data, or the new data can be appended to the existing data. This choice is made by setting the DAPI_MODIFY_REPLACE_PROPERTIES control flag in the BIMPORT_PARMS structure, when calling the BatchImport function. Setting this flag causes existing data to be overwritten. In Microsoft Exchange Server version 5.0 (RC1) or later, importing a new value that differs in case from an existing value will replace the old value, regardless of whether you have chosen to append or overwrite.


Importing Multivalued Properties with DAPIWrite

The ulEvalTag member of the DAPI_ENTRY structure determines the way properties are to be imported. For this member, you can pass one of three values: VALUE_ARRAY, TEXT_VALUE_ARRAY, and TEXT_LINE. Their meanings are similar to those described in Choosing an Export Format.

If you pass TEXT_LINE, DAPIWrite expects the rgEntryValues member to be a string containing attribute values separated by the delimiter. If one of these attributes is multivalued, its members are listed together and separated by a different delimiter. The default delimiters are defined in DAPI.H to be commas for separating attributes and percent signs for separating members of a multi-valued attribute.

In the following example string, DLRecip1, DLRecip2, and DLRecip3 are members of a distribution list to be imported:

"DL1,John,Server1,DLRecip1%DLRecip2%DLRecip3,Hello"

If you pass TEXT_VALUE_ARRAY, DAPIWrite expects the rgEntryValues member to point to an array of attribute values (in ATT_VALUE structures) to be imported. If one of these attributes is multivalued, each value must be specified in a separate structure. These structures are linked. In the following illustration, DLRecip1, DLRecip2, and DLRecip3 are members of a distribution list to be imported.

Specifying TEXT_VALUE_ARRAY with DAPIWrite


Using Directory Access Raw Mode

When an import operation is executed with the DAPI_RAW_MODE control flag set, the import function does not use default values or attribute inheritance. If this flag is not set, fields for which no values are supplied are left blank. For example, the three attributes homeDSA, homeMTA, and homeMDB (the directory, MTA, and information store associated with this object) should all be set to the same value, namely the same computer. For safety, the directory access functions used for importing set these attributes to the same value unless the DAPI_RAW_MODE control flag is set. Therefore, you have more flexibility with raw mode, but you must set these values explicitly or unexpected results may occur.


Specifying the Import Mode

The default import files used by directory access functions are comma-separated value (.CSV) files that can be read and written with Microsoft Excel. You can use the second column in the .CSV file to state the mode of the operation: Update, Create, Delete, or Modify. For more information, see the Microsoft Exchange Server Administrator's Guide and Specifying the Import Mode for BatchImport.

The DIRSYNC sample application demonstrates how a completely different file format can be implemented using the directory access functions of the Microsoft Exchange Server SDK. The format is described in DIRSYNC: Importing and Exporting Mailboxes.


Initializing Import Structures

The BIMPORT_PARMS structure used as a parameter for the BatchImport function must be initialized to zero before use. You can do this by calling the Win32 ZeroMemory function. By zeroing this structure, you ensure that default processing is invoked for fields that are not filled in. The following fields must then be filled in:

  • The BatchImport function needs to have an import file specified with the pszImportFile member.
  • Pointers to callback functions need to be nonzero if a callback is to be used.


Deleting Object Attributes

You can delete attributes from objects using the BatchImport or DAPIWrite function. To do this, specify the object class, the name of the object, and use the string ~DEL in the column specified for the attribute. This should not be in quotation marks. If in quotation marks, the value will be taken literally, and the string "~DEL" will be put into that attribute.

For example, the following lines appear in an import file. The first line is the header line. The second line creates or modifies a mailbox. In this example, the attribute Comment is being deleted from the user Steve Masters:

Obj-Class,Common-Name,Given-Name,Surname,Display-Name,Comment
mailbox,SteveMas,Steve,Masters,Steve Masters,~DEL

It is possible to reset the attribute later by running the import operation again and specifying a value. For example, the data line in the following example resets the Comment attribute for this user to the value 'Hello'.

Obj-Class,Common-Name,Given-Name,Surname,Display-Name,Comment
mailbox,SteveMas,Steve,Masters,Steve Masters,Hello

Another use for this functionality is to remove a recipient from all distribution lists for which it is a member. To do this, specify ~DEL in the Members column. If the object you are modifying is a distribution list, specifying ~DEL in the Members column deletes all the members of the distribution list. To delete a distribution list from another distribution list, use the Administrator program.

This string can be specified in upper- or lower-case letters (~DEL or ~del).

Note Merely omitting a value in a column in a .CSV file does not delete an attribute. If, for example, you use ,, (no value specified between the separator characters), this column is ignored for that object, so the attribute's original value is maintained. This is why ~DEL must be used to delete an attribute.


Using the ~SERVER Substitution String

You can use the ~SERVER string to specify the current server against which the import operation is being run. During an import operation, the DAPIWrite and BatchImport functions substitute the name of the actual home server for this string. You can use this string not only to import the correct current value for the Home-Server attribute; but in any part of the import string, such as the Comments attribute.

Do not place quotation marks around ~SERVER. This string can be specified in upper- or lower-case letters (~SERVER or ~server).


Specifying Import Destinations

Objects are imported into containers in the Microsoft Exchange Server directory. The following table lists typical import destinations for objects most commonly imported using the directory access functions. Because more than one container of a given type may exist in a given directory information tree (DIT), specify the correct destination in the parameters to your function call.

Import Destinations for Objects Imported with Directory Access Functions

Object | Import to
Mailbox | Recipients container
Distribution List | Recipients container
Custom Recipient | Recipients container
Gateway | Connections container
Mailbox Agent | Recipients container
Address Type | Address Types container
Address Template | One-off Address Templates container

For more information about DIT structure, see About the Directory Information Tree.


Using Template Objects

When importing objects into the directory, you can specify a template object that contains default information. This information — in the form of attributes — may be assigned to objects being imported. During the import operation, the import function reads the attributes associated with the template's mailbox and uses this data as defaults for attribute values not specified in the import file.

The advantage of specifying templates for importing recipients is that administrators can select a user that closely approximates the basic configuration to be inherited by all the users about to be imported.

An example of using an object template is located in Example Directory Access Import File and File Formats.


Specifying the Template Object

You specify the template object — typically an existing recipient — with the pszCreateTemplate parameter in a structure passed to the BatchImport and DAPIStart functions. The template object can be expressed as the DN or RDN of an existing Microsoft Exchange Server directory object. The following is an example of a DN of an object:

bp->pszDefaultUser = "/o=Organization/ou=Site/cn=Recipients/cn=DefaultUser";


Rules for Importing Attributes

The BatchImport and DAPIWrite import functions follow these rules when using template objects for importing attributes:

  1. If an attribute value is specified explicitly in an import file or in the pAttributes parameter, this value is imported, even if it preempts user template data.
  2. If an attribute value is not specified in an import file or in pAttributes, but is specified in the template object, this value is imported unless it is a personal attribute.
  3. Personal attributes such as a recipient's Display-Name or e-mail address are not inherited from the template object. To determine which attributes are excluded, see the Duplicate User option of the Administrator program; it excludes the same attributes. Excluded personal attributes not given in an import file or in the pAttributes parameter are left blank in the destination object.


Restrictions on Importing Attributes with a Template Object

Importing objects does not allow cross-class inheritance. This means attributes and their values can be passed on only from a template of the same object type as the current object. For example, when importing recipients, only an existing Recipient object can successfully be used as a template. Attempts to inherit attributes from an object of another class will not always generate an error, but may produce unpredictable results.

Template inheritance does not apply to raw mode operation. In other words, if the DAPI_RAW_MODE flag is set, specification of a template object results in a warning that template objects are ignored, and the object is not read.

Template object values are inherited only when creating objects, not modifying them.


Existing Default Object Attributes

The following attributes are created by default when you call BatchImport or DAPIWrite to create a directory object. Subject to the notes in the right column, attributes in the left column are created on objects of classes listed in the center column. No values are set by default if the DAPI_RAW_MODE is set. These default settings are made only when creating objects, not modifying them.

Default Object Attributes

Attribute Name | Object Classes | Notes
Assoc-NT-Account | Mailbox | Windows NT Server account with same name in session-default security domain is designated as the primary account for the mailbox. The same account is given user privilege. Also see Generating Default Values.
Container-Info | Container | Set to 0x80000001, designating the container as a recipients container.
Deliv-Ext-Cont-Types | All recipient-class objects | Set to the value MH_CTO_MDBEF.
Admin-Display-Name | Container (all classes) | Set to Display-Name, if defined for object, or Common-Name, if not defined for object.
Display-Name | All recipient-class objects | Constructed using the rules described in Generating Default Values.
Maintain-AutoReply-History | All recipient-class objects | Set to TRUE if AutoReply has been specified.
Replication-Sensitivity | All recipient-class objects | Set to 20.
Mail-Nickname | All recipient-class objects | See Generating Default Values.
MAPI-Recipient | Mailboxes and Remote-Address objects | Set to TRUE.
MDB-Use-Defaults | Mailbox | Set to TRUE.
Delivery-Mechanism | Mailbox | Set to Zero.
Report-To-Originator | DL | Set to TRUE.
Report-To-Owner | DL | Set to FALSE.


Generating Default Values

Note This default attribute generation feature behaves as described here only in Microsoft Exchange Server version 5.0 (RC1) or later versions.

If the Display-Name, Mail-Nickname, and Assoc-NT-Account attributes are not specified in an import file, the directory access import functions construct default values for them. This generation of default values resembles that used by the Auto Naming feature of the Microsoft Exchange Server Administrator program. (Choose Options from the Tools menu, and then click the Auto Naming tab to see how Display name and Alias name strings are to be generated.) This generation occurs only for creation (import), and not for entry modification.

Default values are generated in this way:

  1. When DAPIStart or BatchImport are called, the Auto Naming format strings for generating Display-Name and Alias-Names are read and extracted from the Windows NT Registry. Data is stored in the registry on a per-administrator basis, which means that results may vary if the import is performed when different administrators are logged on.
  2. If these values are not specified, are not readable, or are specified as constant literal strings, default format strings are used. These are: DispName <= "%First %Last" and AliasName <= "%First%1Last".
  3. For each entry created through BatchImport or DAPIWrite, if there is no value specified for Display-Name or Mail-Nickname, a default value is constructed according to the rule obtained in step 1 or step 2. If the result of this construction contains no substituted text (that is, it resolves to a constant literal string), the Common-Name is used.

If no value is specified for either the Assoc-NT-Account attribute or the Obj-User attribute, the Mail-Nickname is used — either as specified or as constructed.

If the Common-Name (Directory Name) attribute is not specified, it will be defaulted to the Alias-Name or constructed according to the rule obtained in step 1 or step 2. If a value cannot be obtained for Common-Name, an error is logged.

In this import operation, the directory is not checked for duplicate Display-Names or duplicate e-mail names.


Creating a Mailbox

To create a mailbox for a recipient, create the object for that recipient in the directory. Later, the information store automatically creates a mailbox the first time a person or an application logs on as this recipient (after a MAPI profile has been created) or when someone tries to send mail to the recipient. No separate action is needed to create the object in the information store.

To create a mailbox for a recipient

Create a mailbox object in the directory by calling the DAPIWrite function. You can also use this call to DAPIWrite to create a Windows NT user account. In this function call, pass the pAttributes parameter, which points to a DAPI_ENTRY structure containing names of attributes to write. In this DAPI_ENTRY structure, you need to specify, at minimum, the following attributes:

  • The Object-Class, which is the OID of this object's class and (optionally) the OIDs of its superclass.
  • The Common-Name, which is the DN of this object. This attribute identifies the object.
  • The Home-Server. This may be specified as:

    A specific server.

    — Or—

    The string ~SERVER, which will be replaced with the name of the bound server.

    Although other attributes are required, default values are assigned if you omit them. For example:

  • The Display-Name is required for the MAPI address book. If it is not supplied, it is defaulted to the value specified for Common-Name.
  • Although the schema requires the Delivery-Mechanism attribute, the DAPIWrite function call creates a default value for this attribute for mailbox objects.


Creating an Associated Windows NT Account

You can configure the directory import system to automatically create a new Windows NT Server account when it imports a new recipient. To do this, set the DAPI_CREATE_NT_ACCOUNT flag in the BIMPORT_PARMS structure passed as a parameter with the BatchImport function, or in the DAPI_PARMS structure passed as a parameter with the DAPIStart function. You can also associate a new recipient with an already existing Windows NT Server account.

Duplicate Account Names Warning

If he DAPI_CREATE_NT_ACCOUNT flag is set, a warning is logged when the Windows NT account named in Assoc-NT-Account already exists. This warning enables administrators to take appropriate action when mailboxes with the same name have been associated with the same Windows NT account, resulting in the same Windows NT account having user privileges to mailboxes in multiple sites.

The warning message text (BWARN_ACCNT_EXISTS) is as follows:

Windows NT Account %2 already existed and was set as
the Primary Windows NT account for Mailbox %1.

where %1 is the Common-Name, and %2 is the qualified Windows NT account name (the account name is specified together with the domain name in the form domain\account).

This warning is logged whether the Assoc-NT-Account is explicitly specified or defaulted from another attribute — that is, from Mail-Nickname or Obj-Users.

Note The behavior described here applies to the SP3 release of Microsoft Exchange Server version 4.0, but not Microsoft Exchange Server version 5.0. In Microsoft Exchange Server 5.0 (RC1) or later versions, the warning is logged only when the value for Assoc-NT-Account is defaulted from another attribute. No warning is logged if the specified account already exists.


Working with Associated Windows NT Accounts

Using the Microsoft Exchange Server Administrator program, you can set or change the Windows NT account associated with a Microsoft Exchange mailbox. You make this setting on the General property page for the Recipient object, using the Primary Windows NT Account button.

Setting the Primary Windows NT Account has these results:

  • It determines the Windows NT security account that will have mailbox owner permissions on the mailbox. These directory permissions are granted only within the directory on the mailbox object for the security account, and are unrelated to the Windows NT security privileges held by that account.
  • It links the Windows NT security account to the mailbox object. This allows for linked administration of the mailbox and the security account, but has no affect on the account's Windows NT security privileges.

Windows NT security privileges are granted or denied to Windows NT security accounts through the data structure known as a Windows NT security descriptor. It describes specific object-access permissions granted to specific security accounts. For example, a mailbox's Primary Windows NT Account — identified by the Assoc-NT-Account attribute — has its own entry in the NT Security Descriptor, which in turn is stored in the NT-Security-Descriptor attribute.

The Assoc-NT-Account attribute does not contain the security account's textual name, but rather a binary string known as a security identifier (SID). Every object in the Windows NT Security Domain has a SID, and most, such as Windows NT user accounts, also have names — for example, REDMOND\fredb.

The directory access functions provide a mapping between the text name of the security account and the binary SID. The BatchImport and DAPIWrite functions accept a Windows NT Account name and call the Win32 function LookupAccountName to obtain a SID. BatchExport and DAPIRead obtain the account name by calling the Win32 LookupAccountSid function . For more information, see About Directory Security.

Using the Primary Windows NT Account Attribute

You can also work with the Primary Windows NT Account value programmatically. To do this with directory access functions, you would look up (export) or change (import) the Assoc-NT-Account attribute. With MAPI, this attribute is accessible as the PR_EMS_AB_ASSOC_NT_ACCOUNT property.

Making Security Settings with the Directory Access Functions

When a Primary Windows NT account is assigned to a mailbox, the directory access functions automatically modify the underlying security attribute (NT-Security-Descriptor) to grant mailbox owner rights to the account. This permissions change can take effect only if the application calling directory access functions is running under an account that has a role of Permissions Admin, rather than just Admin.

The directory access functions do not allow complete manipulation of security settings. For example, while you can use the directory access pseudo attributes to assign roles like User, Admin, and Permissions Admin, you cannot set the arbitrary rights combinations that you could set from the Administrator program.

You can, however, import an NT-Security-Descriptor setting, but only when using directory access raw mode. That is, you can build a Windows NT security descriptor using standard Windows NT security functions (such as LookupAccountSid), but to place it in the NT-Security-Descriptor attribute you need to call a directory access import function (BatchImport or DAPIWrite) with the DAPI_RAW_MODE control flag set. If you are attempting to set the security descriptor, it will need to be a self-relative security descriptor. (For more information on absolute and self-relative security descriptors, see Security Descriptors in the Microsoft Platform SDK.)

Making Security Settings with MAPI

If you have used MAPI to set the PR_EMS_AB_ASSOC_NT_ACCOUNT property, you will need to grant mailbox owner rights as well. Because this attribute on its own does not grant rights, the main underlying security attribute (PR_EMS_AB_NT_SECURITY_DESCRIPTOR) must also be updated to specify the rights you want the mailbox owner to have.

You will now need to add the account to the Windows NT security descriptor with the correct ACCESS_MASK structure.

To add a new Windows NT account to the Windows NT security descriptor

This simplified procedure contains the basic steps for adding a Windows NT account. For more complete information, see the Platform SDK documentation, including the overview of Windows NT security.

Before you begin, you need to know the Windows NT account name (or SID), the name of the security domain the account will be a member of, and the permissions to be granted to the account.

  1. If you do not already know the SID for the account in the appropriate security domain, obtain it by calling the Win32 security function LookupAccountName.
  2. Place this SID with the appropriate rights in an access control entry (ACE) in an access control list (ACL) in a security descriptor.

    In order to grant or revoke specific permissions to given Windows NT Accounts, you need to set the correct bits in the ACCESS_MASK structure in the access control entry when you build the security descriptor. For more information on the ACCESS_MASK structure, see the Win32 Structures documentation in the "Reference" section of the Microsoft Platform SDK.

  3. Convert this security descriptor into self-relative form (so that all members of the Win32 SECURITY_DESCRIPTOR structure are located contiguously in memory) for storage on the PR_EMS_AB_NT_SECURITY_DESCRIPTOR property.


Adding an Object to the Directory

You can add an object to the directory by using the directory access functions.

To add a directory object
  1. Call either the DAPIWrite function or the BatchImport function.
  2. If you use the DAPIWrite function, pass DAPI_WRITE_CREATE in the dwFlags parameter. This indicates that you want to create an object. If the object already exists, the call to DAPIWrite fails. In the pAttributes and pValues parameters, pass pointers to DAPI_ENTRY structures that contain the names of attributes to be written to the directory and the values for those attributes, respectively.
  3. If you use the BatchImport function, specify an import file in the pszImportFile member of the BIMPORT_PARMS structure.

For more information about import files, see Directory Access Function Files.


Adding an Application Object

In most cases, you will want to make a new application or service you write addressable. To do this, add it to the Microsoft Exchange Server directory using the BatchImport function or the DAPIWrite function.

To add an application object to the directory
  1. Follow the steps in Adding an Object to the Directory.
  2. For a complete installation of an application, not just its addition to the directory, see Creating a Complete Setup Program.


Synchronizing Directory and Information Store

The Microsoft Exchange Server directory and the Microsoft Exchange Server information store are closely associated. To receive mail, an object in the information store must also be represented in the directory. Note, however, that some directory objects do not require direct counterparts in the information store.

The relationship between an object in the directory and its corresponding object in the information store, if any, depends on the type of the object. This section explains what you need to know about creating and manipulating instances of the most common types of objects.

Mailbox Objects

Directory access functions can be used to import and export mailbox objects and include an option for creating or deleting Windows NT user accounts while creating or deleting mailboxes. For this reason, directory access functions can be called only from an application running on a Windows NT Server computer. For more information about creating mailboxes, see Creating a Mailbox.

Distribution List Objects

Distribution lists (DL) exist only in the directory, not in the information store. You create, edit, import, or export them in the directory. No changes need to be made to the information store.

Note A distribution list (DL) contains an attribute called Hide_DL_Membership. Setting this attribute causes the Administrator Program to hide the DL's membership list from administrators. It also causes backlinks to be hidden, which means that individual recipients cannot be identified as members of the DL. These restrictions do not apply to an administrator, who is usually the creator of the DL and as such has Windows NT modify-user rights on the DL.

Custom Recipient Objects

Directory access functions can be used to create custom recipients, which are addresses for users outside the Microsoft Exchange Server organization who must be represented in the directory service. For example, you can import lists of users who are to be accessed through a gateway. This provides a display name for these remote users and enables Microsoft Exchange Server users to send them messages.

Custom recipients exist only in the directory, not in the information store. You create, edit, import, or export them in the directory. No changes need to be made to the information store.

Gateway Objects

Directory access functions can create and modify Mail-Gateway objects. When a gateway object is created, a special mailbox is created in the information store. The mailbox contains the MTS-IN and MTS-OUT folders, which are used as queues for incoming and outgoing messages.

Mailbox Agent Objects

The directory access functions can be used to create and modify Mailbox-Agent objects. Creating a mailbox agent object in the directory has the same impact on the information store as creating a mailbox.

Address Type Objects

By adding new Address-Type objects to the directory, the directory access functions can be used to create new Microsoft Exchange Server address types. A new Address-Type object includes a pointer to a DLL used to generate new e-mail addresses (also called proxy addresses) for Microsoft Exchange Server mail recipients.

Address Template Objects

Address templates are associated with address types. They provide the client user interface for creating addresses of the new type. Address templates are stored in a different but related part of the directory hierarchy, because address templates can exist for different languages.

Public Folder Objects

Public folders differ from mailboxes because they are first created in the information store using MAPI calls, and then Microsoft Exchange Server automatically creates the associated directory object. Directory access functions should not be used to create public folders. However, you can use directory access functions to edit their attributes.


Using Directory Access Pseudo-Attributes

Directory access functions use several pseudo-attributes that exist alongside Microsoft Exchange Server directory schema attributes to provide additional functionality. They are available for use with directory access functions only.

These attributes are not part of the directory schema, and therefore cannot be accessed through the Microsoft Exchange Server Administrator program in raw mode. However, pseudo-attributes are treated like schema attributes in that they can be specified alongside schema attributes in the header line of an import file used by BatchImport or BatchExport.

Pseudo-Attributes Used by Directory Access Functions

Pseudo-Attribute | Purpose
Home-Server | Stores the values of the HomeMDB, HomeMTA, and HomeDSA schema attributes.
Obj-Container Sets the name of the container from which you're exporting when used with an export command.

Obj-Container is ignored when it is used with an import command and the DAPI_OVERRIDE_CONTAINER flag is set. If this flag is not set, the value specified in the import file for Obj-Container overrides the pszContainer attribute.

At initialization, you specify the basepoint parent container, but Obj-Container overrides it for the parent container or even for the basepoint, on an object-by-object basis. If all the objects you need to export are in the same container, you do not need to use Obj-Container. But if 90 percent of the objects you are exporting are in one container and 5 percent are in another, choose the first as the default container, then override it with Obj-Container.
Obj-Admins | Specifies the names of Windows NT Server accounts that are to be given administrator privilege on the object. The DAPIWrite and BatchImport functions import the Obj-Admins attribute only if the flag DAPI_RESTRICT_ACCESS is set.
Obj-Search | This pseudo-attribute is recognized on container objects only, and is similar to Obj-Admins. Windows NT accounts specified for Obj-Search are granted the privilege to administer security settings in the directory.
Obj-Users | Specifies the names of Windows NT Server accounts that are to have user privilege on the object. The DAPIWrite and BatchImport functions import the Obj-Users attribute only if the flag DAPI_RESTRICT_ACCESS is set.
Member Specifies the names of object members if this object is a distribution list. In all other cases, specifies the distribution lists of which the object is a member.

If an object is a member of a distribution list, change this membership by changing the Members attribute of the object. But if a distribution list is a member of other distribution lists, change these memberships by changing the Members attributes of the containing (not contained) distribution lists.
Mode | Specifies the operation mode for the import procedure and is optional. For complete information, see Specifying the Import Mode for BatchImport.
Secondary-Proxy-
Addresses 		When a request is made to export the Proxy-Addresses attribute, only the primary proxy address (the address used as the originator address on outgoing messages) is exported for each address type. To export secondary proxy addresses (additional addresses for which a gateway will accept incoming mail) the caller must request the Secondary-Proxy-Addresses pseudo-attribute.


Using MAPI with Directory Objects

The Microsoft Exchange Server address book provider provides access to directory objects through the MAPI address book interface. Using MAPI, you can create and delete directory objects, as well as view and change their attributes.

The main requirement for manipulating directory objects through the Microsoft Exchange Server address book provider is that MAPI entry identifiers be generated for the objects. An entry identifier can be created from the object's distinguished name, using the HrCreateDirEntryIDEx function.

To use MAPI to modify existing directory objects
  1. Find the object entry identifier in the directory. The object's presence in the address book means that it is exposed as an addressable entity, such as a mailbox, custom recipient, or distribution list. It is possible to create an entry identifier for an object by using its distinguished name. This provides a more direct way of accessing objects in the directory, including those not exposed in the MAPI address book. For more information about locating an object, see Opening an Object in the Directory and the MAPI Programmer's Reference.
  2. Use the object's entry identifier to invoke the IAddrBook::OpenEntry method on the object. This call returns the appropriate interface for performing operations on that object type. For example, if the object type is Mail-Recipient, OpenEntry returns a pointer to the IMailUser interface. With this call, you specify the type of access you want to the object: read/write or read-only.
  3. Use methods of the returned interface to read or write the object's attributes, depending on your task. For example, you can call IMAPIProp::SetProps (with the proper parameters, such as PR_COMMENT) on the object to change one or more of its attributes.
  4. Repeat step 3 on any other properties, using the appropriate read/write commands, until you've completed your directory work.
  5. Use the IMAPIProp::SaveChanges method to save your changes and either keep the object open to perform further operations or close the object. To keep the object open, use the KEEP_OPEN_READ_{ONLY|WRITE} flag in the SaveChanges call.

If your program modifies several objects, its code may look like this:

OpenEntry (object 1)
SetProps(property list)
GetProps(property list)
SaveChanges( )
Release()
OpenEntry (object 2)

To read or write several object properties at once, it is best to perform the task with a single IMAPIProp::SetProps or IMAPIProp::GetProps call. This is more efficient than repeatedly calling these methods and specifying a single property to read or write in each call.

Through the Microsoft Exchange Server address book provider, you can access directory objects that correspond to the five MAPI display types. The following table lists these display types, along with the most commonly used MAPI interface.

Corresponding Directory Objects and MAPI Display Types

MAPI Display Type | Directory Object Type | MAPI Interface
Distribution List | Distribution-List | IDistList
User | Mail-Recipient | IMailUser
Remote User | Remote-Address | IMailUser
Agent | Mailbox-Agent | IMailUser
Forum | Public-Folder | IMailUser

The IMailUser interface inherits methods from the IMAPIProp interface. Use the methods of these interfaces to access directory objects and their attributes. An object-valued attribute, which is an attribute whose type is PT_OBJECT, is seen by MAPI as a table. The attribute's values are members of the table. To access these values, use the IMAPITable interface, which is obtained by calling IMAPIProp::OpenProperty on the property of interest.

As with directory access import commands, the directory automatically updates the object's USN after it is modified using MAPI commands. Using MAPI commands in the directory has no effect on the information store. For more information about USNs, see Exporting Objects and Using Directory Access Functions.


Network and RPC Error Codes for Directory Operations

The following table lists error codes returned because of network or RPC-related errors when using MAPI to access the directory. These types of errors are usually encountered when the server is low on resources such as memory.

RPC-Related MAPI Error Codes

RPC Error | MAPI Error Returned
RPC_S_OUT_OF_MEMORY | MAPI_E_NOT_ENOUGH_MEMORY
RPC_S_OUT_OF_RESOURCES | MAPI_E_NOT_ENOUGH_RESOURCES
RPC_S_SERVER_TOO_BUSY | MAPI_E_BUSY
RPC_S_CALL_CANCELLED | MAPI_E_USER_CANCEL
Other errors | MAPI_E_NETWORK_ERROR

Most calls to MAPI methods can return these types of errors. You can handle the errors by placing the individual MAPI call into a retry loop that repeats the function call until the error is no longer encountered. You can also place all the code for working with a given message (including individual MAPI calls) into a retry loop. This process differs from that in use by the information store. See Network and RPC Error Codes for Information Store Operations.

In a call to the IAddrBook::PrepareRecips function, several address book service providers may be used. If one of the RPC errors listed in the preceding table occurs, this call may fail for some of the service providers — but not necessarily for all. MAPI discards errors from each service provider, which means that the expected list of properties in each ADRENTRY structure may not be present, or may be incomplete.

WaitForCompletion Not Implemented

The Microsoft Exchange Server address book provider does not implement the MAPI method IMAPITable::WaitForCompletion. This means that your applications should not call this method, nor should they call the methods IMAPITable::SortTable or IMAPITable::Restrict with the flag TBL_ASYNC set.


Accessing Directory Attributes with MAPI

Most attributes in the Microsoft Exchange Server directory can be accessed as MAPI properties. For example, where you might use the directory access function DAPIRead to export the Surname attribute of a Mailbox directory object, you could also call IMAPIProp::GetProps to find out the PR_SURNAME property of the same object.

Directory attributes are divided into two groups: attributes on the various types of recipient objects and attributes on nonrecipient objects. For more information on recipient attributes, see About Recipient Attributes. For more information on nonrecipient attributes, see About Nonrecipient Attributes. Each of these sections contains a table that maps directory attribute names to MAPI property tags.


About Recipient Attributes

Address book attributes are Microsoft Exchange directory attributes on recipient (address book) objects. The EMSABTAG.H file contains property tag definitions for the standard properties of Microsoft Exchange address book objects.

To open an address book attribute through MAPI, look up the attribute's property tag in EMSABTAG.H — or in the following table — and then pass that property tag in a call to the MAPI method IMAPIProp::GetProps.

The following table lists attributes on the various kinds of recipient objects in the Microsoft Exchange Server directory. The MAPI property names in the second column can be derived from the directory attribute names in the first column. To do this, append PR_EMS_AB_ as a prefix to the directory attribute name, replace any hyphens with underscore characters, and make all letters uppercase.

Properties Declared in EMSABTAG.H

Directory Attribute Name | Property Name
Activation-Schedule | PR_EMS_AB_ACTIVATION_SCHEDULE
Activation-Style | PR_EMS_AB_ACTIVATION_STYLE
Address-Entry-Display-Table | PR_EMS_AB_ADDRESS_ENTRY_DISPLAY_TABLE
Address-Entry-Display-Table-MSDOS | PR_EMS_AB_ADDRESS_ENTRY_DISPLAY_TABLE_MSDOS
Address-Syntax | PR_EMS_AB_ADDRESS_SYNTAX
Address-Type | PR_EMS_AB_ADDRESS_TYPE
ADMD | PR_EMS_AB_ADMD
Admin-Description | PR_EMS_AB_ADMIN_DESCRIPTION
Admin-Display-Name | PR_EMS_AB_ADMIN_DISPLAY_NAME
Admin-Extension-DLL | PR_EMS_AB_ADMIN_EXTENSION_DLL
Alt-Recipient | PR_EMS_AB_ALT_RECIPIENT
Alt-Recipient-BL | PR_EMS_AB_ALT_RECIPIENT_BL
Assoc-NT-Account | PR_EMS_AB_ASSOC_NT_ACCOUNT
AutoReply-Message | PR_EMS_AB_AUTOREPLY_MESSAGE
AutoReply-Subject | PR_EMS_AB_AUTOREPLY_SUBJECT
Business-Category | PR_EMS_AB_BUSINESS_CATEGORY
Business-Roles | PR_EMS_AB_BUSINESS_ROLES
Computer-Name | PR_EMS_AB_COMPUTER_NAME
Connected-Domains | PR_EMS_AB_CONNECTED_DOMAINS
Container-Info | PR_EMS_AB_CONTAINER_INFO
Cost | PR_EMS_AB_COST
Country-Name | PR_EMS_AB_COUNTRY_NAME
Deliv-Cont-Length | PR_EMS_AB_DELIV_CONT_LENGTH
Deliv-EITs | PR_EMS_AB_DELIV_EITS
Deliv-Ext-Cont-Types | PR_EMS_AB_DELIV_EXT_CONT_TYPES
Deliver-And-Redirect | PR_EMS_AB_DELIVER_AND_REDIRECT
Delivery-Mechanism | PR_EMS_AB_DELIVERY_MECHANISM
Description | PR_EMS_AB_DESCRIPTION
Display-Name-Override | PR_EMS_AB_DISPLAY_NAME_OVERRIDE
Domain-Def-Alt-Recip | PR_EMS_AB_DOMAIN_DEF_ALT_RECIP
Encapsulation-Method | PR_EMS_AB_ENCAPSULATION_METHOD
Encrypt | PR_EMS_AB_ENCRYPT
Expiration-Time | PR_EMS_AB_EXPIRATION_TIME
Export-Containers | PR_EMS_AB_EXPORT_CONTAINERS
Export-Custom-Recipients | PR_EMS_AB_EXPORT_CUSTOM_RECIPIENTS
Extension-Attribute-X | PR_EMS_AB_EXTENSION_ATTRIBUTE_X
Extension-Data | PR_EMS_AB_EXTENSION_DATA
Extension-Name | PR_EMS_AB_EXTENSION_NAME
Extension-Name-Inherited | PR_EMS_AB_EXTENSION_NAME_INHERITED
Facsimile-Telephone-Number | PR_EMS_AB_FACSIMILE_TELEPHONE_NUMBER
File-Version | PR_EMS_AB_FILE_VERSION
Filter-Local-Addresses | PR_EMS_AB_FILTER_LOCAL_ADDRESSES
Folder-Pathname | PR_EMS_AB_FOLDER_PATHNAME
Folders-Container | PR_EMS_AB_FOLDERS_CONTAINER
Gateway-Proxy | PR_EMS_AB_GATEWAY_PROXY
Help-Data16 | PR_EMS_AB_HELP_DATA16
Help-Data32 | PR_EMS_AB_HELP_DATA32
Help-File-Name | PR_EMS_AB_HELP_FILE_NAME
Heuristics | PR_EMS_AB_HEURISTICS
Hide-DL-Membership | PR_EMS_AB_HIDE_DL_MEMBERSHIP
Hide-From-Address-Book | PR_EMS_AB_HIDE_FROM_ADDRESS_BOOK
Home-MDB | PR_EMS_AB_HOME_MDB
Home-MDB-BL | PR_EMS_AB_HOME_MDB_BL
Home-Public-Server | PR_EMS_AB_HOME_PUBLIC_SERVER
Import-Container | PR_EMS_AB_IMPORT_CONTAINER
Import-Sensitivity | PR_EMS_AB_IMPORT_SENSITIVITY
Imported-From | PR_EMS_AB_IMPORTED_FROM
Instance-Type | PR_EMS_AB_INSTANCE_TYPE
International-ISDN-Number | PR_EMS_AB_INTERNATIONAL_ISDN_NUMBER
Is-Deleted | PR_EMS_AB_IS_DELETED
Is-Member-Of-DL | PR_EMS_AB_IS_MEMBER_OF_DL
Is-Single-Valued | PR_EMS_AB_IS_SINGLE_VALUED
Line-Wrap | PR_EMS_AB_LINE_WRAP
Link-ID | PR_EMS_AB_LINK_ID
Local-Bridge-Head | PR_EMS_AB_LOCAL_BRIDGE_HEAD
Manager | PR_EMS_AB_MANAGER
MAPI-Display-Type | PR_EMS_AB_MAPI_DISPLAY_TYPE
MDB-Backoff-Interval | PR_EMS_AB_MDB_BACKOFF_INTERVAL
MDB-Msg-Time-Out-Period | PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD
MDB-Over-Quota-Limit | PR_EMS_AB_MDB_OVER_QUOTA_LIMIT
MDB-Storage-Quota | PR_EMS_AB_MDB_STORAGE_QUOTA
MDB-Unread-Limit | PR_EMS_AB_MDB_UNREAD_LIMIT
MDB-Use-Defaults | PR_EMS_AB_MDB_USE_DEFAULTS
Member | PR_EMS_AB_MEMBER
Message-Tracking-Enabled | PR_EMS_AB_MESSAGE_TRACKING_ENABLED
N-Address | PR_EMS_AB_N_ADDRESS
N-Address-Type | PR_EMS_AB_N_ADDRESS_TYPE
Network-Address | PR_EMS_AB_NETWORK_ADDRESS
NT-Machine-Name | PR_EMS_AB_NT_MACHINE_NAME
OOF-Reply-To-Originator | PR_EMS_AB_OOF_REPLY_TO_ORIGINATOR
Organization-Name | PR_EMS_AB_ORGANIZATION_NAME
Organizational-Unit-Name | PR_EMS_AB_ORGANIZATIONAL_UNIT_NAME
Original-Display-Table | PR_EMS_AB_ORIGINAL_DISPLAY_TABLE
Original-Display-Table-MSDOS | PR_EMS_AB_ORIGINAL_DISPLAY_TABLE_MSDOS
Owner | PR_EMS_AB_OWNER
Owner-BL | PR_EMS_AB_OWNER_BL
P-Selector | PR_EMS_AB_P_SELECTOR
Per-Msg-Dialog-Display-Table | PR_EMS_AB_PER_MSG_DIALOG_DISPLAY_TABLE
Per-Recip-Dialog-Display-Table | PR_EMS_AB_PER_RECIP_DIALOG_DISPLAY_TABLE
PF-Contacts | PR_EMS_AB_PF_CONTACTS
Postal-Address | PR_EMS_AB_POSTAL_ADDRESS
Preferred-Delivery-Method | PR_EMS_AB_PREFERRED_DELIVERY_METHOD
PRMD | PR_EMS_AB_PRMD
Proxy-Addresses | PR_EMS_AB_PROXY_ADDRESSES
Proxy-Generator-DLL | PR_EMS_AB_PROXY_GENERATOR_DLL
Public-Delegates | PR_EMS_AB_PUBLIC_DELEGATES
Public-Delegates-BL | PR_EMS_AB_PUBLIC_DELEGATES_BL
RAS-Callback-Number | PR_EMS_AB_RAS_CALLBACK_NUMBER
RAS-Phone-Number | PR_EMS_AB_RAS_PHONE_NUMBER
RAS-Phonebook-Entry-Name | PR_EMS_AB_RAS_PHONEBOOK_ENTRY_NAME
RAS-Remote-SRVR-Name | PR_EMS_AB_RAS_REMOTE_SRVR_NAME
Registered-Address | PR_EMS_AB_REGISTERED_ADDRESS
Remote-Bridge-Head | PR_EMS_AB_REMOTE_BRIDGE_HEAD
Report-To-Originator | PR_EMS_AB_REPORT_TO_ORIGINATOR
Report-To-Owner | PR_EMS_AB_REPORT_TO_OWNER
Reports | PR_EMS_AB_REPORTS
Req-Seq | PR_EMS_AB_REQ_SEQ
Role-Occupant | PR_EMS_AB_ROLE_OCCUPANT
Routing-List | PR_EMS_AB_ROUTING_LIST
See-Also | PR_EMS_AB_SEE_ALSO
Site-Folder-GUID | PR_EMS_AB_SITE_FOLDER_GUID
Site-Folder-Server | PR_EMS_AB_SITE_FOLDER_SERVER
Site-Proxy-Space | PR_EMS_AB_SITE_PROXY_SPACE
Street-Address | PR_EMS_AB_STREET_ADDRESS
Supported-Application-Context | PR_EMS_AB_SUPPORTED_APPLICATION_CONTEXT
Supporting-Stack | PR_EMS_AB_SUPPORTING_STACK
Supporting-Stack-BL | PR_EMS_AB_SUPPORTING_STACK_BL
T-Selector | PR_EMS_AB_T_SELECTOR
T-Selector-Inbound | PR_EMS_AB_T_SELECTOR_INBOUND
Target-Address | PR_EMS_AB_TARGET_ADDRESS
Target-MTAs | PR_EMS_AB_TARGET_MTAS
Telephone-Number | PR_EMS_AB_TELEPHONE_NUMBER
Teletex-Terminal-Identifier | PR_EMS_AB_TELETEX_TERMINAL_IDENTIFIER
Temp-Assoc-Threshold | PR_EMS_AB_TEMP_ASSOC_THRESHOLD
Tombstone-Lifetime | PR_EMS_AB_TOMBSTONE_LIFETIME
Tracking-Log-Path-Name | PR_EMS_AB_TRACKING_LOG_PATH_NAME
Trans-Retry-Mins | PR_EMS_AB_TRANS_RETRY_MINS
Trans-Timeout-Mins | PR_EMS_AB_TRANS_TIMEOUT_MINS
Transfer-Retry-Interval | PR_EMS_AB_TRANSFER_RETRY_INTERVAL
Transfer-Timeout-Non-Urgent | PR_EMS_AB_TRANSFER_TIMEOUT_NON_URGENT
Transfer-Timeout-Normal | PR_EMS_AB_TRANSFER_TIMEOUT_NORMAL
Transfer-Timeout-Urgent | PR_EMS_AB_TRANSFER_TIMEOUT_URGENT
Translation-Table-Used | PR_EMS_AB_TRANSLATION_TABLE_USED
Transport-Expedited-Data | PR_EMS_AB_TRANSPORT_EXPEDITED_DATA
Trust-Level | PR_EMS_AB_TRUST_LEVEL
Turn-Request-Threshold | PR_EMS_AB_TURN_REQUEST_THRESHOLD
Two-Way-Alternate-Facility | PR_EMS_AB_TWO_WAY_ALTERNATE_FACILITY
Unauth-Orig-BL | PR_EMS_AB_UNAUTH_ORIG_BL
User-Password | PR_EMS_AB_USER_PASSWORD
USN-Changed | PR_EMS_AB_USN_CHANGED
USN-Created | PR_EMS_AB_USN_CREATED
USN-DSA-Last-Obj-Removed | PR_EMS_AB_USN_DSA_LAST_OBJ_REMOVED
USN-Last-Obj-Rem | PR_EMS_AB_USN_LAST_OBJ_REM
USN-Source | PR_EMS_AB_USN_SOURCE
X121-Address | PR_EMS_AB_X121_ADDRESS
X25-Call-User-Data-Incoming | PR_EMS_AB_X25_CALL_USER_DATA_INCOMING
X25-Call-User-Data-Outgoing | PR_EMS_AB_X25_CALL_USER_DATA_OUTGOING
X25-Facilities-Data-Incoming | PR_EMS_AB_X25_FACILITIES_DATA_INCOMING
X25-Facilities-Data-Outgoing | PR_EMS_AB_X25_FACILITIES_DATA_OUTGOING
X25-Leased-Line-Port | PR_EMS_AB_X25_LEASED_LINE_PORT
X25-Leased-or-Switched | PR_EMS_AB_X25_LEASED_OR_SWITCHED
X25-Remote-MTA-Phone | PR_EMS_AB_X25_REMOTE_MTA_PHONE
X400-Attachment-Type | PR_EMS_AB_X400_ATTACHMENT_TYPE
X400-Selector-Syntax | PR_EMS_AB_X400_SELECTOR_SYNTAX
X500-Access-Control-List | PR_EMS_AB_X500_ACCESS_CONTROL_LIST
XMIT-Timeout-Non-Urgent | PR_EMS_AB_XMIT_TIMEOUT_NON_URGENT
XMIT-Timeout-Normal | PR_EMS_AB_XMIT_TIMEOUT_NORMAL
XMIT-Timeout-Urgent | PR_EMS_AB_XMIT_TIMEOUT_URGENT


About Nonrecipient Attributes

Nonrecipient (non-address book) directory attributes are defined by Microsoft Exchange in the MAPITAGS.H file.

To open a nonrecipient attribute, first obtain its property tag. You can either call the MAPI method IMAPIProp::GetIDsFromNames or look up the property tag in the following table, which lists property tags defined in MAPITAGS.H. Then, call the IMAPIProp::GetProps method and pass that property tag.

Properties declared in MAPITAGS.H

Directory Attribute Name | Property Name
Address | PR_STREET_ADDRESS
Assistant-Name | PR_ASSISTANT
Comment | PR_COMMENT
Common-Name | PR_MHS_COMMON_NAME
Company | PR_COMPANY_NAME
Department | PR_DEPARTMENT_NAME
Display-Name-Printable | PR_7BIT_DISPLAY_NAME
Given-Name | PR_GIVEN_NAME
Initials | PR_INITIALS
Locality-Name | PR_LOCALITY
Mail-nickname | PR_ACCOUNT
MAPI-Recipient | PR_SEND_RICH_INFO
Physical-Delivery-Office-Name | PR_OFFICE_LOCATION
Post-Office-Box | PR_POST_OFFICE_BOX
Postal-Code | PR_POSTAL_CODE
State-Or-Province-Name | PR_STATE_OR_PROVINCE
Surname | PR_SURNAME
Telephone-Assistant | PR_ASSISTANT_TELEPHONE_NUMBER
Telephone-Fax | PR_PRIMARY_FAX_NUMBER
Telephone-Home | PR_HOME_TELEPHONE_NUMBER
Telephone-Home2 | PR_HOME2_TELEPHONE_NUMBER
Telephone-Mobile | PR_MOBILE_TELEPHONE_NUMBER, PR_CELLULAR_TELEPHONE_NUMBER
Telephone-Office1 | PR_BUSINESS_TELEPHONE_NUMBER, PR_OFFICE_TELEPHONE_NUMBER
Telephone-Office2 | PR_BUSINESS2_TELEPHONE_NUMBER, PR_OFFICE2_TELEPHONE_NUMBER
Telephone-Pager | PR_PAGER_TELEPHONE_NUMBER, PR_BEEPER_TELEPHONE_NUMBER
Telex-Number | PR_TELEX_NUMBER
Text-Country | PR_COUNTRY
Title | PR_TITLE
User-Cert | PR_USER_CERTIFICATE
When-Changed | PR_LAST_MODIFICATION_TIME
When-Created | PR_CREATION_TIME


Accessing PT_OBJECT Properties through MAPI

Many directory properties are of the type PT_OBJECT. To access the properties of this type declared in EMSABTAG.H, use the IMAPITable interface. The following procedure illustrates this method by accessing the Manager (PR_EMS_AB_MANAGER) and Reports (PR_EMS_AB_REPORTS) properties.

To read a directory object's Manager and Reports properties
  1. Create a MAPI entry identifier by calling HrCreateDirEntryId. In this call, pass the distinguished name (DN) of the directory object that contains the property in the lpszAddress parameter. .
    hr = HrCreateDirEntryId(
szDN,
&cbEntryID,
&lpEntryID);
  2. Call the IMAPISession::OpenEntry method using the entry identifier returned in step 1 to open an IMAPIProp interface on the object.
    LPMAPIPROP  lpObject   = NULL;

hr = MAPICALL(lpSession)->OpenEntry(
lpSession,
cbEntryID,
lpEntryID,
NULL,
0,
&ulObjType,
(LPUNKNOWN FAR *)&lpObject);

    For each of the PR_EMS_AB_MANAGER and PR_EMS_AB_REPORTS properties you want to access, perform the following steps:

  3. Call the IMAPIProp::OpenProperty method to open an IMAPITable interface on the property.
    LPMAPITABLE   lpTable  = NULL;

hr = MAPICALL(lpObject)->OpenProperty(
lpObject,
ulPropTag,
(LPIID)&IID_IMAPITable,
0,
MAPI_DEFERRED_ERRORS,
(LPUNKNOWN *)&lpTable);
  4. Call the MAPI HrQueryAllRows function to retrieve the rows in the table. For the PR_EMS_AB_MANAGER property, there will be a single row containing the manager's properties, such as PR_DISPLAY_NAME and PR_ENTRYID. For the PR_EMS_AB_REPORTS property, there will be one row for each report.
    LPSRowSet   lpRows   = NULL;

hr = HrQueryAllRows(lpTable, NULL, NULL, NULL, 0, &lpRows);


Finding the Global Address List

To find the global address list
  1. Start a MAPI session. For information on how to do this, see the first two steps of Opening an Information Store.
  2. Open the address book by calling IMAPISession::OpenAddressBook, passing the interface identifier (IID) of the address book object. This call returns an lppAdrBook parameter, which points to a variable where the pointer to the returned address book object is stored.
  3. Call HrFindExchangeGlobalAddressList to obtain the entry identifier (lppeid) of the global address list container within the address book.
  4. Call the OpenEntry function, passing the entry identifier returned in step 2.


Opening an Object in the Directory

If you know the distinguished name (DN) of an object in the directory, you can open that object using the HrCreateDirEntryIdEx function. For more information on DNs, see Microsoft Exchange Server Addresses.

To open a directory object
  1. Start a MAPI session. For information on how to do this, see the first two steps of Opening an Information Store.
  2. Open a the address book by calling the IMAPISession::OpenAddressBook method.
  3. Obtain an entry identifier for the object by calling the HrCreateDirEntryIdEx function, passing a pointer to the address book (returned in step 2) and the DN of the object.
  4. Call the OpenEntry function, passing the entry identifier for the object.


Comparing MAPI with Directory Access Functions

You can perform most directory tasks using either MAPI functions or directory access functions. Each of these sets of functions has its own advantages and its own dependencies.

For example, the directory access functions are specific to Microsoft Exchange Server. They run only on Windows NT Server computers on which the Microsoft Exchange Server Administrator program has been installed. Because directory access DLLs are not installed on client computers, you must use MAPI for all directory access activities performed by client applications, including those running on Windows 95 clients.

In contrast, MAPI is independent of the underlying directory service, which enables your program to work with any MAPI-compliant directory service.

For these reasons, you should typically use MAPI to manipulate directory objects. But certain other aspects of common directory operations should be considered, as discussed in the following sections.


Creating and Importing Proxy Addresses

The BatchImport and DAPIWrite directory access functions import valid proxy addresses for recipients and, when applicable, create new proxy addresses. If an imported recipient object has a value in its Proxy-Addresses attribute, that value is verified for correct format and uniqueness in the directory. If it passes, it is imported along with the object's other attributes.

These two functions automatically call the Microsoft Exchange Server system attendant. It in turn calls the proxy generation DLLs of installed gateways that add proxy addresses to new recipients as they are imported. Every new recipient object receives an X.400 address, even if no X.400 address was explicitly defined on the object before the import operation.

In contrast, the Microsoft Exchange Server address book provider does not automatically call the system attendant to generate proxy addresses. Therefore, if you have created a recipient object using MAPI, pass the appropriate information about the new recipient to the system attendant, which generates proxy addresses. The behavior of other address-book providers (such as a CompuServe address-book provider) must be investigated to determine their handling of proxy address generation.


Setting Security and Privileges on Objects

Directory access functions can be used to assign a Windows NT domain account to a mailbox object while creating or modifying the object. They can also set the NTSecurityDescriptor, which is a directory attribute on mailbox objects. For example, you can use directory access functions to restrict user access to objects when creating mailboxes or other objects.

MAPI functions do not create or modify Windows NT domain accounts.


MAPI and Directory Access Pseudo-Attributes

The directory access functions that are used for importing define several pseudo-attributes that are not part of the Microsoft Exchange Server directory schema. Using these attributes can simplify some operations, such as assigning privileges to an account to determine its access to a newly created object. These attributes are described in Using Directory Access Pseudo-Attributes.

Although the standard directory schema attributes can also be accessed as MAPI properties (see Accessing Directory Attributes with MAPI), the directory access pseudo-attributes have no direct MAPI equivalents.


Performing Bulk Operations

You can use directory access functions to perform bulk operations through the Microsoft Exchange Server Administrator program without writing code. Using import and export files, you can work with very large numbers of objects either programmatically or through the Directory Import and Directory Export commands of the Tools menu of the Administrator program. With MAPI, of course, you must perform bulk operations programmatically.


Accessing Addressable Objects through MAPI

All objects in the Microsoft Exchange Server directory are addressable. However, certain objects are better suited to manipulation through the MAPI address book (IAddrBook) interface than others. For example, Mail-Recipient objects, whose primary role is to receive messages, are often good choices for manipulation through MAPI. In contrast, Messaging-Domain objects (sites) are usually not mail recipients and are better accessed through the directory access functions.


Using the LDAP Protocol

The directory service of Microsoft Exchange Server supports the Lightweight Directory Access Protocol (LDAP) over TCP/IP connections. This means that the objects and attributes in the Microsoft Exchange Server directory are exposed to all applications that communicate through the LDAP protocol.

About LDAP

LDAP is an on-the-wire protocol used to perform directory operations such as read, search, add, and remove. The operations supported by LDAP have a close relationship to those specified by the CCITT X.500 Directory Access Protocol (DAP) but without the overhead of the session and presentation OSI layers.

With LDAP, all operations and parameters are carried directly over TCP or any other transport. LDAP and DAP are not interoperable; in other words, an LDAP client cannot be connected to a DAP server or vice versa without an agent that performs conversion between LDAP and DAP operations.

Support for Paged Results

LDAP as implemented by Microsoft Exchange Server supports paged results. This means that, if a request from an LDAP client would produce results too large for the client to handle (such as the address book of an entire organization), it can choose to receive the results in pages of smaller chunks (say, 100 entries each), one at a time. When the client finishes processing one page, it responds to the server, which then delivers the next page to the client.

Support for Referrals

LDAP as implemented by Microsoft Exchange Server supports referrals. With this mechanism, the DLL that provides LDAP support (WLDAP32.DLL) can be configured to automatically search for a given entry in a directory other than the one to which the request was originally sent. It can find this alternative directory through an IP address or a DNS name.


LDAP Protocol Operations

This section describes the protocol operations of LDAP and states whether each operation is implemented by the directory service of Microsoft Exchange Server. For more information on LDAP, see the documents Lightweight Directory Access Protocol (RFC1777) at http://directory service.internic.net/rfc/rfc1777.txt and The LDAP Application Program Interface (RFC1823) at http://directory service.internic.net/rfc/rfc1777.txt.


AbandonRequest

The AbandonRequest operation allows a client to abandon an outstanding operation.

Parameters

MessageID
The identifier of the message to be abandoned.


AddRequest

The AddRequest operation allows a client to add instances of objects in the directory. Anonymous users will not be able to add objects into the directory.

Parameters

Entry
The DN of the entry to add. All components of the DN other than the last RDN must exist for the add to succeed.
Attributes
The list of attributes and their values to set on the object created.


AddResponse

The AddResponse message is returned by the server to indicate the result of a AddRequest operation.

Parameters

AddResponse
The result of an AddRequest operation by the client.


BindRequest

In LDAP version 2, the BindRequest operation must be the first operation performed by an LDAP client. LDAP version 3 removes this restriction; in other words, an LDAP version 3 client can perform directory operations before successfully binding to the directory. Although it is acceptable for an LDAP version 3 server to reject operations from a client that has not bound to the directory first, the LDAP implementation of Microsoft Exchange Server supports LDAP operations from a client that has not successfully bound to the directory.

Parameters

Version
LDAP versions 2 and 3 are supported. However, with version 3, there are certain operational messages (such as SearchResultReferral) that are not returned to an LDAP version 2 client.
Authentication
Two types of authentication are supported: simple and sasl. For simple authentication, the user must supply a Windows NT domain and user account, in this format: dc=domain,cn=username. The Windows NT user account must be on a domain against which the user can authenticate. For sasl authentication, the user supplies sasl credentials, in one of two forms:

DPA: password authentication (for MCIS only)

NTLM: for Windows NT client support only

If a username and password are provided (in an octet string), the server checks the user's credentials; otherwise, the user is referred to as an 'anonymous' user.

Name
Contains the DN of the client. If the user is anonymous, the Name parameter is ignored; otherwise, if the Authentication parameter contains a password, the directory service must authenticate the user by ensuring validity of the password.


BindResponse

The BindResponse message is returned by the server to indicate the result of a BindRequest operation.

Parameters

BindResponse
The result of a BindRequest operation done by the client.


CompareRequest

This protocol operation is not implemented.

Parameters

None


CompareResponse

This protocol operation is not implemented.

Parameters

None


DelRequest

The DelRequest operation allows a client to remove an instance of an object in the directory.

Parameters

DN
The DN of the entry to be removed.


DelResponse

The DelResponse message is returned by the server as a result of a DelRequest operation by the client.

Parameters

DelResponse
The result of an DelRequest operation by the client.


ExtendedRequest

This protocol operation is not implemented.

Parameters

None


ExtendedResponse

This protocol operation is not implemented.

Parameters

None


ModifyDNRequest

This protocol operation is not implemented.

Parameters

None


ModifyDNResponse

This protocol operation is not implemented.

Parameters

None


ModifyRequest

The ModifyRequest operation allows a client to modify the value(s) of object(s) in the directory.

Parameters

Object
The DN of the object to be modified.
Modification
A list of modifications (add/delete/replace) to be performed on a entry to be modified. Modifications should be made in the sequence specified in this parameter. This means that in a single ModifyRequest you can perform a number of modifications to one or more attributes (for example, to add or remove distribution list membership).

Because there is a sequence of these Modification parameters, you can perform multiple operations on multiple objects in one operational message.

Remarks

It is possible to modify a proxy using the ModifyRequest operation.


ModifyResponse

The ModifyResponse message is returned by the server to indicate the result of a modify operation.

Parameters

ModifyResponse
The result of a ModifyResponse operation by the client.

Remarks

It is possible to modify a proxy using the ModifyResponse operation.


SearchRequest

The search operation allows a client to search the directory

Parameters

baseObject
The distinguished name (DN) of the object where the search starts.
Scope
Microsoft Exchange Server supports all three options: baseObject, singleLevel, and wholeSubtree.
Filter
Provides a set of conditions that need to be met. Microsoft Exchange Server supports all filters, namely: and, or, not, equalityMatch, substrings, greaterOrEqual, lessOrEqual, present, approxMatch (maps to equalityMatch), and extensibleMatch.
derefAliases
The use of this parameter is not implemented.
SizeLimit
Allows the client to limit the number of entries to be returned as a result of a search operation. A value of 0 indicates no size restrictions. The default is 0.
TimeLimit
Allows the client to limit the time in seconds for a search operation. A value of 0 indicates no time limit.
attrsOnly
Indicates whether only Attribute Type or Types and Value should be returned. The default is FALSE (Types and Value).
Attributes
Allows the client to specify a list of attributes from entries found to be returned. An empty list signifies all attributes. The default is to return all attributes.
matchedOnly
The use of this parameter is not implemented.
sortKeys
The use of this parameter is not implemented.
ReverseSort
The use of this parameter is not implemented.
ModifyRightsReq
The use of this parameter is not implemented.
AttrSizeLimit
Allows the client to prevent attributes exeeding a specified size from being returned. A value 0 indicates no size limit restrictions. The default is 0.
Subentries
Allows the client to specify that only subentries should be searched not ordinary entries. The LDAP version 3 specification allows a server to return an empty list or ProtocolError as a result of this.
DontUseCopy
The use of this parameter is not implemented.


SearchResultDone

The SearchResultDone message is returned after the last SearchResultEntry message to indicate the result of the search.

Parameters

LDAPResult
The result of the SearchRequest operation.


SearchResultEntry

The server will return a SearchResultEntry for each entry found as a result of a SearchRequest operation by the client. There can be zero or more SearchResultEntry messages returned as a result of a single SearchRequest operation by the client.

Parameters

ObjectName
The DN of the matching object (there will be one of these in each SearchResultEntry message). If the base of the object returned is the same as BaseObject in the SearchRequest operation, it can be replaced with an asterisk character (*).
Attributes
Contains a list of attribute type and value(s) of the object that matched the search. If the SearchRequest had set the extraAttributes flag and the user was not anonymous then the operational attributes are returned as well.
IncompleteEntry
This flag is set to TRUE if the size of an attribute and all it's values to be returned exceeds that of attrSizeLimit. In this case the attribute is not included in the attributes list.›.
FromEntry
The use of this parameter is not implemented.
ModifyRights
The use of this parameter is not implemented.


SearchResultFull

This is a single message containing the results of a search. It's basically a sequence of SearchResultEntry followed by a SearchResultDone. This message is sent by the server if it is operating over a connectionless oriented transport..


SearchResultReferral

This is returned if the directory has knowledge of another directory that might be able to satisfy the SearchRequest.

Parameters

referral
This is the URL of a directory that may be able to satisfy the request. A list of namespace and portnumber mapping needs to be configured by the administrator which is described in more detail under the referrals section of this document.


UnbindRequest

The UnbindRequest operation allows the client to terminate a session with the directory.

Parameters

None


Information Store Operations

The Microsoft Exchange Server implementation of a MAPI message store is called an information store.You will use MAPI functions and methods to work with information stores.

A Microsoft Exchange Server information store can contain messages, forms, documents, and other information created by users and applications. It provides each user with a server-based mailbox and stores public folder contents.

In addition, the information store enforces security, replicates public folders, enforces storage limits, and delivers messages to users on the same server. It maintains information in two databases: the public information store and the private information store. For information about the structures and characteristics of information stores, see About the Information Store.


Working with Information Stores

Development tasks that are performed when working with information stores include the following:

Opening an Information Store

Locating an Information Store

Opening a Public Information Store

Determining the Type of Information Store


Opening an Information Store

An application that needs to access an information store must first open it. This action serves as the basis for opening public information stores, working with folders and messages, and other related tasks.

To open an information store
  1. Initialize MAPI, using the MAPIInitialize function. This step loads the MAPI DLLs and sets up entry points into them so that your application can call MAPI functions and methods.
  2. Log on to a MAPI profile, using the MAPILogonEx function. This function call returns an LPSESSION pointer to an IMAPISession object (also know as a session handle). The MAPI profile contains information on services, each of which implements one information store. One of the information stores for the profile is its default information store, which is often the information store you want your application to open.
  3. Select an information store to open. To open the default information store, call the HrMAPIFindDefaultMsgStore function, passing the session handle. This function call returns the entry identifier of the default information store. To select a different information store, see Locating an Information Store.
  4. Open the information store by passing its entry identifier in a call to the IMAPISession::OpenMsgStore method. This call creates the information store object (an LPMDB) and returns a pointer to it.

Note When making multithreaded IMAPISession::OpenMsgStore calls, the MDB_NO_DIALOG flag should be set.


Opening a Public Information Store

Once you have a handle to a MAPI session, you can use it to find the public information store. Information stores are cataloged in the message store table, which can be searched using the IMAPISession::GetMsgStoresTable method.

Each information store is identified through its GUID (globally unique identifier). The Microsoft Exchange Server public information store has the PR_MDB_PROVIDER property set to pbExchangeProviderPublicGuid, which is defined in the EDKMDB.H file.

To open a public information store
  1. Log on to a MAPI profile with the MAPILogonEx function. This call returns a MAPI session handle.
  2. Call the HrOpenExchangePublicStore function, passing the session handle obtained in step 1 in the lphSession parameter. As a result of this call, the lppMDB output parameter points to the opened public information store.

For more information on obtaining a session handle, see Opening an Information Store. For an example of using the HrOpenExchangePublicStore function in use, see the sample application source file \BKOFFICE\SAMPLES\EXCHANGE\SMBAGENT\SMBAGENT.C.


Opening a Private Information Store

A private information store is the MAPI message store implementation (part of the Microsoft Exchange Server information store) that stores mailboxes for users. Once you have a handle to a MAPI session, you can use it to locate the private information store for the user whose profile you used to log on.

To open a private information store
  1. Log on to a MAPI profile with the MAPILogonEx function. This call returns a MAPI session handle.
  2. Call the HrOpenExchangePrivateStore function, passing the session handle obtained in step 1 in the lphSession parameter. As a result of this call, the lppMDB output parameter points to the opened private information store.

For more information on obtaining a session handle, see Opening an Information Store. For examples of using the HrOpenExchangePrivateStore function, see the sample application source files \BKOFFICE\SAMPLES\EXCHANGE\MBLSAMPL\MBLSAMPL.C and \BKOFFICE\SAMPLES\EXCHANGE\MBXSERV\MBXSERV.CPP.


Locating an Information Store

If you do not want to open the default information store in the current profile, you can search for and choose one of the other information stores in that profile. After logging on to a profile and obtaining a session handle, follow the steps in one of the following two procedures. For more information, see the first steps of Opening an Information Store).

To locate an information store using the IMAPISession::GetMsgStoresTable method
  1. Call the IMAPISession::GetMsgStoresTable method. This call returns a pointer to a table. Each row in the table corresponds to one of the profile’s information stores.
  2. Use the MAPI HrQueryAllRows function to retrieve all rows of the table. Its output parameter pprows points to the returned SRowSet structure, which contains the retrieved table rows.
  3. Locate the information store by searching through each row's PR_DISPLAY_NAME property and retrieve that row's PR_ENTRY_ID property. These two properties are on each information store object as columns in the table. For example, the PR_DISPLAY_NAME property is the string that appears in the left pane of the Microsoft Exchange Client. It may contain text such as "Mailbox - Louise Morgan."
  4. You can now open the information store using its PR_ENTRY_ID property in a call to the IMAPISession::OpenMsgStore method.

To locate an information store using the HrMAPIFindStore function
  1. Call the HrMAPIFindStore function, passing a string that contains the name of the information store. This function returns the PR_ENTRY_ID of the information store object.
  2. You can now open the information store using its PR_ENTRY_ID property in a call to the IMAPISession::OpenMsgStore method.

For more information, see Opening an Information Store, Opening a Public Information Store, and Opening a Private Information Store.


Determining the Type of Information Store

In some cases, your application may not know if a store is a Microsoft Exchange Server public information store or private information store, even though it has already obtained a pointer to it. To determine the type of information store, check the value of the store’s PR_MDB_PROVIDER property. This procedure is performed within the FIsPublicStore function.

To determine the type of information store
  1. Open the information store as described in Opening an Information Store. The call to the IMAPISession::OpenMsgStore method creates the information store object and returns an LPMDB pointer to it.
  2. Call the FIsPublicStore function, passing the LPMDB pointer to the information store. This function checks the information store’s PR_MDB_PROVIDER property. If the value of this property is pbExchangeProviderPublicGuid, the store is a public information store and the function sets its output parameter lpIsPublicStore to TRUE. Other values for this property correspond to other types of information stores; for more information, see the following section.

Identifying Providers by Provider GUIDs

Microsoft Exchange Server defines several GUIDs in the EDKMDB.H file. The MAPI PR_MDB_PROVIDER property can have these values in the store table and when returned from a call to the IMAPIProp::GetProps method on the information store, on a folder, or on message objects. The value returned identifies the type of information store provider.

GUID | Information Store Provider
pbExchangeProviderPrimaryUserGuid | Private information store. Calling application is the owner
pbExchangeProviderDelegateGuid | Private information store. Calling application has delegate access
pbExchangeProviderPublicGuid | Microsoft Exchange Server public information store

Another GUID is also used to recognize the Microsoft Exchange Server transport provider in the transports table.

GUID | Type of Provider
pbExchangeProviderXportGuid | Microsoft Exchange Server transport provider

If a provider GUID does not match any of the entries in the preceding tables, it is not a provider specific to Microsoft Exchange Server.


Working with Folders

When developing Microsoft Exchange Server applications, you customize and manipulate public, private, and personal folders by programming with MAPI and using features such as ACLs, rules, and folder replication.

For information about public folders, see About Public Folders and Working with Public Folders. For information about the interfaces and properties used when working with folders, see Folder Object.

For information about permissions on folders, see About Access Control Lists.


Creating a Folder

This procedure can be used for creating a folder in the public, private, or personal information stores. You cannot create subfolders in the Favorites container of the public information store.

To create a folder
  1. Open the information store. This returns an LPMDB pointer to the open information store. See Opening an Information Store.
  2. Open the folder in which you want to create a new folder by calling the IMsgStore::OpenEntry method, with the MAPI_MODIFY flag set. This folder will be the container of the folder you are creating.
  3. Create the folder with a call to the IMAPIFolder::CreateFolder method. This creates the subfolder object and returns an LPMAPIFOLDER pointer to it, which gives access to the IMAPIFolder interface on the new object.
  4. Optionally, set the folder’s PR_STATUS property to indicate a user-defined value. Use IMAPProp::SetProps to set this property.

The following sample code illustrates this procedure:

// Open the parent (or root) folder...
hr = lpMsgStore->OpenEntry(
    cbEID,    // use 0L for root folder
    lpEID,    // use NULL for root folder
    NULL,     // use NULL for interface ID
    MAPI_MODIFY | MAPI_DEFERRED_ERRORS, // use MAPI_MODIFY if
    you plan to make changes
    &ulObjType,
    (LPUNKNOWN*)&lpParentFolder);

//  Create folder with MAPI call...
hr = lpParentFolder->CreateFolder(
    FOLDER_GENERIC,
    TEXT("Folder Name"),
    TEXT("Folder Comment"),
    NULL,        // Interface ID, must be NULL for client apps
    fMapiUnicode,
    &lpNewFolder);

// At this point you may set the folder's PR_STATUS property.
// It is purely optional, and may be any value you find meaningful.
static SPropValue PropStatus = { PR_STATUS, 0L, {0L}};
SPropProblemArray lpProblems = NULL;

hr = lpNewFolder->SetProps( 1, &PropStatus, &lpProblems);


Opening Special Folders

The entry identifiers of certain special folders (such as the IPM Subtree, the Outbox, and the Sent Items folder) are stored as properties on the information store objects that contain them.

To open a special folder
  1. Open the private, personal, or public information store. This returns an LPMDB pointer to the open information store. See Opening an Information Store.
  2. Open the folder within the information store by calling the MAPI IMsgStore::OpenEntry method. In this function call, pass the entry identifier of the folder in the lpEntryID parameter. For a list of entry identifiers, see Entry Identifiers of Special Folders and Expressing Paths to Folders.


Entry Identifiers of Special Folders

MAPI and Microsoft Exchange Server define entry identifiers for a number of special folders. You can use them to directly open these types of folders when calling the IMsgStore::OpenEntry method. The entry identifiers are properties on the information store object that contains the folder of interest.

No special entry identifier is declared for a folder’s Inbox. For information on how to locate an Inbox, see Opening the Inbox.

One advantage to using entry identifiers is that you can use them to open special folders in any installation of Microsoft Exchange Server, regardless of the language in use. Special folders are listed in the following tables under their English names.

A second advantage is that using an entry identifier is a faster way to open a special folder than using the HrMAPIFindFolderEx function.

Entry Identifiers of Special Folders (Declared by MAPI)

Entry Identifier | Folder Name
Folders in information stores |
PR_IPM_SUBTREE_ENTRYID | IPM Subtree
PR_IPM_OUTBOX_ENTRYID | Outbox
PR_IPM_WASTEBASKET_ENTRYID | Deleted Items
PR_IPM_SENTMAIL_ENTRYID | Sent Items
PR_VIEWS_ENTRYID | Views
PR_COMMON_VIEWS_ENTRYID | Common Views
PR_FINDER_ENTRYID | Finder

Entry identifiers in the preceding table are declared by MAPI in the MAPITAGS.H file. The entry identifiers in the following table are declared by Microsoft Exchange Server in the EDKMDB.H file.

Entry Identifiers of Selected Special Folders (Declared by Microsoft Exchange Server)

Entry Identifier | Folder Name
Folders in Private (Mailbox) Information Stores |
PR_SCHEDULE_FOLDER_ENTRYID | Schedule
PR_IPM_DAF_ENTRYID | Deferred Action
Folders in Public Information Stores |
PR_IPM_PUBLIC_FOLDERS_ENTRYID | IPM Subtree\All Public Folders
PR_IPM_FAVORITES_ENTRYID | IPM Subtree\Favorites
PR_NON_IPM_SUBTREE_ENTRYID | Non-IPM Subtree
PR_ADDRBOOK_FOR_LOCAL_SITE_ENTRYID | Microsoft internal use
PR_EFORMS_FOR_LOCALE_ENTRYID | Microsoft internal use
PR_EFORMS_REGISTRY_ENTRYID | EFORMS Registry
PR_FREE_BUSY_FOR_LOCAL_SITE_ENTRYID | Microsoft internal use
PR_OFFLINE_ADDRBOOK_ENTRYID | Offline Address Book
PR_SPLUS_FREE_BUSY_ENTRYID | Schedule+ Freebusy
Folders in Gateway-Specific Information Stores |
PR_GW_MTSIN_ENTRYID | MTS-IN
PR_GW_MTSOUT_ENTRYID | MTS-OUT
Other Folders |
PR_HEADER_FOLDER_ENTRYID | Microsoft internal use
PR_DEFAULT_VIEW_ENTRYID | Microsoft internal use


Expressing Paths to Folders

The HrMAPIFindFolderEx, HrMAPIOpenFolderEx, HrMAPIFindSubfolderEx, and HrMAPIOpenSubfolderEx functions require the path to a folder as an input parameter. You can express this path in one of two ways:

  • By using display names
  • By using an entry identifier

Path Using Display Names

In the folder path parameter (lpszFolderPath or lpszName), use a series of display names starting with the first folder in the information store. Separate the display names by a character you can specify in the chSep parameter (such as a backslash). For example:

IPM_Subtree\Business\Conferences\Global Summit\Session Materials

Note The Favorites and All Public Folders display names are not valid when used in a path name without an entry identifier. See the following section.

Path Using an Entry Identifier

In the folder path parameter (lpszFolderPath or lpszName), use a path that starts with one of the property names listed in the tables in the section Entry Identifiers of Special Folders. Append an @ character to the beginning of the property name. Following the property name, use a series of display names for the subfolders.

For example, the following two path examples point to the same location:

@PR_IPM_PUBLIC_FOLDERS_ENTRYID\Business\Conferences\Global Summit\Session Materials

IPM_Subtree\Business\Conferences\Global Summit\Session Materials

Note The Favorites and All Public Folders display names are valid only when using the @PR_IPM_SUBTREE_ENTRYID property name to begin the path. For example, this path is valid:

@PR_IPM_SUBTREE_ENTRYID\All Public Folders\Business\Conferences\Global Summit\Session Materials


Opening the Inbox

Because no specially declared property holds the entry identifier of an information store Inbox, you must call a function to retrieve its entry identifier.

To find the Inbox
  1. Open the information store that contains the Inbox. See Opening an Information Store.
  2. Find the entry identifier of the Inbox folder by calling HrMAPIFindInbox and passing a pointer to the open information store.
  3. Open the Inbox folder by calling IMsgStore::OpenEntry and passing the entry identifier of the Inbox.

The following sample code is from the SMBAGENT.C file in the \BKOFFICE\SAMPLES\EXCHANGE\SMBAGENT directory. It opens the Inbox folder in the mailbox of the SMBAGENT sample application.

// Find SMBAGENT's Inbox folder
hr = HrMAPIFindInbox( lpStore, &cbInEntryID, &lpInEntryID);

ASSERTERROR ( lpInEntryID != NULL, "NULL lpInEntryID");

// Open SMBAGENT's Inbox folder
hr = MAPICALL(lpRootFolder)->OpenEntry( lpRootFolder,
    cbInEntryID,
    lpInEntryID,
    NULL,
    MAPI_MODIFY|MAPI_DEFERRED_ERRORS,
    &ulObjType,
    (LPUNKNOWN FAR *) &lpInFolder);

if( ulObjType != MAPI_FOLDER)
{
    hr = HR_LOG( E_FAIL);
    goto cleanup;
}


Opening an Existing Private or Personal Folder

You can open an existing folder if you know either its entry identifier or the value of its Display-Name property. It is faster to use the entry identifier if it is known.

To open an existing private or personal folder
  1. Open the private information store or personal folder store (PST) that contains the folder. This step returns an LPMDB pointer to the open information store. See Opening an Information Store.
  2. Call either the HrMAPIFindFolderEx function or the HrMAPIOpenFolderEx function. In each case, pass both the pointer returned in step 1 and the folder path. See Expressing Paths to Folders. HrMAPIFindFolderEx returns the entry identifier of the folder, which you can use to open it. The HrMAPIOpenFolderEx function locates the folder and opens it.

    – Or –

  3. Open the root folder of the information store by calling the MAPI IMsgStore::OpenEntry method.

    The following sample code shows the call to open the root folder of an information store:

    // Open the parent (or root) folder...
hr = lpMsgStore->OpenEntry(
    0L,      // use 0L for root folder
    NULL,    // use NULL for root folder
    NULL,    // use NULL for interface ID
    MAPI_MODIFY | MAPI_DEFERRED_ERRORS, // use this flag if you plan to make changes
    &ulObjType,
    (LPUNKNOWN*)&lpParentFolder);
  4. Call the HrMAPIFindSubfolderEx function or the HrMAPIFindSubfolderEx function. In either call, pass both the LPMAPIFOLDER pointer returned in the preceding step and the folder path. See Expressing Paths to Folders. HrMAPIFindFolderEx returns the entry identifier of the folder, which you can use to open it later. The HrMAPIOpenSubfolderEx function locates the folder and opens it.


Working with Public Folders

Public folders are distinguished from private foldersby several characteristics:

  • They are accessible by people or applications throughout the organization, provided those people or applications have the necessary permissions to access the folders. For more information, see About Information Store Security.
  • They are location-independent within a site.
  • They support replication between servers in a site and between sites in an organization. The fact that they are replicated means replication conflicts can occur in their content.
  • They support public folder affinity, which is the ability of a client application to look at a server on another site and access a public folder. As an alternative to replicating that folder to the local site, public folder affinity is normally used if a high-bandwidth connection exists.

To develop applications that use public folders, you use MAPI interfaces. These interfaces enable you to directly manipulate public folders, their properties, and their contents in the information store. Microsoft Exchange Server functions that may also be used with public folders include FIsPublicStore, HrFindExchangePublicStore, and HrOpenExchangePublicStore.

For more information about using MAPI to program folders, see the MAPI Programmer's Reference. For information about folder objects, see Folder Object.


Opening an Existing Public Folder

Public folders are located in the Microsoft Exchange Server public information store, which is a portion of the information store. Therefore, before you can access public folders, you must locate and open the public information store.

You can open an existing folder if you know either its entry identifier or a path to the folder, including the value of its Display-Name property. It is faster if you use the entry identifier to open the folder, if you know it. Also, folder paths or names may change, so reusing a path to a folder that once worked may fail. A folder’s entry identifier remains the same, so using it should work reliably.

To open an existing public folder using the HrOpenExchangePublicFolders function
  1. Open the public information store by calling the HrOpenExchangePublicStore function. For more information, see Opening a Public Information Store.
  2. Open the All Public Folders container by calling the HrOpenExchangePublicFolders function and passing the LPMDB pointer to the public information store. This returns an LPMAPIFOLDER pointer to the open folder.
  3. Call either the HrMAPIFindSubfolderEx function or the HrMAPIOpenSubfolderEx function. In each case, pass both the pointer returned in step 2 and the path to the folder, as described in Expressing Paths to Folders.

    The HrMAPIFindSubfolderEx function returns the entry identifier of the folder, which you can use to open it later. The HrMAPIOpenSubfolderEx function locates the folder and opens it for you.

To open an existing public folder using the HrMAPIOpenFolderEx function
  1. Open the public information store by calling the HrOpenExchangePublicStore function. For more information, see Opening a Public Information Store.
  2. Open the IPM_SUBTREE folder by calling the HrMAPIOpenFolderEx function, and passing either a folder path or folder name. For more information, see Expressing Paths to Folders.

    This call returns an LPMAPIFOLDER pointer to the open folder. At this point, you have opened the All Public Folders container.

  3. Call either the HrMAPIFindSubfolderEx function or the HrMAPIOpenSubfolderEx function. In each case, pass both the pointer returned in step 2 and the path to the folder.

    The HrMAPIFindSubfolderEx function returns the entry identifier of the folder, which you can use to open it later. The HrMAPIOpenSubfolderEx function locates the folder and opens it for you.

Note The Favorites folder can contain only one level of subfolders. These subfolders can contain messages, but not other subfolders.


Configuring Public Folders

Configuring public folders consists of a combination of the following actions:

  • Setting ACLs on the public folder to control access. For more information, see Manipulating ACLs.
  • Configuring public folder replication. See the Microsoft Exchange Server Administrator’s Guide and the Microsoft Exchange Server Concepts and Planning Guide and Public Folder Replication.
  • Setting rules on the public folder. For more information, see Working with Rules.


Public Folder Replication

Public folder replication is configured by an administrator through the Microsoft Exchange Server Administrator program. Although you can develop ways to report on the status of public folder replication in your site or organization, programmatic control of replication is limited.

Reporting on Replication

The GetMailboxTable and GetPublicFolderTable members of the IExchangeManageStore interface can be called to return summary information. Each of these methods returns tables.

  • The GetMailboxTable method returns a table with one row for each mailbox on the server — not just the mailboxes in the calling user’s profile.
  • The GetPublicFoldersTable method returns a list of all the public folders that have replicas on the server.

These functions are the basis of the mailbox and public folder resources pages that appear in the Administrator program. Therefore, the user interface of the Microsoft Exchange Administrator program can help you see what information is available as columns in the tables returned by these functions.

PR_REPLICA_SERVER is a read-only property on an item in a folder. It contains the server name from which the item was replicated. This property may also be useful for reporting on replication.

Controlling Replication

Replica servers can be determined on a per-folder basis by examining the values in the read/write PR_REPLICA_LIST property on the folder. This property contains a list of the distinguished names (DNs) of the servers that are replicating (receiving and sending) the contents of the public folder. Replication for a single folder can be controlled by editing the values of PR_REPLICA_LIST. Changing the values in this property is the only way that replication can be controlled programmatically.

Note A folder or set of folders can be replicated to only one location in an information store. For example, you can copy a folder into a mailbox and then copy it into the same mailbox again. This produces nearly identical folders, each with its own unique entry identifier. But if you configure or program folders to be replicated, the folders can be replicated to only one location within a given public folder store.


Working with the Favorites Folder

Using the IExchangeFavorites interface, you can programmatically add public folders to the Favorites folder and delete public folders from the Favorites folder.

You can obtain the IExchangeFavorites interface by calling the QueryInterface method on the folder whose entry identifier is specified by the PR_IPM_FAVORITES_ENTRYID property on the public folder store. This interface exposes the following methods:

Methods of the IExchangeFavorites Interface

Method | Description
IExchangeFavorites::AddFavorites | Adds a list of public folders to the Favorites folder.
IExchangeFavorites::DelFavorites | Removes a list of public folders from the Favorites folder.
IExchangeFavorites::GetLastError | Retrieves information about the last occurring error condition.


Opening the Favorites Folder

The visibility of the All Public Folders folder and the Favorites folder differs according to the way they are sought. When an application opens the IPM_SUBTREE folder by first obtaining the MAPI PR_IPM_SUBTREE_ENTRYID property and then obtaining the hierarchy table at this level, the Favorites and All Public Folders folders appear in the hierarchy table.

But when an application directly traverses the hierarchy table beginning with the root folder of the public information store, the Favorites folder and the All Public Folders folder do not appear in the hierarchy table. The subfolders of the All Public Folders folder appear in the hierarchy directly under the IPM_SUBTREE folder.

To open the Favorites folder or the All Public Folders folder directly, use the PR_IPM_PUBLIC_FOLDERS_ENTRYID and PR_IPM_FAVORITES_ENTRYID properties on the public information store object. This method for opening the Favorites folder is described in the following procedure. For more information, see About the Favorites Folder.

To open the Favorites folder using HrOpenExchangePublicStore
  1. Open the public information store by calling the HrOpenExchangePublicStore function. This function call returns an lpMDB pointer to the open store, which also gives you access to the MAPI IMsgStore interface.
  2. Use the IMAPIProp::GetProps method to read the PR_IPM_FAVORITES_ENTRYID property, which contains the entry identifier of the Favorites folder.
  3. Open the Favorites folder within the public information store by calling the MAPI IMsgStore::OpenEntry method. In this function call, pass the entry identifier of the folder in the lpEntryID parameter.
To open the Favorites folder using HrMAPIOpenFolderEx

Open the Favorites folder by calling the HrMAPIOpenFolderEx function. In this function call, pass the entry identifier of the Favorites folder as follows: @PR_IPM_FAVORITES_ENTRYID.

For a list of other entry identifiers for special folders, see Entry Identifiers of Special Folders.


Adding a Public Folder to Favorites

You can add one or more public folders to a user’s Favorites folder by calling the IExchangeFavorites::AddFavorites method. Before you call this method, you must prepare an ENTRYLIST structure to list the public folders to be added.

For more information about ENTRYLIST structures, see the MAPI Programmer’s Reference.

To add one or more public folders to a user’s Favorites folder
  1. Open the public information store by calling the HrOpenExchangePublicStore function. This function call returns an lpMDB pointer to the open store, which also gives you access to the MAPI IMsgStore interface.
  2. Use the IMAPIProp::GetProps method to read the PR_IPM_FAVORITES_ENTRYID property, which contains the entry identifier of the Favorites folder.
  3. Open the Favorites folder within the information store by calling the MAPI IMsgStore::OpenEntry method. In this function call, pass the entry identifier of the folder in the lpEntryID parameter. This call returns a pointer to the IExchangeFavorites interface.
  4. Call the HrMAPICreateEntryList function to create an entry list of folders to add.
  5. Call the IExchangeFavorites::AddFavorites method, which adds one or more public folders as specified in the ENTRYLIST structure.


Deleting a Public Folder from Favorites

You can delete one or more public folders from a user’s Favorites folder by calling the IExchangeFavorites::DelFavorites method. Before you call it, you must prepare an ENTRYLIST structure to list the public folders to be deleted. For more information about ENTRYLIST structures, see the MAPI Programmer’s Reference.

To delete one or more public folders from a user’s Favorites folder
  1. Open the public information store by calling the HrOpenExchangePublicStore function. This function call returns an lpMDB pointer to the open store, which also gives you access to the MAPI IMsgStore interface.
  2. Use the IMAPIProp::GetProps method to read the PR_IPM_FAVORITES_ENTRYID property, which contains the entry identifier of the Favorites folder.
  3. Open the Favorites folder within the information store by calling the MAPI IMsgStore::OpenEntry method. In this function call, pass the entry identifier of the folder in the lpEntryID parameter. This call returns a pointer to the IExchangeFavorites interface.
  4. Call the HrMAPICreateEntryList function to create an entry list of folders to delete.
  5. Call the IExchangeFavorites::DelFavorites method, which deletes one or more public folders as specified in the ENTRYLIST structure.


Working with Offline Folders

Offline folders are a feature of Microsoft Exchange Server that makes public folders and mailbox messages available to users when they work offline. Folders configured for offline availability are stored in a file with the .OST extension on the user's disk. When users log on to their home server and the network connection is reestablished, Microsoft Exchange Server automatically synchronizes the offline copy of the folder that it stored locally on the client computer with the copy on the server computer. This type of synchronization is known as local replication.

If a user has configured an offline folder identical copies of this folder exist in the information store on the server and in the OST file. When an application writes to this folder, it does not specify — nor need to know — whether the folder is currently online or offline. If the application is online, it writes to the online (server) copy of the folder. If the application is offline, it writes to the offline (OST) copy. This mechanism is automatic and is controlled by the information store.

When the offline information store is synchronized, its entire hierarchy table (including the user’s Favorites folders and the user’s private information store) is synchronized. Folders not designated as offline folders are also synchronized, but those folders cannot be written to and have an empty contents table when the computer is offline.

If both the offline information store and the information store on the server have changed at the time they are synchronized, changed data on the OST is first copied to the server, and then changed data on the server is copied to the OST. If this is an automatic synchronization — that is, it is occurring because the user has reconnected to the server — data is copied in only one direction from the OST to the server, regardless of whether data on the server has changed.

If an information store is offline, it contains the PR_STORE_OFFLINE property, which is set to TRUE.

An offline folder is permanently available if it was created while the computer was offline. If the folder was created while the computer was online, it will be available offline only if the user designates it as an offline folder.

For more information, see Offline Folders and RTF-Awareness.


Reading Messages in a Folder

Before you can open messages in a folder, you must open the information store and the folder itself. See Opening an Information Store, Opening an Existing Public Folder, and Opening an Existing Private or Personal Folder.

To read the messages in a folder
  1. Open the folder contents table, using the IMAPIFolder::GetContentsTable method.
  2. Set the columns of the contents table to specify which properties are to be retrieved for each message. One of the properties to retrieve is PR_ENTRYID because you will use it in step 4. .
  3. Query the contents table by calling the MAPI HrQueryAllRows function or the IMAPITable::QueryRows method.
  4. Open a message with a call to the MAPI OpenEntry method.
  5. After opening the message, you can choose to indicate that the message has been read.

The following sample code illustrates these steps.

// Open folder contents table.
hr = lpFolder->GetContentsTable(
    MAPI_DEFERRED_ERRORS,
    &lpFolderTable);

// Here we're primarily interested in ENTRYIDs, and wish to sort by submission time.
    static SizedSPropTagArray( 1L, PropEntryID) = { 1L, {PR_ENTRYID}};
    static SizedSSortOrderSet( 1L, SortSubmitTime) =
    { 1L, 0L, 0L, { PR_CLIENT_SUBMIT_TIME, TABLE_SORT_ASCEND}};

// Read table.  If you perform this action inside a loop, you may
   wish to use the MAPI
// SetColumns and SortTable functions before this call.  They only
   need to be performed
// once when the contents table is retrieved.
hr = HrQueryAllRows(
    lpFolderTable,
    (LPSPropTagArray)&PropEntryID,
    NULL,           // no restriction
    (LPSSortOrderSet)&SortSubmitTime,
    NULL,
    0L,
    &lpMessageRows);

// Read rows one at a time
ULONG i = 0L;
ULONG ulObjType = 0L;
LPMESSAGE lpMessage = NULL;
for (i = 0L; i < lpMessageRows->cRows; i++)
{
    // Open the message
    hr = lpFolder->OpenEntry(
        0L,
        lpMessageRows->aRow[i].lpProp[0].bin.cb,
        lpMessageRows->aRow[i].lpProp[0].bin.lpb,
        NULL,
        MAPI_MODIFY | MAPI_DEFERRED_ERRORS,
        &ulObjType,
        (LPUNKNOWN*)&lpMessage);

    // Indicate this message has been read
    hr = lpMessage->SetReadFlag( MAPI_DEFERRED_ERRORS);

    //
    // Perform message processing here...
    //

    // Delete the message
    hr = lpFolder->DeleteMessage(
        lpMessageRows->aRow[i].lpProp[0].bin,
        0L,
        NULL,
        0L);
}


Manipulating ACLs

You can use either the IExchangeFolderACLs interface or the IExchangeModifyTable interface to add, delete, and edit members of an access control list (ACL).

The IExchangeFolderACLs Interface

The IExchangeFolderACLs interface is built on the IExchangeModifyTable interface. It is the preferred interface because it is specifically designed to simplify the task of working with ACLs. To get a pointer to this interface, call the HrFolderACLsOpen function on the folder to which the ACLs apply. This interface contains the following methods:

IExchangeFolderACLs::HrDelete

IExchangeFolderACLs::HrGet

IExchangeFolderACLs::HrInsert

IExchangeFolderACLs::HrModify

IExchangeFolderACLs::HrSeek

IExchangeFolderACLs::HrTell

The IExchangeModifyTable Interface

An ACL is a MAPI table, which means it can be accessed through the IExchangeModifyTable interface. To obtain IExchangeModifyTable, call the IMAPIProp::OpenProperty method on any property of type PT_OBJECT. This interface contains the following methods:

IExchangeModifyTable::GetLastError

IExchangeModifyTable::GetTable

IExchangeModifyTable::ModifyTable

For general information on ACLs, see About Access Control Lists.


Reading ACLs

You can use the IExchangeFolderACLs::HrSeek and IExchangeFolderACLs::HrGet methods to read existing ACLs from a folder’s ACL table. The HrGet method retrieves the access rights for the current member of the ACL table.

To read an ACL table
  1. Retrieve an interface pointer to the ACL object using HrFolderACLsOpen.
  2. Use the ACL object’s IExchangeFolderACLs::HrSeek method to seek to the beginning of the table.
  3. Use the ACL object’s IExchangeFolderACLs::HrGet method within a loop to step through the ACL table, reading successive ACL entries. (HrGet automatically advances the table cursor to point to the next table entry after each call.)


Modifying ACLs

The following procedure describes how to change one existing entry in an ACL table.

To modify an ACL
  1. Retrieve an interface pointer to the ACL object by calling the HrFolderACLsOpen function.
  2. Use the ACL object’s IExchangeFolderACLs::HrSeek method to seek to the beginning of the table.
  3. Use the ACL object’s IExchangeFolderACLs::HrGet method within a loop to step through the ACL table. Stop when you reach the ACL to be modified. You can recognize the correct ACL table entry by examining the returned user display name and user entry identifier.
  4. Call the ACL object’s IExchangeFolderACLs::HrModify method to set the access rights for the current member of the ACL table. In this function call, pass the lRights parameter to specify the rights you are requesting for the current member of the ACL.


Adding a New ACL Member

You can insert a user as a new member of the ACL table and insert a set of access rights for that user with the IExchangeFolderACLs::HrInsert method.

To add a new ACL member
  1. Retrieve an interface pointer to the ACL object using HrFolderACLsOpen.
  2. Open the address book and get the entry identifier of the user whose access rights you are adding to the ACL. First, open the address book by calling the IMAPISession::OpenAddressBook method. Then, to obtain the user’s entry identifier, call the IAdrBook::ResolveName method.
  3. Call the ACL object’s IExchangeFolderACLs::HrInsert method to insert a user as a new member of the ACL table. This call also inserts a set of access rights for that user. In this call, pass the rights requested for the new member in the lRights parameter, and the user’s entry identifier obtained in step 2 in the lpentryid parameter.

For an example of this procedure, see the bDoInsert function in the \BKOFFICE\SAMPLES\EXCHANGE\ACLEDIT\ACLEDIT.CPP source file.


Working with Rules

You can use either the IExchangeFolderRules interface or the IExchangeModifyTable interface to add, delete, and edit rules on folders.

The IExchangeFolderRules Interface

The IExchangeFolderRules interface is built on the IExchangeModifyTable interface. It is the preferred interface because it is specifically designed to simplify the task of working with rules. To get a pointer to this interface, call the HrFolderRulesOpen function on the folder to which the rules apply. This interface contains the following methods:

IExchangeFolderRules::HrDelete

IExchangeFolderRules::HrDisable

IExchangeFolderRules::HrEnable

IExchangeFolderRules::HrGet

IExchangeFolderRules::HrInsert

IExchangeFolderRules::HrSeek

IExchangeFolderRules::HrTell

The IExchangeModifyTable Interface

Rules are stored in MAPI tables and as such can be accessed through the IExchangeModifyTable interface. To obtain this interface, call the IMAPIProp::OpenProperty method on any property of type PT_OBJECT. This interface contains the following methods:

IExchangeModifyTable::GetLastError

IExchangeModifyTable::GetTable

IExchangeModifyTable::ModifyTable

For general information on rules, see About Rules. For information on specific tasks you can perform to manipulate rules, see the following:

Creating a Rule

Reading Rule Contents

Modifying Rules


Creating a Rule

To create a rule, prepare its contents and insert the new rule in the rule table.

To create a rule
  1. Retrieve an interface pointer to the rule object by calling HrFolderRulesOpen.
  2. Find the position in the rule table where you want to insert the rule. Use the rule object’s IExchangeFolderRules::HrSeek method to seek to the correct position.
  3. Call the HrStringToRestriction function to prepare the restriction (the conditions) for the new rule. This function returns a pointer to an SRestriction structure that contains the restriction.
  4. Call the HrStringToAction function to prepare and obtain a pointer to the ACTION structure for the new rule.
  5. Create the new rule by calling the IExchangeFolderRules::HrInsert method. This method inserts a new rule into the set of rules for the folder.

For an example of rule insertion, see the DoDelete function and the DoInsert function in the \BKOFFICE\SAMPLES\EXCHANGE\RULEEDIT\RULEEDIT.CPP file.


Reading Rule Contents

The following procedure describes how to read the contents of a rule within the rule table.

To read a rule table
  1. Retrieve an interface pointer to the rule object using HrFolderRulesOpen.
  2. Use the rule object’s IExchangeFolderRules::HrSeek method to seek to the beginning of the table.
  3. Use the rule object’s IExchangeFolderRules::HrGet method within a loop to step through the rule table, reading successive rule entries. (HrGet automatically advances the table cursor to point to the next table entry after each call.)


Modifying Rules

To modify a rule, find the rule you want changed, save and edit its contents, delete it, and insert the new rule in the old rule’s position in the rule table.

To modify a rule
  1. Retrieve an interface pointer to the rule object using HrFolderRulesOpen.
  2. Find the rule you want to modify. First, use the rule object’s IExchangeFolderRules::HrSeek method to seek to the beginning of the rule table.
  3. Within a loop, call the rule object’s IExchangeFolderRules::HrGet method to step through the rule table until you find the rule you want to modify.
  4. Save the information of the rule to be modified. You can do this as a part of the loop described in step 3 because HrGet returns all the information of the rule, including pointers to an SRestriction structure and an ACTIONS structure. The SRestriction structure contains the rule’s conditions. The ACTIONS structure contains the rule’s actions.
  5. Modify the saved information to reflect the rule changes you want to make. You will be modifying data of a variety of types.
  6. Back the cursor up by 1 by calling the IExchangeFolderRules::HrTell method (to determine the absolute position in the rule table) and the IExchangeFolderRules::HrSeek method (to move to the next lower position).
  7. Delete the rule you want to modify by calling IExchangeFolderRules::HrDelete. For HrDelete, the cursor is unchanged. If you delete a rule and then insert a rule, the new rule goes back in the same position.
  8. Create a new rule with the IExchangeFolderRules::HrInsert method. This method inserts the rule into the set of rules for the folder.

To review these methods, see the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\RULECLS\RULECLSI.CPP source file. For examples of rule deletion and rule insertion, see the DoDelete function and the DoInsert function in the \BKOFFICE\SAMPLES\EXCHANGE\RULEEDIT\RULEEDIT.CPP file.


The Incremental Change Interface

The incremental change synchronization (ICS) interface provides a mechanism for monitoring and synchronizing changes to an information store’s hierarchy or content. Examples of its use include:

  • List information store changes. You can then use this list to build an index for users or to archive change information.
  • Gather information store changes for replication to systems other than Microsoft Exchange Server, such as a SQL database.

Incremental change synchronization is used by the local replication features of Microsoft Exchange Server.

As explained in About Incremental Change Synchronization, three software components are used with the incremental change interface: the agent, the collector, and the synchronizer. When replicating data to a system other than Microsoft Exchange Server, you will need to program a collector and a synchronizer designed specifically to work with the target system, as well as an agent that runs in the Microsoft Exchange Server environment.


Handling Message Conflicts

Because public folders and the messages they contain can be replicated to multiple servers, users can edit replicated copies of the same message on different locations. A message conflict arises at the time of the next replication. When Microsoft Exchange Server detects a message conflict, it takes actions to resolve the conflict. The specific actions taken are determined by the value of the PR_RESOLVE_METHOD folder property, which is set on the folder that contains the message in conflict.


Specifying the Resolution Method with PR_RESOLVE_METHOD¦

Microsoft Exchange Server handles message conflicts in one of three ways, as determined by the value of the PR_RESOLVE_METHOD property. This behavior is the same for message conflicts of any type, even if the message is controlled by a custom form. The values of PR_RESOLVE_METHOD are defined in the EDKMDB.H file.

Because PR_RESOLVE_METHOD is not initialized on folder creation, it may not be present on a given folder. In this case, the information store’s default behavior is RESOLVE_METHOD_DEFAULT.

Microsoft Exchange Server handles message conflicts in three ways:

  • Default conflict resolution
  • Last writer wins
  • No conflict notification

Default Conflict Resolution

If PR_RESOLVE_METHOD is set to RESOLVE_METHOD_DEFAULT, Microsoft Exchange Server does the following:

  • Saves the newer message into the public folder.
  • Sets the MSGSTATUS_IN_CONFLICT bit in the PR_MSG_STATUS property of the newer message.
  • Attaches a copy of each conflicted version (including the newest version and all older versions) of the message to the newest message.
  • Attaches older messages to the newer message because there may be more than two messages in the case of a complex conflict.
  • Sets to TRUE the PR_IN_CONFLICT property on the attached messages.
  • Notifies both the modifiers of the message and the contacts defined on the folder by sending a conflict notification message. This message is of the message class IPM.Conflict.Message, which displays as a standard conflict notification form at the client. This form displays a button that, if pressed, displays and opens the conflict message for the user. The conflict message is only sent from the server computer on which the folder was created. Until the conflict replication reaches that computer, no notifications are sent.

Last Writer Wins

If PR_RESOLVE_METHOD is set to RESOLVE_METHOD_ LAST_WRITER_WINS, Microsoft Exchange Server saves the newer message.

No Conflict Notification

If PR_RESOLVE_METHOD is set to RESOLVE_METHOD_ NO_CONFLICT_NOTIFICATION, Microsoft Exchange Server performs the same steps as if the RESOLVE_METHOD_DEFAULT flag is set, except that it does not notify the contacts defined on the folder and the modifiers of the message.

Note The PR_RESOLVE_METHOD property determines the resolution method only for conflicts on messages in the folder’s contents table. Conflicts on the contents of the folder associated information (FAI) table are always resolved with the Last Writer Wins method.


Resolving the Message Conflict

Once the server has performed the necessary actions, the actual conflict can be resolved. This can happen three different ways:

  • A user resolves the conflict
  • A custom form resolves the conflict
  • A mailbox application resolves the conflict

A User Resolves the Conflict

As a conflict message is opened, the Microsoft Exchange Client detects the MSGSTATUS_IN_CONFLICT flag on the message and launches its standard conflict resolution note. This allows the user to open the attached conflicting messages and select the winner of the conflict or combine the data in the different versions to reconcile them. The value of MSGSTATUS_IN_CONFLICT is defined in the EDKMDB.H file.

A Custom Form Resolves the Conflict

If the form server for the message class is registered as one that can handle its own conflicts, the client does not launch the standard conflict resolution form. Instead, it launches the form registered for the message class as normal. It is then up to the form’s code to either reconcile the conflict itself (as described in Automatic Conflict Resolution) or display the conflict to the user using its own user-interface semantics,so the user can do the reconciliation. For more information on registering a form for conflict resolution, see Resolving Message Conflicts with Forms.

A Mailbox Application Resolves the Conflict

A mailbox application establishes itself as a public folder contact that can receive conflict notification messages. In this case, the conflict notification message will be mailed directly to the application. Conflict notification messages can be easily identified because they have the message class IPM.Conflict.Message.

The application opens the PR_CONFLICT_ENTRYID property on any notification message to find the original conflict message that contains (as attachments) the conflicting versions of the message. At this point, the mailbox application proceeds as described in Automatic Conflict Resolution.

In the time before an application receives and processes the conflict notification, either of the other resolution methods (described in A User Resolves the Conflict or A Custom Form Resolves the Conflict) might have occurred. Therefore, the mailbox application should be prepared for the possibility that the conflict has already been resolved.

Note The latency inherent in a replication schedule can cause special circumstances. If multiple applications resolve a conflict before the next replication, a new conflict is the result. Also, until a conflict resolution is replicated throughout the entire system, the conflict remains visible to users and applications. At this point, new attempts to resolve the conflict may cause further conflicts.


Automatic Conflict Resolution

Once a conflict message has been identified, an application or form can resolve the conflict as follows:

  1. It locates the attachments in conflict by reading the PR_IN_CONFLICT property on the attachment table.
  2. It resolves the conflict between these attachments in one of two ways:
    • It can select the winning message based on almost any criteria.
    • It can merge the contents of the messages in conflict.
  3. Using the MAPI IMAPIProp::CopyTo method, it copies the resolved properties to the main message (the message to which conflicting messages are attached). Then, the attachments are deleted.

When all conflicting message attachments are deleted and changes are saved, Microsoft Exchange Server automatically clears the message’s MSGSTATUS_IN_CONFLICT bit. You do not need to programmatically reset this bit after the conflicting message attachment is deleted.


Using OLE Documents

Microsoft Exchange Server uses OLE to let users drag documents into information store folders. This action may be taken from locations such as the desktop, the Windows NT Explorer, and the Windows 95 Explorer. This mechanism uses the OLE concept of document objects. For more information on OLE document objects and their property sets, see the COM and ActiveX Object Services section of the Platform SDK.

The Microsoft Exchange Client displays a set of properties about a document according to the current user-defined view. For example, if a Total field in a Microsoft Excel worksheet is published as an OLE document object property, then this worksheet is dragged into a Microsoft Exchange Server public folder, it will be displayed by the client if the Total field is an element of the current view.

Microsoft Exchange clients can create objects for documents dragged into folders, display these objects, and start their native applications. The sequence of actions performed by a Microsoft Exchange Client for each of these tasks is defined as follows:

To create a document object
  1. The user drags a document into a folder displayed by the client.
  2. The client creates a message and attaches the document to the message as a MAPI attachment.
  3. The client opens an IStorage interface on the document and reads property-set streams.
  4. The client reads OLE document object properties (such as summary properties) from the document object and creates equivalent MAPI properties on the message.
  5. The client sets the message class to IPM.Document.*xxx, where xxx is the file extension (if any) associated with the application.
To display a document object

As a result of the previous steps, the OLE document object properties now exist as MAPI properties on a message, which the client displays in user-defined views. If the current view includes Item Type, the client displays an appropriate icon for the document. The icon to be used is determined by using the message class IPM.Document.*xxx. For example, the client displays a Microsoft Excel icon if the message class is IPM.Document.*XLS.

To open a document
  1. The user double-clicks the icon of a document.
  2. The client uses the message class to determine how to display the message. First, if the message class is IPM.Document.*xxx, the client knows it is a message with an attachment to be opened. In contrast, if the message class is IPM.Note, the client displays it as an e-mail message. An attachment, if any, is not opened immediately.
  3. The client locates the attachment and requests that Windows open the document by activating the application with which it is associated.

Third-party client applications can use OLE to perform these same functions. A client application can also use OLE interfaces and document-object properties to write attachment documents into a Microsoft Exchange Server information store.


Working with Messages

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. Every message supports many properties; some that describe the message, some that describe its contents, some that describe transmission options, and some that describe recipients.

Messages are stored in folders within an information store, typically folders created within the Interpersonal Message (IPM) root folder. The message object represents a single message, item, document, or form in a folder.

Every message has a message class property, PR_MESSAGE_CLASS, which identifies the type, purpose, or content of the message. A message's class determines the form that is used to present the message to the user and the folder for placing incoming messages.


Creating a Message

When creating a new message, some message properties are required and others are optional. For example, it is important that you set the PR_MESSAGE_CLASS property of the message. See step 3 of the following procedure.

For a list of message properties that are automatically set, see Properties Set at Message Creation.

To create a message
  1. Open the folder in which you want the new message to exist. See Opening an Existing Public Folder and Opening an Existing Private or Personal Folder.
  2. Create a new message with a call to the IMAPIFolder::CreateMessage method. This creates the message object and returns an LPMESSAGE pointer to it, which gives access to the MAPI IMessage interface on the new object.
  3. Be sure to set the PR_MESSAGE_CLASS property. You can set this and other properties on the message by calling IMAPIProp::CopyProps or IMAPIProp::SetProps.
  4. Commit the properties you have set by calling IMAPIProp::SaveChanges. The message will appear in the folder in which it was created.

The following sample code illustrates these steps:

    // Create new message with MAPI call...
        hr = lpNewFolder->CreateMessage(
        NULL,        // Interface ID, must be NULL for client apps
        MAPI_DEFERRED_ERRORS,
        &lpNewMessage);

// Set appropriate message properties.  Here's a list of the most common...
    // PR_SENDER_NAME,
    // PR_SENDER_ENTRYID,
    // PR_SENDER_ADDRTYPE,
    // PR_SENDER_EMAIL_ADDRESS,
    // PR_SENT_REPRESENTING_NAME,
    // PR_SENT_REPRESENTING_ENTRYID,
    // PR_SENT_REPRESENTING_ADDRTYPE,
    // PR_SENT_REPRESENTING_EMAIL_ADDRESS,
    // PR_CLIENT_SUBMIT_TIME,
    // PR_MESSAGE_DELIVERY_TIME,
    // PR_IMPORTANCE,
    // PR_EXPIRY_TIME,
    // PR_MESSAGE_ATTACHMENTS,
    // PR_RTF_COMPRESSED or PR_BODY
    // PR_SUBJECT
    // PR_MESSAGE_CLASS

    // SaveChanges commits the current state of the message.
    // Must use KEEP_OPEN_READWRITE or KEEP_OPEN_READONLY if you
    // intend to access the message later.
    hr = lpNewMessage->SaveChanges( KEEP_OPEN_READWRITE );

Note The maximum number of messages that a folder in a personal folder store (PST) can hold is 16,383. Once this number has been reached, an attempt to create another message in the folder results in the error MAPI_E_TABLE_TOO_BIG being returned by the call to the IMAPIProp::SaveChanges method.


Creating and Posting a Message

Posting messages and documents to folders (as opposed to sending messages) is a common action performed by client applications. For example, a client application may post information to a public folder as a way of allowing the associated server application to read the information.

The message class for a posted message (IPM.POST) differs from the message class for a message to be sent (IPM.NOTE). It is important that this property be set in the message. See step 3 in the following procedure.

To post a message
  1. Open the folder in which you want the new message to exist. See Opening an Existing Public Folder and Opening an Existing Private or Personal Folder.
  2. Create a new message with a call to the IMAPIFolder::CreateMessage method. This creates the message object and returns a pointer (LPMESSAGE) to it, which gives access to the MAPI IMessage interface on the new object.
  3. Set the PR_MESSAGE_CLASS property to IPM.POST. Set this and other properties on the message by calling IMAPIProp::CopyProps or IMAPIProp::SetProps. Some properties are required and others are optional. For a list of message properties that are automatically set, see Properties Set at Message Creation.
  4. Optionally, you can use the MAPI IMessage::SetReadFlag method to set (or clear) the read flag of the message so that it displays as read or unread.
  5. Commit the properties you have set by calling IMAPIProp::SaveChanges. The message will appear in the folder in which it was created.


Adding Custom Properties to a Message

Information store providers that need to extend property sets typically implement the IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs methods for message objects. Other interfaces derived from IMAPIProp typically return MAPI_E_NO_SUPPORT for calls to these methods.

Once the property exists, you can use the IMAPIProp::SetProps method to to change its value.

To add custom properties to a message
  1. Open a message by calling IMAPISession::OpenEntry.
  2. Create the custom property using IMAPIProp::GetIDsFromNames, passing an LPMAPINAMEID and the MAPI_CREATE flag. This call allocates a property identifier for each named property not registered in the name-to-identifier mapping table and internally registers the identifier in this table.
  3. Save the property on the message by calling IMAPIProp::SaveChanges or IMessage::SubmitMessage.

The following sample code converts a string to Unicode and searches in the name-to-identifier mapping table for previously registered properties. It creates a custom property if it does not already exist, and returns the property tag of the new property:

HRESULT ProptagFromString(
    IN LPMAPIFOLDER lpFolder,
    IN LPSTR lpszPropName,
    IN ULONG ulPropType,
    OUT ULONG *pulPropTag)
{
    HRESULT        hr        = NOERROR;
    MAPINAMEID        nameid        = {0};
    MAPINAMEID        *rgpnameid[1]    = {&nameid};
    WCHAR        rgwch[128]    = {0};
    LPSPropTagArray    lpSPropTags    = NULL;

    // Convert property tag string to Unicode
    MultiByteToWideChar(
        CP_ACP,
        MB_PRECOMPOSED,
        lpszPropName,
        -1,
        rgwch,
        sizeof(rgwch));

    nameid.lpguid = (GUID*)&PS_PUBLIC_STRINGS;
    nameid.ulKind = MNID_STRING;
    nameid.Kind.lpwstrName = rgwch;

    hr = MAPICALL( lpFolder)->GetIDsFromNames( lpFolder,
        1,        // number of property tags to look up
        rgpnameid,
        MAPI_CREATE,
        &lpSPropTagsT);
    if ( FAILED(hr))
    {
        hr = HR_LOG( E_FAIL);
        goto cleanup;
    }

    // Success!
    *pulPropTag = lpSPropTags->aulPropTag[0];

     // Change PT_UNSPECIFIED to the type required by the user
    *pulPropTag = PROP_TAG( ulPropType, PROP_ID(*pulPropTag));

cleanup:
    MAPIFREEBUFFER( lpSPropTags);

    RETURN( hr);
}


Sending a Message

When submitting a new message, the list of recipients must contain at least one entry. This is accomplished in steps 2 and 3.

To send a message
  1. Create the message to be sent. See Creating a Message.
  2. Using the HrMAPICreateAddressList function, create and set the values of a recipient list, which is an LPADRLIST structure. This list contains all the TO, CC, and BCC recipients of the message.
  3. Modify the recipient list of the message by calling the MAPI IMessage::ModifyRecipients method.
  4. Optionally, set the PR_MESSAGE_CLASS and PR_DELETE_AFTER_SUBMIT properties.
  5. Submit the message by calling the IMessage::Submit method.

The following sets addressing information on an existing message, and submits it:

// These calls create and set information in the address list data structure.
hr = HrMAPICreateAddressList( cProps, lpAdrProps, &lpAdrList);

// If you copy address information from another message, these
    properties have the same values:
// New address property         was Property in message
// PR_DISPLAY_NAME was     PR_SENDER_NAME
// PR_ENTRYID     was PR_SENDER_ENTRYID
// PR_ADDRTYPE was PR_SENDER_ADDRTYPE
// PR_EMAIL_ADDRESS was     PR_SENDER_EMAIL_ADDRESS
//
// Also, the recipient's PR_RECIPIENT_TYPE must be MAPI_TO, MAPI_CC, or MAPI_BCC

// Update the message with list of addressees.
hr = lpNewMessage->ModifyRecipients( 0L, lpAdrList);

hr = HrMAPISetPropBoolean( lpNewMessage, PR_DELETE_AFTER_SUBMIT, TRUE);

// Last step: submit the message.
hr = lpNewMessage->Submit( 0L);


Working with Text in Rich Text Format

The body of a message in a Microsoft Exchange Server information store is kept in the PR_RTF_COMPRESSED property. As the name implies, this property contains compressed text that includes rich text formatting information. For this reason, the body of any message that will at some time be stored in a Microsoft Exchange Server information store or transmitted by Microsoft Exchange Server can most efficiently be stored in this property and not, for example, in the PR_BODY property. This section describes various ways to work with text contained within or destined for the PR_RTF_COMPRESSED property.


RTF-Awareness

An information store is known as RTF-aware if it keeps the body and the RTF text of a message synchronized. The server information store and the offline folder store (OST) are RTF-aware and the personal folder store (PST) is not RTF-aware.

The MAPI RTFSync function synchronizes PR_BODY and PR_RTF_COMPRESSED, ensuring that the rich text format body of a message matches the plain text body. You call this function before reading the RTF body and after modifying the RTF body. This is necessary for when working with the PST. For the server information store and the OST, you do not need perform this extra step. For information about RTF-awareness in message stores, see the MAPI Programmer's Reference.


Saving ANSI Text as a Message Property in RTF

Follow this procedure if the original text contains ANSI characters with no RTF formatting. The purpose of this task is to produce a valid PR_RTF_COMPRESSED property on a message. You must start with a message that does not already contain a PR_RTF_COMPRESSED property. This can be either an existing message or a new message.

To save ANSI text into PR_RTF_COMPRESSED
  1. Open the destination message object with a call to the IMAPIFolder::CreateMessage method (for a new message) or IMAPIFolder::OpenEntry (for an existing message). This call returns an LPMESSAGE pointer to a message object.
  2. Open a stream to the ANSI text to be saved.
  3. Call the HrTextToRTFCompressed function, passing a pointer (LPMESSAGE) to the destination message. This function reads text from the open stream and writes the text to the PR_RTF_COMPRESSED property, simultaneously compressing the text.


Saving RTF Text as a Message Property in RTF

In this case, you are starting with text already in RTF format—perhaps produced by a rich text editor—and you want to save this RTF text into a valid PR_RTF_COMPRESSED property on a message. You must start with a message that does not already contain a PR_RTF_COMPRESSED property. This can be either an existing message or a new message.

To save RTF text into PR_RTF_COMPRESSED
  1. Open the destination message object with a call to the IMAPIFolder::CreateMessage method (for a new message) or IMAPIFolder::OpenEntry (for an existing message). This call returns an LPMESSAGE pointer to a message object.
  2. Create the PR_RTF_COMPRESSED message property with a call to the IMAPIProp::OpenProperty method. In this function call, pass the LPMESSAGE pointer to the destination message object, the IID_IStream interface identifier in the lpiid parameter, and the MAPI_CREATE and MAPI_MODIFY flags in the ulFlags parameter.
  3. Call the MAPI WrapCompressedRTFStream function. This call returns an unwrapped (uncompressed) stream on the PR_RTF_COMPRESSED property.
  4. Write the original RTF data to the uncompressed stream, using the IStream::CopyTo or IStream::Write methods.
  5. Call IStream::Commit on the uncompressed stream. This call saves the property in compressed format.


Retrieving ANSI Text from a Message Property in RTF

Retrieving ANSI text from the PR_RTF_COMPRESSED message property is unnecessary, because message text is also stored in the PR_BODY property, which is either null-terminated wide string data or null-terminated 8-bit character string data. For this reason, you can retrieve the text you need by opening the message and reading this property.

To retrieve ANSI text
  1. Call IMAPIFolder::OpenEntry on the message that contains the text in RTF format. This call creates a message object and returns a pointer (LPMESSAGE) to the message object.
  2. Call IMAPIProp::GetProps to read the PR_BODY property of the message.


Privileged Access To Mailboxes

Applications you develop for Microsoft Exchange Server may need to dynamically access multiple mailboxes. These types of applications are sometimes referred to as privileged services because they must be granted special privileges by a Microsoft Exchange Server administrator.


Why Special Functions are Needed

Even if a service is somehow able to obtain a user’s account name and password, it still cannot access the user’s mailbox using the MAPILogonEx function. This is because MAPILogonEx requires a profile, and the service does not necessarily have access to the profiles of all its users. Therefore, even if a voice mail application is designed so that users enter their username and password over the telephone, the user’s profile is not be available.


Setting Up a Profile for Privileged Access

As illustrated in the MBLSAMPL sample application, the minimum required permissions to log on with privileged access is Logon Rights for each mailbox in the site you want to view. To ensure that you have this permission, add a Windows NT account with at least a View Only Admin role in the Microsoft Exchange Server Administrator program for the site. No specific user rights are required on Windows NT Server.


Running an Application as a Privileged Service

To run an application as a privileged service, create an object for it in the directory and make sure you can run it as a service of Windows NT Server.

To run your application as a privileged service
  1. Create a Mailbox-Agent object for the service in the Microsoft Exchange Server directory. To do this, import a Mailbox-Agent object with a call to the DAPIWrite or BatchImport function.
  2. Load the service by calling the HrInstallService function, which writes information about the service into the Windows NT Registry.
  3. Create and configure a profile for the service.
  4. A Windows NT Server administrator must assign the Log on as a service right to the Windows NT account belonging to the service. It is not necessary to give administrator privileges to the service on Windows NT Server.
  5. A Microsoft Exchange Server administrator must grant administrator privileges to the service for the Microsoft Exchange Server site in which the service will operate. The application must have these permissions for access to multiple mailboxes.


Logging On to Mailboxes

You can write programs that log on to and manage Microsoft Exchange Server mailboxes and public folders in two ways:

  • Use the HrMailboxLogon mailbox logon function. This wrapper function is located in \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\MBLOGON\MBLOGON.C. The MBLSAMPL sample application uses this function and is located in BKOFFICE\SAMPLES\EXCHANGE\MBLSAMPL\MBLSAMPL.C. HrMailboxLogon wraps the methods of the IExchangeManageStore interface.
  • Use the IExchangeManageStore interface itself to manipulate mailboxes directly. The IExchangeManageStore interface is used by the wrapper functions in MBLOGON.C.

Using the Microsoft Exchange Server mailbox wrapper function to perform basic logon operations for mailboxes is recommended. They implement low-level details of managing mailboxes and can save you time.


Logging On to a Mailbox as a Privileged Service

The HrMailboxLogon and HrMailboxLogoff functions are designed to simplify the task of performing basic mailbox management. The sample code in the following section shows how to implement the two functions listed.

To log on to a mailbox as a privileged service
  1. Open the default information store or another information store. For more information, see Opening an Information Store. This action creates the information store object and returns a LPMDB pointer to it.
  2. Call the HrMailboxLogon function. The following sample code shows how to log on to a mailbox using the HrMailboxLogon function. (For more granular control, use the IExchangeManageStore interface. See Using the IExchangeManageStore Interface.)

The full source code for this sample application is located in BKOFFICE\SAMPLES\EXCHANGE\MBLSAMPL\MBLSAMPL.C. For clarity, error handling is not included in this code sample.

// --------------------------------------------------------------
// Opening a mailbox using privileged access - without error detection.
// --------------------------------------------------------------

AnyFunction()
{
    LPTSTR          lpszProfileName = "Admin Profile";
    LPTSTR          lpszPassword    = NULL;
    LPTSTR          lpszServer      = "/O=Organization/OU=Site/CN=Servers/CN=ServerName/CN=NULL";
    LPTSTR          lpszMailbox     = "/O=Organization/OU=Site/CN=Recipients/CN=MailboxName";
    LPMAPISESSION   lplhSession     = NULL;
    LPMDB           lpMDB           = NULL;     // Ptr to default msg store interface.
    LPMDB           lpMailboxMDB    = NULL;     // Ptr to any another's msg store interface.
    ULONG           cbeid           = 0;
    LPENTRYID       lpeid           = NULL;

    MAPIInitialize( NULL);

    MAPILogonEx( 0, lpszProfileName, lpszPassword,
                 MAPI_NEW_SESSION | MAPI_LOGON_UI | MAPI_EXTENDED, &lplhSession);

    HrMAPIFindDefaultMsgStore( lplhSession, &cbeid, &lpeid);

    MAPICALL( lplhSession)->OpenMsgStore( lplhSession, 0, cbeid, lpeid,
              NULL, MDB_NO_DIALOG | MAPI_BEST_ACCESS, &lpMDB);

    HrMailboxLogon( lplhSession, lpMDB, lpszMsgStoreDN, lpszMailboxDN, &lpMailboxMDB);

    // Now lpMailboxMDB contains the MAPI interface needed to access the mail box requested.
    ...
}


Using the IExchangeManageStore Interface

If your application goes beyond the basic steps of logging on to mailboxes, you may want to use the IExchangeManageStore interface directly instead of using the HrMailboxLogon and HrMailboxLogoff mailbox logon functions. Using this interface, a caller with appropriate permissions can obtain an entry identifier of any mailbox in the private information store. The returned entry identifier can then be used to open the mailbox, read mail, and send mail through standard MAPI calls.

The following methods are available on the IExchangeManageStore interface:

  • CreateStoreEntryID
  • EntryIDFromSourceKey
  • GetRights
  • GetMailboxTable
  • GetPublicFolderTable


Logging On to a Mailbox Using the IExchangeManageStore Interface

The following procedure uses the CreateStoreEntryID method of the IExchangeManageStore interface to log on to a mailbox.

To log on to a mailbox using the IExchangeManageStore interface
  1. Create a profile that lists an information store to which your service will log on. The service’s Windows NT security ID should be listed as the owner of the store. This store is usually not used for any purpose other than logging on to MAPI.
  2. Initialize MAPI using MAPIInitialize.
  3. Log on to MAPI using MAPILogonEx and specify the previously created profile.
  4. Get the entry identifier of the default information store, which in this case is the Microsoft Exchange Server information store. Use the HrMAPIFindDefaultMsgStore function or make direct MAPI calls to perform this action.
  5. Open the mailbox listed in the profile using the IMAPISession::OpenMsgStore function. Microsoft Exchange Server examines the Windows NT security identifier under which your application is running and compares this with the access control list (ACL) that has been set on the mailbox object in the Microsoft Exchange Server directory. If the application does not have the appropriate rights, the call to OpenMsgStore will fail.
  6. Obtain a pointer to IExchangeManageStore by calling the QueryInterface method of the message store object.
  7. Call IExchangeManageStore::CreateStoreEntryID, passing the distinguished names (DNs) of the server and the mailbox, as well as the privileges your service is to have for the mailbox. For example, you could specify an OR’d combination of bits such as OPENSTORE_USE_ADMIN_PRIVILEGE | OPENSTORE_TAKE_OWNERSHIP. The function formats an entry identifier and does not access the information store. This means calls to the CreateStoreEntryID function are relatively fast and require no server resources.
  8. Open the information store using the pointer to the entry identifier that is returned from CreateStoreEntryID. Do this by calling the IMAPISession::OpenMsgStore method. In this call, make sure to specify the flag MDB_TEMPORARY. Otherwise, the store you are opening may be added to your profile.

The following sample code shows how to implement the previously listed steps. The sample code is the implementation of the HrMailboxLogon function, located in \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\MBLOGON\MBLOGON.C.

Note The MBLOGON sample application includes error checking. For clarity, error checking has been removed from this code sample.

// -----------------------------------------------------------------
// HrMailboxLogon() without any error detection.
// -----------------------------------------------------------------

HRESULT HrMailboxLogon(
   IN  LPMAPISESSION   lplhSession,            // ptr to MAPI session handle
   IN  LPMDB           lpMDB,                  // ptr to message store
   IN  LPTSTR          lpszMsgStoreDN,         // ptr to server DN
   IN  LPTSTR          lpszMailboxDN,          // ptr to mailbox DN
   OUT LPEXCHANGEMANAGESTORE *lppXManageStore, // ptr to manage mailbox interface ptr
   OUT LPMDB           *lppMailboxMDB)         // ptr to mailbox message store ptr
{
    ULONG       cbeid   = 0;      // count of bytes in entry ID
    LPENTRYID   lpeid   = NULL;   // Entry ID of default store

    MAPICALL( lpMDB)->QueryInterface( lpMDB, (REFIID) &IID_IExchangeManageStore,
        (LPVOID*) lppXManageStore);

    MAPICALL( *lppXManageStore)->CreateStoreEntryID(
        *lppXManageStore, lpszMsgStoreDN, lpszMailboxDN,
        OPENSTORE_USE_ADMIN_PRIVILEGE | OPENSTORE_TAKE_OWNERSHIP,
        &cbeid, &lpeid);

    MAPICALL( lplhSession)->OpenMsgStore(
        lplhSession, 0, cbeid, lpeid, NULL, MDB_NO_DIALOG | MAPI_BEST_ACCESS,
        lppMailboxMDB);

    MAPIFREEBUFFER( lpeid);

    return( NOERROR);
}


Flag Settings for Privileged Access

The preceding sample code contains calls to the IExchangeManageStore::CreateStoreEntryID and IMAPISession::OpenMsgStore methods. The following flags should be passed in these function calls.

Flags Used with IExchangeManageStore::CreateStoreEntryID

OPENSTORE_USE_ADMIN_PRIVILEGE Grants temporary user rights to an application for the specified information store if the application already has Admin privilege on the information store. It allows the application to act as owner of the store, but it does not log on to the mailbox under the mailbox owner identity. Passing this flag causes a security event to be written to the event log. It is normally used in conjunction with OPENSTORE_TAKE_OWNERSHIP.

OPENSTORE_TAKE_OWNERSHIP Opens the store with Ownership privilege. When an application specifies this flag, it accesses the store under the identity of the store’s owner. Passing this flag causes a security event to be written to the event log.

Flags Used with IMAPISession::OpenMsgStore

MDB_NO_DIALOG Prevents display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned when logon is unsuccessful. If this flag is not set, the information store provider can prompt the user to correct a name or password, insert a disk, or perform other actions necessary to establish connection to the store. Pass this flag to avoid these prompts during an automated process.

MDB_NO_MAIL Indicates the information store should not be used for sending or receiving mail. The flag signals MAPI not to notify the MAPI spooler that this information store is being opened.

Important Because an active spooler can cause unexpected results in a mailbox you have opened with privileged access, it is very important to pass the MDB_NO_MAIL flag when you call IMAPISession::OpenMsgStore.

MDB_TEMPORARY Instructs MAPI that the store is not to be added to the message-store information table and that the store cannot be made permanent.

MAPI_BEST_ACCESS Indicates the object should 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 access, the object is opened with read/write access; if the client has read-only access, the object is opened with read-only access. The client can retrieve the access level by getting the PR_ACCESS_LEVEL property.


Examples: Privileged Service Applications

You can build privileged services that can log onto multiple mailboxes by using Microsoft Exchange Server functions. These functions enable you to build a range of services that might include the following two examples:

  • Voice mail application that allows users to call into Microsoft Exchange Server and retrieve their messages over the telephone. A user might enter a personal ID code and an access code on their touch-tone phone, whereby the voice mail application reads the user’s mail over the phone by converting the message’s text to analog voice signals. Entering other codes would result in messages being saved, deleted, forwarded, and so forth.
  • A utility that performs operations on mailboxes, such as moving them from one server to another or backing up an entire mailbox on a different server. Without the mailbox logon functions, Microsoft Exchange Server will not permit these actions because it does not allow multiple mailboxes on different servers for a single user.


Backing Up and Restoring Data

The Microsoft Exchange Server SDK provides functions for backing up and restoring data in the Microsoft Exchange Server directory and information store. These functions perform backups online, which means that there is no need to stop the directory service or information-store service to back up directory or information-store data. Also, backup and restore operations can be performed remotely.

Files Needed to Call the Backup and Restore Functions

Files | Purpose
EDBMSG.H | Error codes
EDBBCLI.H | Header file for the backup/restore functions
EDBBCLI.LIB | Static LIB of backup/restore functions
EDBBCLI.DLL | Backup/restore entry point DLL

The backup and restore functions provide three types of backup capabilities: full, incremental, and differential.

  • A full backup backs up the entire directory or entire information store and allows you to restore it from a single backup.
  • An incremental backup backs up just the changes since the last full or incremental backup. Restoring incremental backups requires the original full backup plus all the incremental backups made since that time.
  • A differential backup backs up the changes since the last full backup. Restoring a differential backup requires one differential backup and the original full backup.

The following table lists the backup and restore functions and what they are used for.

List of Backup and Restore Functions

Function | Purpose
BackupFree | Frees memory allocated during one of the backup functions.
HrBackupClose | Closes the current file being backed up.
HrBackupEnd | Cleans up after a backup operation has been performed.
HrBackupGetBackupLogs | Obtains the list of log files to be backed up. These are the only files that need to be backed up for a differential or incremental backup.
HrBackupGetDatabaseNames | Returns the list of the attached databases on the remote machine.
HrBackupOpenFile | Opens a remote file for backup and will perform whatever client and server side operations to prepare for the backup.
HrBackupPrepare | Connects to a remote Microsoft Exchange Server database and prepares it for backup.
HrBackupRead | Reads one block from a backup file.
HrBackupTruncateLogs | Deletes the committed database log files.
HrRestoreEnd | Cleans up after a restore operation has been performed.
HrRestoreGetDatabaseLocations | Returns the database locations for the server and service referred to by the handle hbcRestoreContext.
HrRestorePrepare | Connects to a remote Microsoft Exchange Server database and prepares it for restore.
HrRestoreRegister | Registers a restore operation.
HrRestoreRegisterComplete | Completes a restore operation.
HrSetCurrentBackupLog | Sets the last log number that was backed up.

The directory and information store consist of the following files:

  • A main database file. This file is named DIR.EDB for the directory, PRIV.EDB for the private information store, and PUB.EDB for the public information store. This file name is returned from the HrBackupGetDatabaseNames function, and is passed in a call to the HrBackupRead function.
  • Transaction log files, named EDB#####.LOG, where ##### is a 5-digit hexadecimal number from 00000 to FFFFF. One set of these files is used for the directory and one set is used for the private and public information stores combined.

Because the log files log the changes made to the database, the backup functions use the log files to perform incremental and differential backups. After a full or incremental backup, the log files must be purged (that is, the logs that have been written to the EDB file are deleted) with a call to the HrBackupTruncateLogs function.

The location of the database and log files on a Microsoft Exchange Server computer can be changed dynamically by an administrator. The currently configured paths can be obtained using the HrRestoreGetDatabaseLocations function. For more information, see Backup File Locations.


Backing Up Directory or Information Store Data

The following procedures outline a typical methodology to programmatically back up the directory and information store databases. The first procedure explains how to perform a full backup. The second procedure explains differential and incremental backups.

To perform a full backup of data
  1. Call HrBackupPrepare to get a client-side context handle and to specify the backup method. In this call, specify that the type of backup to be performed is FULL.
  2. Call HrBackupGetDatabaseNames to get a list of the files to backup. These files cannot be backed up using normal file copy routines. They must be backed up using HrBackupOpenFile and HrBackupRead. Each file name in the list is preceded by a one-byte token (defined in EDBBCLI.H) that indicates the type of file. This token should be saved along with the data backup so it can be matched with the proper directory returned by HrRestoreGetDatabaseLocations at restore time. For more information, see Backup File Locations.
  3. Call HrBackupOpenFile to open the file for each file in the list returned by HrBackupGetDatabaseNames. When the file has been successfully opened, call HrBackupRead to read the data in that file. When the file has been read and stored to the desired location, call HrBackupClose.
  4. Release the memory returned by HrBackupGetDatabaseNames by calling BackupFree on it.
  5. Call HrBackupGetBackupLogs to get a list of transaction log files to back up. These files are all located in the current log file path (configurable in the Microsoft Exchange Server Administrator program). For a full backup, one of the files returned in this list will be a patch file that contains the changes that occurred to the database while the backup was running. As with the files returned by HrBackupGetDatabaseNames (see step 2), each file returned by HrBackupGetBackupLogs will be preceded by a token indicating the file type that should be saved and matched with tokens returned by HrRestoreGetDatabaseLocations at restore time.
  6. Call HrBackupOpenFile, HrBackupRead, and HrBackupClose for this list of files in the same manner as step 3.
  7. Release the memory returned by HrBackupGetBackupLogs by calling BackupFree on it.
  8. Call HrBackupTruncateLogs to delete the log files.
To perform differential or incremental backup of data
  1. Call HrBackupPrepare to get a client-side context handle and to specify the backup method. In this call, specify that the type of backup to be performed is Logs Only (for differential or incremental). Under certain situations, a differential or incremental backup may not be possible in certain situations such as when a full has not been performed because a defragmentation or migration has been performed on the database, or transaction log files are out of sequence on the disk, or Circular Logging is enabled on the database. If HrBackupPrepare fails for the type of backup you wish to perform, a full backup should be performed before retrying a differential or incremental backup.
  2. Call HrBackupGetBackupLogs to get a list of transaction log files to backup. These files are all located in the current log file path (configurable in Microsoft Exchange Administrator). Each file returned by HrBackupGetBackupLogs will be preceded by a token indicating the file type, which should be saved and matched with tokens returned by HrRestoreGetDatabaseLocations at restore time.
  3. Call HrBackupOpenFile, HrBackupRead, and HrBackupClose for this list of files.
  4. Release the memory returned by HrBackupGetBackupLogs by calling BackupFree on it.
  5. This step is performed only for incremental (not differential) backups

    Call HrBackupTruncateLogs to delete the log files.

    Important Do not call HrBackupTruncateLogs if the backup is unsuccessful. If you call HrBackupTruncateLogs and the backup is not successful, your database will not be recoverable if it is interrupted before a clean shutdown.

  6. Call HrBackupEnd to release the backup context.


Restoring Directory or Information Store Data

Because of directory addressing constraints, a directory can be restored only to the server from which it was backed up. An information store can be restored to an alternate server. The backup application should be capable of selecting the appropriate paths to restore the files to the appropriate paths because they may have been reconfigured since the backup, or, in the case of the information store, the server may be different.

To restore data
  1. Shut down the service that is being restored. The directory service is MSExchangeDS, the information store is MSExchangeIS. The application can also have the user stop the services manually through the Services applet of the Windows NT Control Panel.
  2. Call HrRestorePrepare to obtain a restore context.
  3. Call HrRestoreRegister to interlock subsequent restore operations and prevent the service from being started until you have completed the restore.
  4. Copy the files off the backup medium onto the destination server. To find out the location where the files should be restored, call HrRestoreGetDatabaseLocations. Match the tokens that were returned by HrBackupGetBackupLogs and HrBackupGetDatabaseNames at backup time with the tokens preceding the directories returned by HrRestoreGetDatabaseLocations. The programmer requires no knowledge of what type of files are backing up and where they are being restored beyond this token matching technique. For examples of the data returned by these functions, see Backup File Locations.
  5. Before the service starts, you must call HrRestoreRegisterComplete and specify the status of the restore operation. If the status is not successful, the service will not start until a valid database has been restored. This completes the restore operation and allows the service to start.
  6. Start the service or allow the user to start the service manually.


Backup File Locations

The following is a list of example locations for files used in the backup and restore procedures. They are not default directories, but rather a set of four example directories that an administrator could set on the server object using the Microsoft Exchange Administrator program. They are used in some of the preceding procedures that describe how to back up and restore data.

The string at the beginning of each line corresponds to a file type defined in the EDBBCLI.H file.

Example: At backup time, the HrBackupGetDatabaseNames function returns:

BFT_MDB_PRIVATE_DATABASE\\SERVER1\MDBDATA\PRIV\PRIV.EDB\0

BFT_MDB_PUBLIC_DATABASE\\SERVER1\MDBDATA\PUB\PUB.EDB\0\0

Example: The HrBackupGetBackupLogs function returns:

BFT_LOG\\SERVER1\MDBDATA\LOGS\EDB00001.LOG\0

BFT_LOG\\SERVER1\MDBDATA\LOGS\EDB00002.LOG\0

BFT_PATCH_FILE\\SERVER1\MDBDATA\WORKING\PUB.PAT\0\0

Example: At restore time, the HrRestoreGetDatabaseLocations function returns,:

BFT_CHECKPOINT_DIR\\SERVER2\MDBDATA\WORK\0

BFT_LOG_DIR\\SERVER2\MDBDATA\TRAN_LOGS\0

BFT_MDB_PRIVATE_DATABASE\\SERVER2\MDBDATA\PRIVATE\0

BFT_MDB_PUBLIC_DATABASE\\SERVER2\MDBDATA\PUBLIC\0\0

In this example, five files were backed up. Based on the return values of HrRestoreGetDatabaseLocations, they should be restored as follows:

File | Restore to
PRIV.EDB | \\SERVER2\MDBDATA\PRIVATE
PUB.EDB | \\SERVER2\MDBDATA\PUBLIC
EDB00001.LOG | \\SERVER2\MDBDATA\TRAN_LOGS
EDB00002.LOG | \\SERVER2\MDBDATA\TRAN_LOGS
PUB.PAT | \\SERVER2\MDBDATA\TRAN_LOGS

You must also provide the path preceded by the BFT_CHECKPOINT_DIR token to the HrRestoreRegister function, even though you will never have to directly restore any files to this path.


Restoring to a Server other than the Backup Server

You cannot restore the directory to a server other than the server from which the backup was taken. Although the backup and restore functions allow you to do this and the directory service will start up, the directory service will not function correctly on a different server.

An information store, however, can be restored to a different server.


Erasing Log File Data Before Restoring

You may want to give users the option to keep existing log file data already on the server and restore over it. After you restore the files and the service starts up, the database will commit the transactions in the restored log files. If contiguous log files exist on the server beyond the highest restored log file, those transactions will also be committed. If there is any gap in the numeric log file name sequence, however, no further transactions will be committed beyond the gap.

You should also provide the option to delete the existing log files on the disk because certain situations will require this (such as restoring an information store to a different server or purposely restoring to a previous date without desire for recommitting all the logs that are still on the disk). This can, of course, also be done manually by the user before running your program.


Preventing an Incremental Backup Until a Full Backup Is Performed

In some situations, you may want to prevent an incremental backup from being performed until a full backup is performed again. The following procedure shows how to force an incremental backup to fail.

To force an incremental backup to fail

Call HrSetCurrentBackupLog with the BACKUP_DISABLE_INCREMENTAL value for the dwCurrentLog parameter.


Using Event Notifications

Event notification is the communication of information between two MAPI objects. One object registers an interest in learning of a change or error, called an event, that may take place in another object. After the event occurs, the first object is informed, or notified. The object receiving the notification is called the advise sink; the object responsible for the notification is called the advise source. MAPI advise sink objects implement the IMAPIAdviseSink interface, which contains a single method, OnNotify. The advise source notifies the advise sink by calling OnNotify and passing a notification structure that contains information about the event. OnNotify can perform tasks in response to the notification, such as updating data in memory or refreshing a screen display.

Client applications typically implement advise sink objects and service providers implement the advise source. Unlike the advise sink, which is a particular type of MAPI object, the advise source may be one of the many different types of MAPI objects that supports event notification. To name a few, advise source objects include sessions, tables, message stores, address book objects, and folders. All advise source objects contain the Advise and Unadvise methods to handle notification registration. Clients call Advise when they want to register for a notification and Unadvise when they want to cancel the registration.

For more information on the tasks required to implement notifications, see the MAPI Programmer's Reference.

There are two major kinds of notifications: object notifications and table notifications. The following sections provide information on using these types of notifications in your application.


Requesting Object Notifications

You can request object notifications on the contents of private information stores or on public information stores. These notifications report on notification events indicating that an object was created, deleted, modified, copied, or searched.


Notifications on Private Information Stores

For the contents of private information stores, you can control the scope of notifications you receive by tailoring your call to the Advise method:

  • You can register for notifications on changes on a single specified object in the private information store by passing its entry identifier.
  • You can register for notifications on changes to any object in the entire information store—the entire user’s mailbox—by passing NULL for the lpEntryId parameter. This requests that your application be notified of the creation or deletion of any message, or the movement of any object.


Notifications on Public Information Stores

You cannot register for notifications on the entire public information store. You can register only for changes on a specific folder or message by passing its valid entry identifier.

Notifications on an entire public information store are not supported because these stores are replicated to other servers and sites. Such a notification request could mean reporting all changes to any public folders anywhere in the organization, although the details might be spread out over many different servers.


Table Notifications

Users can register to be notified when a change to a table occurs by creating an advise sink object and calling IMAPITable::Advise. Typical changes that cause notifications to be sent include the addition or deletion of a row or column and any critical error.

Microsoft Exchange Server information stores support table notifications only for contents tables and for hierarchy tables, not for other kinds such as attachment tables. Table notifications apply to specific tables, such as the contents table of your Inbox, which is the list of messages that appear in your Inbox. If you are registered for table notifications on it, you will be notified when new messages are added.

Using table notifications instead of object notifications can reduce network traffic. This is because, with a table notification, table data is connected to the notification’s RPC. In other words, when a message is added or modified, the table notification also includes data that has changed. It states, for example, that a message was added at a certain position in the table and it supplies the row data (the properties) for the row (the message). Because the notification itself contains all the information you need, you can simply display that returned data in the row with no further calls to the server.

In contrast, object notifications supply the notification but not the changed data. Typically, you would need to make an additional call to read the changed data, which causes more network traffic.


Push and Poll Notifications

Notifications can be initiated in two ways:

  • Poll notifications are triggered by client requests
  • Push notifications are triggered by events on the server.

With poll notifications, a client asks for notifications at regular intervals, such as every five minutes. This notification model reflects the standard client-server model, in which clients obtain information by initiating actions. One disadvantage of this notification model is that if an event occurs on the server that a client has interest in, the server must wait for the client to ask. Only by making frequent requests can clients receive information on a timely basis. This increases network traffic, which is a second disadvantage to the polling model.

With push notifications, if an event occurs on the server such as the arrival of new mail, the server can send a network packet that contains the relevant data to every registered client.

Client Network Protocols for Push Notifications

When an application registers for notifications, the information store activates push notifications if the network protocol installed on the client computer supports them. If push notifications are not possible for any reason, the information store activates poll notifications.

Push notifications are not used with the AppleTalk, NetBEUI, or Banyan Vines protocols , but they are supported for the TCP/IP and IPX/SPX protocols. If at least one client computer that has IPX/SPX installed is connected to a Microsoft Exchange Server computer, you need to install Gateway Services for Novell NetWare and the SAP agent on the Microsoft Exchange Server computer. For more information, see the Microsoft Exchange Server Concepts and Planning Guide and your operating system documentation.

The following table lists the protocols that, on a client computer, support push notifications.

Protocol Requirements for Push Notifications

Network Client | Protocol for Push Notifications
Novell NetWare | NWLink (IPX/SPX) or LanWorkplace for DOS (TCP/IP) or Microsoft Windows for Workgroups TCP/IP 3.11A
Microsoft Windows for Workgroups, Microsoft Windows NT Workstation, MIcrosoft Windows 95 | IPX/SPX-compatible protocol or TCP/IP protocol

The Named Pipes RPC protocol may be layered on top of the IPX/SPX or the TCP/IP protocol. This does not hinder the operation of push notifications.

If you are not using the Windows Internet Name Service (WINS), the IP addresses of all Microsoft Exchange Servers in the organization must be specified in the HOSTS file on client computers. This file can be found, for example, in the WINNT\SYSTEM32\DRIVERS\ETC directory on a client computer running Windows NT Workstation.


Testing for Push Notifications

There are two ways to determine whether push notifications are in use on your installation. The first test is to send a message to yourself. Push notifications may not be working if the message appears only after a standard polling interval of two or five minutes, or if you can cause messages to appear by opening another folder and then re-opening your Inbox.

The following procedure outlines a test that may give more reliable results.

To test for push notifications
  1. In the Microsoft Exchange Client, select the Find option from the Tools menu.
  2. Click Folder and select a folder in a remote information store (such as an Inbox on the server or a public folder), preferably one that contains a large number of messages.
  3. Type a string in the Message body text box that will likely be found in a large number of messages, such as the letter e.
  4. Click Find Now. Watch the screen as the messages appear. If they appear in rapid bursts, push notifications are most likely working.
  5. If the display of new messages slows markedly or stops, click a column heading (such as Item Text or Received) to sort the messages. If new messages appear as the list of messages is redisplayed, push notifications are probably not in use. This is because your request to re-sort messages causes an RPC, which in turn causes the delivery of messages if poll notifications are in effect.


The Queue of Notifications

The server maintains a fixed-size queue of notifications. When the queue limit of 64 notifications is exceeded, the information store provider first tries to collapse notifications. For example, notifications that describe the specific changes in a table are changed into TABLE_CHANGED notifications, which state simply that the table has changed. It no longer provides the row that has been added, deleted, or modified. At this point, the client must reload the entire table to ensure accuracy. When the queue limit is exceeded, it is also possible that some notifications are lost.

TABLE_RELOAD Notifications

The TABLE_RELOAD flag indicates a need to re-read the table data and start over. When a client receives the TABLE_RELOAD event, it should assume that nothing about the table is still valid. All bookmarks, instance keys, short-term entry identifiers, and status and positioning information are obsolete.

In almost every case, an application should respond the same way to a TABLE_CHANGED event as to a TABLE_RELOAD event: namely, it should read all the table data again.


Calling the Advise Function to Start Notifications

The client side of the Microsoft Exchange Server information store provider buffers calls to the MAPI Advise function, and does not send it to the server until it is forced through by a later function call. In other words, although there is no MAPI_DEFERRED_ERRORS flag on the Advise function, a call to Advise works as if this flag is available and always set.

This means that an application cannot simply call Advise and wait for notifications to appear. It must call Advise and then, for example, call IMAPIProps::GetProps on a property known not to be cached on the client. This GetProps call can be executed on any object, such as the information store itself.

An RPC can initiate the return of notifications, but an Advise call itself does not force an RPC.

If your application is about to make several function calls, one of which is Advise, make sure that Advise is not the last call. For example, this order is incorrect:

  1. OpenNote
  2. OpenEntry
  3. GetProps
  4. Advise (on the new message)

The following order is correct because at least one call after Advise causes an RPC:

  1. OpenNote
  2. OpenEntry
  3. Advise (on the new message)
  4. GetProps

If you are working with a table, you could also call the QueryRows function, which causes an RPC and forces any Advise requests to the server.

To summarize, call Advise in a way that you know causes the information store (server side) to receive the Advise call to make sure notifications are enabled, and then check that there is a mechanism by which the store sends notifications.


Multiple Advise Calls

Calling Advise causes an RPC, which constitutes network traffic and can load the server. Therefore, if you want to request multiple Advise calls, it is best to request all of them, and then perform an operation that causes them to be sent to the server in a single RPC, as described in the preceding section.


Network and RPC Error Codes for Information Store Operations

All MAPI interfaces are OLE COM interfaces that use RPC services for marshaling data across process boundaries. If the Remote Procedure Call Service returns an error, a corresponding MAPI error (as shown in the following table) is returned to the calling application. For more information on OLE custom interfaces, see the Platform SDK.

RPC-Related MAPI Error Codes

RPC Error | MAPI Error Returned
RPC_S_ACCESS_DENIED | MAPI_E_NO_ACCESS
RPC_S_NOT_LISTENING | MAPI_E_SESSION_LIMIT
RPC_S_SERVER_UNAVAILABLE | MAPI_E_NETWORK_ERROR
RPC_S_OUT_OF_RESOURCES | MAPI_E_NOT_ENOUGH_MEMORY
RPC_S_SERVER_TOO_BUSY | MAPI_E_CALL_FAILED

Because the Microsoft Exchange Server information store provider automatically retries calls that return these RPC errors, you need not do so in your own code. This process differs from that in use by the directory service; for more information, see Network and RPC Error Codes for Directory Operations.


Entry Identifier Identifies Specific Object for Notification

An application can register to receive notification of the deletion of an object in any of three ways:

  • In the call to Advise, pass the entry identifier of the particular object, whether it is a folder object or a message object. To receive notification of the deletion of a message within a folder, the application must be registered for notifications about the message itself, not the folder that contains it.
  • Pass NULL in the Advise call to request notification of all deleted objects in the information store.
  • Register for table notification on a contents table of the folder.


Ordering Function Calls to Ensure Table Notifications

Microsoft Exchange Server automatically batches calls to the IMAPITable::SetColumns and IMAPITable::SortTable methods, even if not expressly requested to do so by the calling application. Because of this batching, you need to make these calls in a certain order to receive notifications. Specifically, IMAPITable::GetRowCount or IMAPITable::QueryRows must be called before changes are made to a table for which notifications are expected.

For example, your code may contain a sequence like the following:

  1. Call lpFolder–>GetContentsTable(lpTable)
  2. Call lpTable–>Advise
  3. Call methods on objects other than the table, such as lpFolder–>CreateMessage, SetProps, and then SaveChanges on the messages. It is these calls that cause the changes for which notifications are expected.

The result of this sequence is that notifications do not arrive. However, notifications are received if the following order is followed, in which GetRowCount is called before changes are made to the table:

  1. Call lpFolder–>GetContentsTable(lpTable)
  2. Call lpTable–>Advise
  3. Call lpTable–>GetRowCount or lpTable–>QueryRows. Calling this method at this point enables notifications for the changes to be made in the next step.
  4. Call methods on objects other than the table, such as lpFolder–>CreateMessage, SetProps, and then SaveChanges on the messages. It is these calls that cause the changes for which notifications are expected.


Obtaining Microsoft Exchange Server Interfaces

Many of the programming tasks that manipulate information store data rely on the use of Microsoft Exchange Server interfaces. Most of these interfaces are available through the extensibility mechanism that MAPI provides for objects.

This mechanism is the support MAPI provides for properties that are themselves objects. These object properties have the type PT_OBJECT and implement the IUnknown interface. For properties of this type, call the IMAPIProp::OpenProperty method instead of GetProps. As indicated in the following table, you need to pass the correct value in the lpiid parameter to obtain the correct interface.

In some cases, you obtain an interface pointer by calling a function designed to return that pointer, such as HrFolderACLsOpen.

The following table lists the interfaces provided by Microsoft Exchange Server and the actions you take to obtain a pointer to each.

Microsoft Exchange Server Interfaces

Interface | To obtain a pointer to this interface
IExchangeExportChanges | The controlling process (agent) must open the store and call the MAPI IMAPIProp::OpenProperty method on either the PR_CONTENTS_SYNCHRONIZER property (to synchronize the contents of a folder) or the PR_HIERARCHY_SYNCHRONIZER property (to synchronize the hierarchy of a folder). When calling the OpenProperty method, pass the value IID_IExchangeExportChanges in the lpiid parameter.
IExchangeFavorites | Call the MAPI IMAPIProp::GetProps method with the PR_IPM_FAVORITES_ENTRYID property and then the MAPI IMsgStore::OpenEntry method with that entry identifier. When calling the OpenEntry method, pass the value IID_IExchangeFavorites in the lpInterface parameter.
IExchangeFolderACLs | Call the HrFolderACLsOpen function.
IExchangeFolderRules | Call the HrFolderRulesOpen function.
IExchangeImportContentsChanges | The controlling process (agent) must open the store and call the MAPI IMAPIProp::OpenProperty method on the PR_COLLECTOR property of the object. When calling the OpenProperty method, pass the value IID_IExchangeImportContentsChanges in the lpiid parameter.
IExchangeImportHierarchyChanges | The controlling process (agent) must open the store and call the MAPI IMAPIProp::OpenProperty method on the PR_COLLECTOR property of the object. When calling the OpenProperty method, pass the value IID_IExchangeImportHierarchyChanges in the lpiid parameter.
IExchangeManageStore | Call the QueryInterface method of the information store object.
IExchangeModifyTable | Call the MAPI IMAPIProp::OpenProperty method on any property of type PT_OBJECT. When calling the OpenProperty method, pass the value IID_IExchangeModifyTable in the lpiid parameter.
IExchangeRuleAction | Call the MAPI IMAPIProp::OpenProperty method on the PR_CLIENT_ACTIONS property of the object. When calling the OpenProperty method, pass the value IID_IExchangeRuleAction in the lpiid parameter.

For more information, see Microsoft Exchange Server Interfaces.


Microsoft Exchange Server Scripting Agent

The Microsoft® Exchange Server Scripting Agent lets you use server-side scripts that run as a result of events occurring in folders. Such triggering events include timer events and actions such as posting, editing, or deleting a message. They can take place in private folders (mailboxes) or public folders. You need sufficient folder permissions to install and enable event-driven folder scripts.

You can write these scripts in VBScript, JavaScript, or other supported scripting languages, and you can use Notepad (by default) or Microsoft Visual Studio (specifically, the Microsoft Developer Studio IDE) as your script editor, in conjunction with Microsoft Outlook version 8.03. See Writing and Installing Scripts.

Collaboration Data Objects (CDO, formerly Active Messaging) is the primary interface that scripts use to access and manipulate data in Microsoft Exchange information stores. (These scripts call CDO objects to perform their operations.) For more information, see Overview of Collaboration Data Objects.


Application Scenario: an Expense Report

A typical and appropriate use of server-event scripting is an approval application such as expense-report processing. In this example, a person wanting reimbursement fills out and submits a request in the form of an e-mail message. The simplest routing path takes the message to the requester's supervisor, to a person in Accounts Payable, and finally back to the requester, with payment notification.

This example shows that scripts can use information from a message, obtain information from other sources, and respond accordingly, which may include changing the path the message takes.

The employee submits an expense report by mailing or posting it to a designated "Expense Report" folder. Its arrival in the folder (known as the "application" folder) triggers the Folder_OnMessageCreated event.

The Folder_OnMessageCreated subroutine in the script evaluates the properties contained in the expense report and verifies that all the required ones are present. If any are missing, it returns the report to the sender.

This subroutine also evaluates the amount requested in the expense report. It can look up the name of the sender's manager in the directory and forward the report to that person automatically. Or it can look up the expense authorization budget limit and forward the report to the manager's manager if the limit would be exceeded. In this way, the subroutine can use server-side logic to perform directory lookups and make routing decisions based on properties of people in the directory.

If we assume that expense reports will not be edited while being processed, the script that processes them will not need a Message_OnChanged subroutine. But it would almost certainly need a Folder_OnTimer subroutine, which would be triggered if no response has arrived from the manager who received the request after a chosen number of days. The subroutine could, for example, notify the requester (or the manager's manager) of the delay and suggest that another action be taken.


At a Glance: Setting up the Event Service

Perform the following actions to install and configure the Microsoft Exchange Event Service.

To set up the Event Service
  1. While installing Microsoft Exchange Server (version 5.5 or later), your system administrator also installs the Microsoft Exchange Event Service. Once the Event Service is installed, it will run automatically as a Microsoft Windows NT® service when you start Microsoft Exchange Server. During installation, a folder (called EventConfig_<ServerName>) is automatically created in the information store. This folder holds information about the Event Service. You will use this folder in a later step when binding agents to the server.
  2. (Optional) Install Microsoft Visual Studio, to use as a script editor. Otherwise, Notepad is the default script editor.
  3. To configure Microsoft Visual Studio so that you can edit and save scripts for the Exchange Scripting Agent, refer to the Release Notes included with your installation compact disk of Microsoft Exchange Server version 5.5.
  4. Install Microsoft Outlook version 8.03 or later. (This is the version of Microsoft Outlook version that you receive with Microsoft Exchange Server version 5.5.)
  5. Have a Microsoft Exchange Server administrator grant permissions. You need sufficient permissions to run scripts in folders. For more information, see Granting Permissions.
  6. Create an agent to monitor and respond to events in a folder. This involves writing and adding scripts to the folder, and binding agents to the computer running Microsoft Exchange Server, on which you want the scripts to run.
  7. (Optional) Advanced users can write a custom agent, instead of a script, to process events.


Scripting Architecture

The following elements work together to provide server-side event scripting and are depicted in the illustration that follows:

  • The Microsoft Exchange Event Service A Microsoft® Windows NT® service that runs on the computer running Microsoft Exchange Server. Using Microsoft Outlook, you configure this service to monitor events that occur in folders you specify.
  • Folders The folders upon which event scripting works can be Microsoft Exchange private folders (mailboxes) or public folders.
  • Microsoft Exchange Scripting Agent An engine that processes scripts. This element is a COM object that exposes the IExchangeEventHandler interface.
  • User-created scripts These scripts, which call CDO objects/interfaces, constitute the actual CDO logic that works on folders. Scripts are stored as messages in the folder and, as such, travel with the public folder application. These messages are visible only through the Agents interface or through a MAPI utility such as Mdbvu32.exe, and are hidden to Microsoft Exchange clients such as Microsoft Outlook.

Other related elements—not seen in the diagram—are these:

  • Microsoft Exchange Administrator program A graphical interface used for configuring and maintaining the sites and servers of an organization, for creating and configuring public folders, and for granting permissions to users—such as for writing and enabling scripts.
  • Microsoft Outlook Using Microsoft Outlook version 8.03 or later, you can create agents that respond to events in folders.


Advantages of Server-side Logic

Logic performed on the server enables the creation of many types of useful applications, including workflow applications. Workflow is improved in the following ways:

  • Exception Handling If a recipient of an expense report, for example, is away for several days without access to e-mail, the report would remain unread at that point in its path. When this happens, script logic executed on the server could automatically approve the item, reject it, or send it to the absent recipient's manager.
  • Routing Determination When the expense report (a message) is posted, the script can read message properties, determine where it should go next, and then update the state of the message.
  • State Verification If logic were implemented on the client, the workflow logic would travel with the message and would therefore reside only on individuals' computers. This would make it impossible to check its state (for example: which recipients have responded and which haven't) from a central location. A server-resident script could store and update state information on a server location—such as in the monitored folder—and thus always have access to it.
  • Data Validation An application may need to control the completeness and correctness of items submitted, such as making sure that required properties are present. This is done best when data-validation logic is consolidated in a server script. Then, no matter what form recipients use to post or edit a workflow item, server logic can validate its data. For example, it could check for a department number on an expense report and, if missing, return the message to the sender.

Implementing workflow logic client-side could work for some applications, but it still might require that the server perform time-out monitoring or that user workstations be logged on continuously. Because applications that need successive approval steps are typical, the server-side scripting provided by the Microsoft Exchange Scripting Agent is a more reliable and efficient method than using client-side logic.


Typical Steps in Event Processing

The following steps illustrate folder event processing and refer to elements in the diagram in Scripting Architecture. In this example, "Folder 3" is one of several folders configured to monitor events. The creation of the agents for this folder linked certain events that occur in Folder 3 to a script placed in Folder 3.

  1. A message is posted to Folder 3, a folder being monitored by the Microsoft Exchange Event Service.
  2. A notification of the posting is sent to the Event Service.
  3. The Event Service calls an Incremental Change Synchronization (ICS) method to request all the changes that have occurred in Folder 3 since the last time an event occurred in that folder. The Event Service translates the notification into an event.
  4. The Event Service keeps track of the agents registered for every type of folder event. Because the agent called Microsoft Exchange Agent Scripting has been registered for events in this folder, the Event Service instantiates an agent of this type.
  5. The Event Service calls the Run method on the IExchangeEventHandler interface on the agent. In doing so, it passes the folder identifier of Folder 3, the message identifier of the newly posted message, and the session object of the logged-in CDO session.
  6. The scripting agent obtains the script from the folder being monitored.
  7. The scripting agent creates a CDO session (with the Microsoft Exchange identity of the person who saved the script in Folder 3) and passes it to the script. Now, when performing actions within the system, the script has the same rights as its author. See Scripts, Agents, and Security.
  8. The scripting agent runs the script for the event that occurred.

Note – Synchronous versus Asynchronous Event Handling The Microsoft Exchange Event Service fires events asynchronously with respect to the Microsoft Exchange information store. This means that the store does not block your event script, or wait for it to run, before letting other processes access the folder or message. Other processes (Inbox Assistant rules, or even a fast user) could move, copy, delete, or modify the message before your script has a chance to run.

The Microsoft Exchange Scripting Agent is therefore suitable for typical, medium-volume workflow or administrative applications. It is not suitable for applications that would, for example, scan every piece of mail in or out of the system for viruses, or archive every message for government record-keeping purposes, because there is no guarantee that your scripts will see every message. A good example is trying to use OnMessageCreated events in your Outbox folder to process all outgoing mail. By the time your script runs, the message will already have been delivered and deleted from your Outbox.

Additionally, some of these types of scripting applications could face problems of scale. Depending on the application's purpose, you would either have to manually install a script in every folder for every user, or the volume would simply be too high to process with an interpreted language like VBScript.


About ICS Notifications

Incremental Change Synchronization (ICS) is a reliable mechanism used for obtaining information about folder events. ICS acts as a bookmark, so that changes in folders are never missed, even if the Event Service is down. ICS is also efficient: only one notification is generated per changed document.


About Agents

An agent maps a folder, one or more events, and the code (usually in a script) that processes those events. There are two types of agents:

  • A script, combined with the Microsoft Exchange Scripting Agent and a folder in which events are monitored
  • Custom agents

An agent is like a rule in that is has these characteristics:

  • It is tied to a specific folder.
  • It runs when a certain event triggers it, such as when a message with specific properties appears in that folder.
  • It has specific behavior.

Agents differ from rules in that, while any Microsoft Exchange recipient can set a rule, you need special folder permissions to set up agents. For information on creating agents, see Configuring Events and Actions.

About the Microsoft Exchange Scripting Agent

The Microsoft Exchange Scripting Agent is an agent that runs folder-resident scripts and provides CDO session, folder, and message objects to the script. It can work in conjunction with Microsoft Transaction Server. This is the default agent installed as part of Microsoft Exchange setup.


Microsoft Exchange Server Administration

The Microsoft® Exchange Server administrator controls a number of aspects that affect event scripting:

  • Permissions on an agent's configuration folder Administrators determine who (persons with Author permission on the EventConfig_<ServerName> folder) can bind agents to run on any particular server. See Granting Permissions and Binding an Agent to a Server.
  • Permissions on the application folder Administrators grant permissions for authoring and running scripts within the folder in which events will be monitored. Without Owner permission on a folder, you can save a script into the folder, but you cannot create an agent using Microsoft Outlook because the option for doing so (the Agents tab in the folder property sheet) will be unavailable. If you create a folder, you automatically have Owner permission on it until your permissions are expressly changed.
  • Agent installation Because administrators are in charge of the software installed on the server computer, they control which agents are available (installed) on the server.
  • Script restrictions Administrators can set script restrictions, such as which COM objects are available, and the maximum time of execution.

For related information, see Chapter 6, "Configuring Public Folders," in the Microsoft Exchange Server Getting Started Guide.


Granting Permissions

In order to install a script on the server, you need correct permissions on two folders:

  • You must be an owner of the application folder—the folder in which events are monitored—in order to edit or save scripts there.
  • You must have Author or Owner permission on the folder in which agents are created. This permission is granted in the following steps, which are to be followed by a server administrator.
To grant permissions for installing scripts
  1. Using the Microsoft Exchange Server Administrator program, in the Systems Folder container under \Events Root, select the EventConfig_<ServerName> folder that corresponds to the server on which the Microsoft Exchange Event Service is running.
  2. On the File menu, choose Properties, and then choose Client Permissions.
  3. Choose Add, and then select the user who will have permission to run applications or other agents on this server.
  4. In the Roles dialog box, select Author or another role with greater permissions (Owner); take special care when granting Owner permission because of the power this role entails.

For related information, see the Microsoft Exchange Server Getting Started Guide.


Scripts, Agents, and Security

Because event scripting uses Microsoft Exchange objects, the level of Microsoft Exchange permissions for scripts is important. But because non-Microsoft Exchange objects can also be used, Microsoft Windows NT permissions are important as well. This section discusses both types of permissions.

The Microsoft Exchange Scripting Agent creates a CDO session based on the mailbox identity of the script author. This means that it has Microsoft Exchange Server permissions equal to those of the script author when accessing objects within the CDO session.

Typically, the Microsoft Exchange Scripting Agent runs on the Microsoft Exchange site service account, whose Windows NT permissions match those of basic Microsoft Exchange components such as the directory service and the information store. This means that the agent has the same broad powers on the system as Microsoft Exchange Server itself. The agent can, for example, open any recipient's mailbox. (In fact, it does open the mailbox of the script author, in order to determine that person's Microsoft Exchange Server identity.)

For this reason, unless you use Microsoft Transaction Server (MTS) as described in the following section, you should only allow trusted developers to create and bind scripts that run on your Exchange Servers. For information on granting permissions to run scripts on your servers, see Chapter 6, "Configuring Public Folders," in the Microsoft Exchange Server (version 5.5) Getting Started Guide.

Running Scripts with a Lower-Privilege Windows NT Account

See the Microsoft Exchange Server 5.5 Release Notes for details on how to use MTS as a process manager for running your scripts under a particular Windows NT security account (for example, as the IUSER_MACHINE account that is created for IIS anonymous logons). MTS is available as a component of Microsoft Internet Information Server (IIS) version 4.0.


Configuring Events and Actions

Using Microsoft® Outlook, a folder owner can create a script and configure the folder to monitor events that will trigger script functions. As mentioned previously, you must also have Author permission on the EventConfig_<ServerName> folder to bind agents on the server on which they will be run.

To create a script in a folder
  1. Start Microsoft Outlook and locate the folder whose events you want a script to respond to.
  2. Right-click this folder, or select Folder from the File menu.
  3. Select Properties for that folder. This displays the Expense Report Properties dialog box.
  4. Choose the Agents tab to display the Agents property page.
  5. Select New. This displays the New Agent dialog box.
  6. Give the agent a name, such as Process New Expense Report. This also renames the dialog box.
  7. Choose an event to be monitored. In the When the following event(s) occur check box, select, for example, A new item is posted in this folder. This is illustrated in Process New Expense Report Dialog Box. For more information about the other choices in this dialog box, see Scheduled Event Dialog Box, and About Event Logs.
  8. Choose an agent for the event. To use the default script agent, choose the Script option button and go to Step 8. If you intend to use a non-script agent, skip to Step 9.
  9. Choose Edit Script. This launches Notepad by default, or Microsoft Visual InterDev if it is installed. If the script does not exist, a default script will open that contains stubs for four events; see Procedure for Editing Scripts. If a script exists, with the script editor open, choose Open on the File menu, and then open the existing script.
  10. If non-script agents are available, they are listed in the drop-down list box below Edit Script, the Other option button is available, and you can choose it to select one of these agents. This list box shows all the COM objects that support the IExchangeEventHandler interface and are bound to the specified server. If, for an agent, you choose a COM object that is also an ActiveX control that requires properties to be set, you can choose the Properties button to set them in the Properties dialog box.


Expense Reports Properties Dialog Box

Folder owners use this property sheet to configure the Expense Reports public folder.

To create or edit agents, click the Agents tab.


Agents Property Page

Folder owners use this property page to create a new agent. This page is also used for binding an agent to a server.

This property page is used to connect events, scripts, and servers. Collectively, these components are displayed as properties of an agent.

As with the Permissions page, this page is visible only to owners of the folder. When the folder owner clicks the Agents tab, the property page displays a list of agents, as shown in the illustration Agents Property Page (with Agents Displayed).

The Agents property page contains the following controls:

  • Agents for this folder This is a list box control that uses the check box style. It lists the current agent messages installed in this folder, displaying the property PR_DISPLAY_NAME. Double-clicking one of the items in the list box is the same as choosing the Edit button.
  • New Choosing New causes a new agent message to be created. See New Agent Dialog Box.
  • Copy Use Copy to copy agent messages between folders.
  • Edit Use the Edit button to modify the existing agent configuration data. See New Agent Dialog Box.
  • Delete Choosing Delete deletes the current agent messages. Deletion then requires user confirmation.
  • Run these agents on this server Use this control to bind an agent to a server. This is a drop-down list of servers on which the script should be run. It is populated from the list of folders that are under the NON_IPM public folder tree and whose name follows the format EVENTS_<server name>. One such folder exists for each server that has the Event Service installed. Each of these folders is created when the Event Service is installed on a particular computer.

    The server choice defaults to the home MDB server of the current folder, assuming that this server has the Event Service installed. If the home MDB server does not have the Event Service installed (and thus has no corresponding EVENTS_<server name> folder), the choice defaults to the first server on the list. The list is sorted alphabetically.

    The set of agents for a given folder must be guaranteed to run on only one server. This helps to ensure that the common set of ICS bookmarks for this folder (stored in the agent message in the folder) are manipulated by only a single server (ICS client).


Agents Property Page with Agents Displayed

If agents have already been created for this folder, they appear in the Agents for this folder control, as shown in the following illustration of the Expense Reports Properties dialog box.


New Agent Dialog Box

The following dialog box is displayed when you choose New or Edit on the Agents property page.

This dialog box has the following controls:

  • Agent Name This is a text edit box through which the author can name the agent. The string entered is used as the PR_DISPLAY_NAME property of the agent message that is written to the folder.
  • When the following event(s) occurs This is a check box-style list box that contains the following event-type choices:
    • A scheduled event occurs
    • A new item is posted in this folder
    • An item is changed in this folder
    • An item is deleted in this folder

    If at least one event is checked in this list box, the agent specified in the Run the following action section will start when that event occurs. Otherwise, no events are monitored in this folder.

  • Schedule This is available only if A scheduled event occurs is checked. Choosing the Schedule button displays the Scheduled Event dialog box, which you use to schedule timer events.
  • Logs Choosing this button displays the last 32KB of log messages resulting from this particular event, in this particular folder. See About Event Logs.
  • Run the following action These controls are used to edit the agent to be invoked when a matching event is triggered.
    • Script Choosing this option button causes the agent to default to the Microsoft Exchange Scripting Agent that handles scripts.
    • Edit Script Choosing this button starts Microsoft Notepad as your script editor. To use Microsoft Visual Studio 97 to edit scripts, refer to the Release Notes for Exchange Server version 5.5.
    • Other (option button) Choosing this option button sets the agent to the one listed in the drop-down list box.
    • Other (drop-down list box) This control displays the list of IExchangeEventSink-compatible objects installed on the server to which the script was bound on the Agents property page.
  • Properties Choose Properties to configure the properties of a COM object (a custom agent). This requires that the actual DLL or EXE files be installed on the local client computer as well as the server, so that the normal ActiveX property pages can be displayed.
  • OK/Apply Choosing OK or Apply registers your folder to be monitored by the Event Service so that your new agent is triggered when the event occurs. Specifically, this action
  1. Writes a message to the application folder. This hidden message contains the script, if the action chosen was to handle scripts with the Microsoft Exchange Scripting Agent. The script, now stored in the application folder, travels with the folder if it is moved.
  2. Writes an event-binding message to the EVENTS_<server name> hidden public folder. This message holds information for use by the Event Service, such as which folder to monitor (it contains the folder's identifier), the name of the server on which to run the action, the identifier of the script message to be run, and any needed COM object properties.


Scheduled Event Dialog Box

If A scheduled event occurs is checked in the New Agent dialog box, the Schedule button is enabled. Choosing it displays the Scheduled Event dialog box, which you use to schedule timer events.

These are some of the controls on this dialog box:

  • Hourly When this option is selected, the At time control and the Mon through Sun check boxes are unavailable. Use the Every control to specify the time interval on which the timer event should fire. The maximum number of hours is 99, and the maximum number of minutes is 59. Events will only fire during the hours indicated by the Start and End controls. All Day is the default choice.
  • Daily When this option is selected, the At time control and the Mon through Sun check boxes are unavailable. Choosing Daily causes the event to be fired once every day at the time specified with the At control. Because this choice specifies a particular time of day, when Daily is selected, the All Day, Start, and End controls are unavailable.
  • Weekly When this option is selected, the Every control is unavailable. It causes the event to be fired at the time specified by the At control on each day of the week checked. Because this specifies a particular time of day, when Weekly is selected, the All Day, Start, and End controls are unavailable.


About Event Logs

Choosing the Logs button displays the most recent log messages resulting from this particular event, in this particular folder. These messages are stored as properties—along with your script—in the hidden message in the application folder. You can have your script write messages to this log by assigning string values to the Script.Response intrinsic object.

Log data is displayed in a simple list box control. By default, there is a maximum of 32K of log text that can be stored. There is no mechanism to clear the logs; they replace each other—first in, first out—when the 32KB limit is reached.


Process New Expense Report Dialog Box

You see the following dialog box after you have named the agent (Process New Expense Report) and selected an event (A new item is posted in this folder) to trigger the agent.

For information about the controls on this dialog box, see New Agent Dialog Box.


Binding an Agent to a Server

One server running the Microsoft Exchange Event Service can handle events for an arbitrary number of folders.

Although the Event Service can be running on any number of computers, a script runs only once per event, and each event (and thus each script) is processed by only a single server. Therefore, binding an agent to a server means choosing which Event Service server will run the agent.

For example, to monitor a given folder for new postings, you first specify a Microsoft Exchange server on which to run the events these postings will trigger.

You use Microsoft Outlook to perform the binding, and you do this while creating agents. Use the Run these agents on this server control on the Agents property page to bind an agent to a server. All the agents for a given folder must be bound to the same server.

Location of Servers, Folders, Scripts, and Registration Information

A folder on which you want to run a script may be anywhere, such as in a recipient's mailbox, or replicated from a folder on another server.

Binding information is stored in a public folder that represents a server on which the Event Service is running. Specifically, when an administrator installs the Event Service, a new folder is created in the non-IPM subtree of the information store, under System Folders\Events Root\. This new folder is named EventConfig_<ServerName>, and it exists to contain data that connects folder events to this particular server. The location of this folder is shown in the following illustration.

If, for example, you configure an event in a given folder to trigger an action that will be run on the server EXCHNGE3, the act of binding writes agent data into the folder EventConfig_EXCHNGE3. Although this folder contains binding data, it is not visible through the Microsoft Exchange Server Administrator program.

The public folder information store, the Event Eervice, and the agents can each be on different Microsoft Windows NT® servers or all on the same server.

Permissions Are Needed to Bind Agents

The Microsoft Exchange administrator, who configures public folders, controls who is allowed to run scripts on a given server. Administrators must grant you Editor permission for you to bind an agent to be run on a particular server.

To continue with the example from the previous section, only people who have write permissions on the monitored folder for the server EXCHNGE3 can cause agents (including scripts) in that folder to be run on the server EXCHNGE3. Like all public folders, the property sheets for the folder EventConfig_EXCHNGE3 contain a Client Permissions property page. A Microsoft Exchange administrator can, on this page, assign Editor permission to whoever should be able to run agents on the server—in this case, EXCHNGE3.


Writing and Installing Scripts

You can write scripts in VBScript, JavaScript, or another supported scripting language. You can use any script or text editor, including Microsoft Outlook version 8.03, and either Notepad or Microsoft Visual Studio 97. In fact, with a macro extension (an Add-In) installed, Microsoft Visual Studio can be used as a complete script creation tool. It lets you open, edit, and save scripts in folders within Microsoft Exchange information stores.

For details on configuring Microsoft Visual Studio to open, edit, and save scripts for use by the Microsoft Exchange Scripting Agent, please see the Release Notes for Microsoft Exchange Server version 5.5.


Using the Microsoft Script Debugger

To debug scripts that are running in the Microsoft Exchange Scripting Agent, you can use the Microsoft Script Debugger, which is available with Microsoft IIS version 4.0 or Microsoft Internet Explorer version 4.0. Because the Script Debugger is not included as part of Microsoft Exchange Server, you must install one of these other products. During installation, choose the Custom installation option and then select the Microsoft Script Debugger option.

The Microsoft Script Debugger performs only local debugging. Therefore, you must run the debugger on the computer on which the script is executing. In the case of the Microsoft Exchange Scripting Agent, this is the Microsoft Exchange Server computer on which the script is executing.

To force your script to hit a breakpoint and start the debugger, insert the following command into your script, under the event subroutine you wish to debug:

  • For VBScript, this command is stop.
  • For JavaScript, the command is debugger.

To use the Microsoft Script Debugger to step into Event Service code, you must first log on with the same Windows NT service account as the Microsoft Exchange Event Service itself; otherwise, the debugger will not be launched correctly when it reaches a stop (or debugger) statement in the code.

As soon as an event occurs that triggers your script's event subroutine, the script will halt, and you will see the currently running script in the debugger window at the line containing the stop or debugger statement. Inside the script debugger, you can step into or around statements and you can inspect the values of variables by using the immediate command window. See the documentation on Microsoft Script Debugger for more information on using this tool.


Writing a Script

Scripts used with the Microsoft Exchange Event Service primarily use CDO, although they exhibit some differences from pure CDO scripts. For example, the following points are good to remember:

  • You do not need to write code to log on to a CDO session, because you will be passed the named value EventDetails.Session as an intrinsic object.
  • You can write "asserts" or other debugging strings to the Agent's execution log by assigning the string as value to the intrinsic object Script.Response.


Intrinsic Objects

The Microsoft Exchange Event Service passes the following intrinsic objects when your script is run:

  • EventDetails.Session The object that represents the CDO session you're logged on as. Because a script is handed this logged-in CDO session, it automatically has access to all CDO objects. This session is logged on as the script author.
  • EventDetails.FolderID The entry identifier of the folder in which the event took place.
  • EventDetails.MessageID This is the identifier of the triggering message, if a message (and not a timer event) triggered the event.


Procedure for Editing Scripts

Using Microsoft Outlook, choose New Event, and then Edit Script. This creates a stub script that contains these empty subroutines:

  • Folder_OnMessageCreated
  • Message_OnChanged
  • Folder_OnMessageDeleted
  • Folder_OnTimer

(The preceding names are for VBScript. The corresponding JavaScript names are Folder::OnMessageCreated, Message::OnChanged, Folder::OnMessageDeleted, and Folder::OnTimer.)

You can add scripting code to any of these subroutine sections to control its functionality. To indicate that the script should not respond to an event of that type, just leave a section blank, or delete the section. Although this script could be written to respond to events of all four types, you could also choose to use separate scripts for each event.

Note: Using VBScript and JavaScript You can write a script in pure VBScript, pure JavaScript, or a mixture of the two. If you mix the two languages and you are making cross-language calls, you need to prefix variable names with the name of the language; for example, VBScript.MyVar or JavaScript.MyVar.


Editing Agents' Properties

You can have your script change the behavior of your agent in any of several ways. The script can, for example:

  • Change the events the agent fires on.
  • Edit the details of a schedule (for scheduled events).
  • Implement filtering.
  • Implement error logging.
  • Return assert and response strings (example: "now at line 27") for debugging purposes (using the command Script.Response=<string>).


The Sample Script OSPREV.VBS

The following sample script ships with Microsoft Exchange Server version 5.5 and above. It contains the four basic functions Folder_OnMessageCreated, Message_OnChange, Folder_OnMessageDeleted, and Folder_OnTimer.

Each of these event functions calls two support functions: first GetEventDetails, and then MakeResponseMessage, as described in the following sections.

The GetEventDetails Function

In addition to error checking, the function GetEventDetails performs the following steps:

  1. Using the CDO session, it establishes the location of the current user's Microsoft Exchange mailbox. It does this with the call
    Set AMSession = EventDetails.Session.
  2. It retrieves the user's Outbox with the call
    Set fldrOutbox = AMSession.Outbox.
  3. Using the EventDetails object passed by the Microsoft Exchange Event Service, this function sets an application folder ("target" folder) to be the same as the monitored folder in which the event occurred. It does this with the assignments
    idTargetFolder = EventDetails.FolderID and
    Set fldrTarget = AMSession.GetFolder( idTargetFolder, Null ).
  4. This function also sets a target message to be the same as the message that triggered the event. It does this with the assignments
    idTargetMessage = EventDetails.MessageID and
    Set msgTarget = AMSession.GetMessage( idTargetMessage, Null ).

The MakeResponseMessage Function

In addition to error checking, the function MakeResponseMessage prepares and sends a response message that reports the number of messages in the monitored folder. For this, it uses the CDO response object in the call msgResponse.Send.

Script Text: OSPREV.VBS

<SCRIPT RunAt=Server Language=VBScript>

'---------------------------------------------------------------------
'FILE DESCRIPTION: Sample Exchange Server Event Script for Osmium
'
' Copyright (c) Microsoft Corporation 1993-1997. All rights reserved.
'---------------------------------------------------------------------

Option Explicit

'---------------------------------------------------------------------
' Localized strings
'---------------------------------------------------------------------
' Put all localizable strings and constants here

'---------------------------------------------------------------------
' Global Variables
'---------------------------------------------------------------------

Dim AMSession
Dim fldrOutbox
Dim msgTarget
Dim fldrTarget

'---------------------------------------------------------------------
' Event Handlers
'---------------------------------------------------------------------

' DESCRIPTION: This event is fired when a new message is added to the folder
Public Sub Folder_OnMessageCreated
    On Error Resume Next

    GetEventDetails
    If Err.Number = 0 Then
        MakeResponseMessage "A message has been added"
    Else
        Script.Response = "GetEventDetails Failed"
    End If
End Sub

' DESCRIPTION: This event is fired when a message in the folder is changed
Public Sub Message_OnChange
    On Error Resume Next

    GetEventDetails
    If Err.Number = 0 Then
        MakeResponseMessage "A message has been changed"
    Else
        Script.Response = "GetEventDetails Failed"
    End If
End Sub

' DESCRIPTION: This event is fired when a message is deleted from the folder
Public Sub Folder_OnMessageDeleted
    On Error Resume Next

End Sub

' DESCRIPTION: This event is fired when the timer on the folder expires
Public Sub Folder_OnTimer
    On Error Resume Next

End Sub

'---------------------------------------------------------------------
' Support Functions
'---------------------------------------------------------------------

' DESCRIPTION: Get the details of the event that fired
Private Sub GetEventDetails
    On Error Resume Next

    Dim oStores
    Dim Temp
    Dim idTargetFolder
    Dim idTargetMessage

    idTargetFolder = EventDetails.FolderID
    idTargetMessage = EventDetails.MessageID

    ' some of the above may not exist
    Err.Clear

    Set AMSession = EventDetails.Session
    If Err.Number = 0 Then
        ' We will send a msg, so let's get the Outbox here
        Set fldrOutbox = AMSession.Outbox
        If Err.Number = 0 Then
                Set fldrTarget = AMSession.GetFolder( idTargetFolder, Null )
                If Err.Number = 0 Then
                    Set msgTarget = AMSession.GetMessage( idTargetMessage, Null )
                    If Not Err.Number = 0 Then
                        Script.Response = "Session.GetMessage Failed: " & Err.Description
                    End If
                Else
                    Script.Response = "Session.GetFolder Failed: " & Err.Description
                End If
            Else
                Script.Response = "Session.InfoStores Failed: " & Err.Description
            End If
        Else
            Script.Response = "Outbox.Messages Failed: " & Err.Description
        End If
    Else
        Script.Response = "EventDetails.Session Failed: " & Err.Description
    End If
End Sub

' DESCRIPTION: Make a response message
Private Sub MakeResponseMessage(strSubj)
    Dim msgResponse
    Dim iMsgCount

    On Error Resume Next

    iMsgCount = fldrTarget.Messages.Count
    If Err.Number = 0 Then
        Set msgResponse = fldrOutbox.Messages.Add( strSubj, "There are now " & iMsgCount & " messages in the folder")
        If Err.Number = 0 Then
            msgResponse.Recipients.Add "", "", 1, msgTarget.Sender.ID
            If Err.Number = 0 Then
                msgResponse.Recipients.Resolve(False)
                If msgResponse.Recipients.Resolved = True Then
                    msgResponse.Send
                    If Not Err.Number = 0 Then
                        Script.Response = "Message.Send Failed: " & Err.Description
                    End If
                Else
                    Script.Response = "Recipients.Resolve Failed: " & Err.Description
                End If
            Else
                Script.Response = "Recipients.Add Failed: " & Err.Description
            End If
        Else
            Script.Response = "Messages.Add Failed: " & Err.Description
        End If
    Else
        Script.Response = "Messages.Count Failed: " & Err.Description
    End If
End Sub

</SCRIPT>


Advanced Topics: Custom Agents

In the standard scenario of running an agent in a monitored public folder, an agent in that folder is routed by default to the script handler supplied by Microsoft® Exchange Server (the Microsoft Exchange Scripting Handler). But you may feel that scripting doesn't give fast enough performance, so you may want to use another handler in which event response code is hard-coded in C/C++. Or you may not want customers to see your source code, so instead of shipping scripts, you ship compiled code in binary format.

An agent that uses such a mechanism would probably contain no script, though it does contain some agent configuration data.


About Other Handlers

A handler is any COM object that exposes (implements) the IExchangeEventHandler interface and advertises (is registered under) the COM category CATID_ExchangeEventSink.

Other types of handlers could include those that can run Microsoft Visual Basic version 5.0 programs, JavaScript, Java VM code, and C++ code in addition to JScript or VBScript provided by Microsoft. Handlers can currently only be authored in C/C++.
The mechanism for processing folder events with custom handlers is similar to that used with the Microsoft Exchange Scripting Handler, as shown in the following diagram.


Invoking a Custom Agent

The following steps illustrate folder event processing and refer to elements in the diagram in the previous section. In this example, "Folder 3" is one of several folders configured to monitor events. The creation of the agents for this folder linked certain events that occur in Folder 3 to a script placed in Folder 3.

Although the usual case when an event occurs is for a script to be run, custom agents can also be used. This is because The Microsoft Exchange Event Service can pass an event to any agent that exposes the COM interface IExchangeEventHandler.

  1. A message is posted to Folder 3, a folder being monitored by the Event Service.
  2. A notification of the posting is sent to the Event Service.
  3. The Event Service calls an Incremental Change Synchronization (ICS) method to request all the changes to Folder 3 that have occurred since the last time an event occurred in that folder.
  4. ICS generates and sends the change list to the Event Service. This list contains the message identifier of the message just posted and any other changed messages—including new, changed, and deleted messages.
  5. The Event Service searches the monitored folder for agents.
  6. The Event Service requests the agent for the CLSID of its handler.
  7. The Event Service calls CoCreateInstance to create an object of that CLSID.
  8. The Event Service performs a QueryInterface for the IExchangeEventHandler interface.
  9. Once the Event Service has retrieved the IExchangeEventHandler interface on the object, it writes session, folder, and message information into properties in a Microsoft Exchange IEventSource object. The Event Service also sets the event type (new message, changed message, deleted message, timer event) in a property on the IEventSource object.
  10. The Event Service calls IExchangeEventHandler::ExecuteEvent, passing the IEventSource object.
  11. Using the IEventSource object passed from the Event Service, the custom handler responds to the folder event.


Programming Recommendations

Consider the following recommendations when designing a custom agent.

  • Be careful with security, because the MAPI session that you're passed has powerful permissions within Microsoft Exchange Server. Be particularly careful when handing control to another element in the system, especially if you are not the creator of that other element.
  • The EventSource object is provided by Microsoft, so to use it, all you need are the proper header files.
  • Do your own exception handling by watching out for exceptions and access violations.


Caching Sessions and Scripts

Your handler's design depends in part on the number of folders it will be used in and the workload (number, or volume, of events) it will carry within a folder. One affected design element is whether to cache a CDO session and a script. Consider the following cases:

  • Few folders, high volume per folder For example, an agent functioning as a distribution list could broadcast any item posted to the monitored folder to the members of the list. Caching the members of the list could help in this example since list membership is not likely to change as often as messages are being posted.
  • Many folders, low volume per folder Caching would be less helpful in this case.
  • Many folders, high volume per folder An example of this case is a script agent used in many folders on a server; This case could occur, for example, when many of a system's recipients use script agents in folders within their private mailboxes. Caching information specific to each mailbox would probably help in this case.

In general, caching is more likely to help if high volume is involved.

In the case of the Microsoft Exchange Scripting Handler, if a new CDO session (which includes a logon to MAPI) had to be created every time a script fired, performance would suffer greatly. In this case, the session object (using the mailbox of the script author) is cached, which helps greatly. In other words, if a new script is run whose author also created another recently run script, that person's CDO session, having been cached, is reused. The script itself is also cached, to be used when the next event triggers it.

CDO Sessions and MAPI Sessions

The session that is passed to you is a MAPI session from the service, not a CDO session. This precludes Microsoft Visual Basic handlers from using it, because Visual Basic can only manipulate the IDispatch interface, an interface that MAPI does not support.

If your custom agent is written in Microsoft Visual Basic, it will need to perform its own CDO session logon.


Registering a COM Object as an Agent

In addition to the normal registration of your COM object you need to put the following information into the registry:

HKEY_CURRENT_USER \ CLSID \ {Your CLSID} \ Implemented Categories \ {50F45350-D0AF-11d0-9836-00AA006D27AB}
    (Default Value) = 'Exchange Event Handler Category'


About the IExchangeEventHandler Interface

Every agent must implement the IExchangeEventHandler interface in its object. This interface has one method:

ExecuteEvent( IDispatch* pEventSource)

An EventSource is a COM object that exposes one interface: IEventSource. It has no methods, just the following properties:

Property | Description
Source | MAPI object (the agent message in the target folder)
SourceID | Entry identifier of the agent message in the EventConfig_<ServerName> folder
MessageID | Entry identifier of the message that was changed, added, or deleted (NULL for timer events)
Session | The MAPI session passed from the Microsoft Exchange Event Service
EventType | The type of event that occurred (an integer enumeration: 0, 1, 2, or 3)
MaxExecutionTime | Seconds of execution from beginning of agent execution until agent execution is terminated.
Response | Put a string here to record the outcome of the agent's execution. The string is written to the event log. The Response property is a variant, but the Event Service expects a string (if not a string, it will be ignored).


Administrators Set Up Handlers

If you write and distribute your own custom handler or buy a third-party handler for your own system, it's likely that a setup program will be distributed. If not, the agent must be registered manually, and its files copied. In either case, a server administrator is the person to set up the agent.

Similarly, if you're a folder author and you want to install a new agent that uses the handler you've written, you need to request that your server administrator install your handler.

For more information about administrators' roles, see Microsoft Exchange Server Administration and the Microsoft Exchange Server Getting Started Guide.


Security with Custom Handlers

You may want to limit the power of your custom handler. To do this, you can incorporate code that diminishes its power by, for example, impersonating a Windows NT® account that has fewer permissions.

One way to accomplish this is to implement your handler (COM object) as a Microsoft Transaction Server (MTS) object. In addition to providing support for database transactions, MTS also can act as a process manager for in-process COM objects. You can use MTS to specify that your object is always to run under a specific Windows NT security account – one that has sufficiently low privileges for your application.


Forms

To develop forms-based applications for Microsoft Exchange Server, you use MAPI forms interfaces. These interfaces give you the ability to define custom forms, install them in forms libraries, and supply them to users of Microsoft Exchange Server. You can also develop forms with the Microsoft Exchange Forms Designer, which in turn calls the MAPI forms interfaces. For more information on creating forms, see the MAPI Programmer's Reference, and the Microsoft Exchange Server Application Designer's Guide.

Any MAPI-compliant forms application can run in the Microsoft Exchange Server environment. Developers of these applications can take advantage of the following facilities of Microsoft Exchange Server:

  • Organization forms library Stores forms for an entire organization.
  • Folder forms libraries Allows users to install folder-specific forms.
  • Conflict-resolution capability Can be invoked when multiple versions of same message have been created by different users.


About the Organization Forms Library

In MAPI, a form library is a storage area where you can install and access forms. Microsoft Exchange Server provides a special form library called the organization forms library, which has the following characteristics:

  • It resides in the public information store as a hidden public folder and is replicated throughout the organization to facilitate access to forms. This library is a single folder stored on an organization's central messaging servers. It contains forms that are available to all users within the organization. This single-folder storage makes organization-wide form management possible. For example, to enhance the availability of forms throughout an organization, the organization library can be easily replicated across multiple servers simply by copying one folder.
  • It contains only folder-associated information; there are no user-visible messages or folders in it. Usually one organization library is associated with each server-based information store.
  • It is partitioned into at least two classes of entries: those that are displayed in the library browser for sending person-to-person, and those that are shared link targets of entries in folder libraries or are old forms that should be available for reading but not sending.
  • It is specific to organizations using Microsoft Exchange Server. Organizations where MAPI is used, but Microsoft Exchange Server is not, will not have an organization forms library unless the custom forms manager that is being used supports one.


Installing Forms into the Organization Forms Library

Administrators usually install new forms into the organization forms library if users throughout the organization need access. You can also install forms into this library programmatically, subject to the access rights under which your program is running.

To install a form into the organization forms library
  1. Obtain a MAPI session. Do this by initializing MAPI with the MAPIInitialize function and logging on to a MAPI profile with the MAPILogonEx function. For more information, see the first steps of Opening an Information Store. To install forms, this MAPI profile needs Create permission on the organization forms library.
  2. Open the MAPI form manager interface by calling the MAPIOpenFormMgr function and passing a pointer to the MAPI LPMAPISESSION session. This call opens an IMAPIFormMgr interface on a forms-library provider object.
  3. Open the organization forms library by calling the MAPI IMAPIFormMgr::OpenFormContainer method . Pass the HFRMREG_ENTERPRISE constant for the hfrmreg parameter. This denotes the organization's Microsoft Exchange Server library in the public information store.

    When IMAPIFormMgr::OpenFormContainer detects HFRMREG_ENTERPRISE, it returns an interface pointer to the organization forms library. You can then call any of the MAPI-defined forms container methods.

  4. Install the form with a call to the IMAPIFormContainer::InstallForm function, passing a pointer to the name of the configuration file for the form.

The INSTFORM.EXE sample application is a command-line utility that installs or removes a Microsoft Exchange Server form. You can run it to study the installation of forms, and you can look at its source files (in particular INSTFORM.CPP), which are located in the \BKOFFICE\SAMPLES\EXCHANGE\INSTFORM directory. Some of the code from INSTFORM.CPP is reproduced here:

hr = MAPILogonEx(
        NULL, lpszProfile, lpszPassword,
        MAPI_LOGON_UI|MAPI_EXTENDED|MAPI_NEW_SESSION,
        &lpMAPISession);

// Open form manager interface.
hr = MAPIOpenFormMgr( lpMAPISession, &lpFormMgr);

// Open appropriate form container.
hr = lpFormMgr->OpenFormContainer( hFrmReg, lpFolder, &lpFormContainer);

hr = lpFormContainer->InstallForm( NULL, ulUIFlags, UserParams.m_pszCfgFile);

For more information about MAPI form libraries, see the MAPI Programmer's Reference.


Resolving Message Conflicts with Forms

Although custom forms are commonly used for composing or reading messages, they can also be used for resolving message conflicts. Such a form must contain code that checks the message status every time the form is launched. If the MSGSTATUS_IN_CONFLICT flag is set, the form knows to invoke its conflict resolution functionality (which includes a conflict-resolution user interface) instead of its compose or read functionality.

Note Microsoft Exchange Server can handle message conflicts in one of three ways, depending on the value of the PR_RESOLVE_METHOD property. If this property is set to invoke default behavior, one of the actions taken by Microsoft Exchange Server is to set the MSGSTATUS_IN_CONFLICT bit in the MAPI PR_MSG_STATUS property of the winning message. For more information, see Specifying the Resolution Method with PR_RESOLVE_METHOD.

To register a form for conflict resolution, set the GUID for one of the form's extension properties in the [Extensions] section of the form's .CFG file. For this GUID, use the value given in the following example in the line starting with NmidPropset=. The [Extension.1] section indicates that the form can handle its own conflicts. This prevents the Microsoft Exchange Client from displaying its conflict-resolution user interface for forms of this message's class.

[Extensions]
Extensions1=1

[Extension.1]
Type=11
NmidPropset={77f69534-6b7d-101b-9f0d-00aa003ba905}
NmidInteger=0
Value=1

If these lines are detected in the form's .CFG file, Microsoft Exchange Server starts the forms server when a conflict occurs.

If a forms server checks a message's PR_MSG_STATUS property and finds the MSGSTATUS_IN_CONFLICT bit set, it can try to resolve the conflict detected by Microsoft Exchange Server. To do this, the forms server opens the attachment table and searches for attachments that have the PR_IN_CONFLICT property set to TRUE. For more information, see Automatic Conflict Resolution. For general information on conflict resolution, see Handling Message Conflicts.


Using the MS_EXCHANGE_01 Property

When a user of the Microsoft Exchange Client opens a message, the form that displays the message must open it properly and display correct values in its controls. Forms created by the Microsoft Exchange Forms Designer use the MS_EXCHANGE_01 property to perform these actions.

Note The MS_EXCHANGE_01 property is a named property, and as such does not appear in any Microsoft Exchange Server header file. For more information on named properties, see the MAPI Programmer's Reference.

The first time a message is opened by a form, the MS_EXCHANGE_01 property is not present. In this situation, the form initializes the values of the controls it displays on the message and does not attempt to read any property values to display in those controls.

When saving a new message, the form must create this property and set its value to FALSE (zero) or TRUE (nonzero). If the property is set to FALSE, the message will be treated as a Response form when it is opened. This means that values to be displayed in the message's controls are initialized, and certain properties present on the original message are read and displayed.

If the MS_EXCHANGE_01 property is set to TRUE, the message is treated as a Send form when it is opened. This means that the properties of the original message are simply read and displayed.

These actions are summarized in the following table:

How Forms Use the MS_EXCHANGE_01 Property

Value of MS_EXCHANGE_01 | Method of Opening Message | Initialize values? | Read Properties?
empty | Create new (Send form) | yes | no
TRUE | Read | no | yes
FALSE | Create new (Response form) | yes | yes

The MS_EXCHANGE_01 property is also used with the FIMPORT sample application, which allows users to save items to folders and ensure their correct behavior with the Forms Designer. Use the /EFD switch to create the MS_EXCHANGE_01 property and set it to TRUE on each new message; use /NOEFD to forego the creation of this property. For more information, see FIMPORT: Importing Folder Information.

For more information on designing forms and setting properties on them, see the Microsoft Exchange Server Application Designer's Guide.


Administrator Program Extensions

A server application's directory object makes the application visible to the Microsoft Exchange Server Administrator program Through the Administrator program, administrators manage an application's directory attributes by using its object's property sheet. Property sheets are composed of one or more property pages. You can extend the Administrator program to include custom property pages, and you add property pages by creating Administrator extension DLLs.

You can also create new data fields for a directory object, control these new fields through custom property pages, and manage this application-specific extension data. These property pages can be used by administrators to view other data accessible on a Microsoft Exchange Server system, such as data in an information store. The Extension-Data attribute is used to associate these new data fields with your application's directory object. Special Administrator extension functions provide support for the Extension-Data directory attribute. Extension data is commonly used to configure an application's behavior.

Several sample applications included with this SDK illustrate the installation and use of Administrator extension DLLs that extend the abilities of the Administrator program. They include the Queue Viewer (QUEVIEW), the Extension Data Viewer (EXTDATVW), the Mailbox Extension sample application (MBXSERV), the Sample Mailbox Agent (SMBAGENT), and the Sample Gateway.

Benefits of Extending the Administrator Program

Although you can write your own custom administration interfaces for your server application, it is usually more efficient to extend the Administrator program. Benefits of using Microsoft Exchange Server Administrator extensions include the following centralized administration capabilities:

  • A single program The Administrator program can be used to control a wide range of applications from many different vendors. Performing administration tasks at a central location can standardize and thus streamline the work of an administrator.
  • Advanced features Advanced features of the Administrator program, such as remote administration, are available to all applications.
  • Replication The Microsoft Exchange Server directory is replicated across an entire organization. Storing objects in the directory leverages this automatic replication mechanism.
  • User interface The Administrator program provides a user interface, so you don't need to write one for your server application. Using this user interface eliminates the need for users and administrators to learn an additional user interface.


Adding New Property Pages

The primary duties of a Microsoft Exchange Server administrator are basic operations such as creating mailboxes, managing the basic components of Microsoft Exchange Server, and directory object management. Administrators perform most of these tasks—including all server control and maintenance actions—by using property sheets to manipulate objects in the Microsoft Exchange Server directory.

Each property sheet is made up of one or more property pages. Within the property sheet, controls are visible only on the front property page. Additional property pages are displayed one at a time when the administrator selects a tab. The General property page of the Sample Server Application object's property sheet is shown in the following figure.

A property sheet with ten property pages

For complete information on property sheets and the Administrator program, see the Microsoft Exchange Server Administrator's Guide.


Creating an Administrator Extension DLL

To create a new property page, you must create an Administrator extension DLL using functions and structures from the following libraries:

  • Win32 API Used to create property pages as Windows dialog boxes, using standard Win32 Common Controls.
  • Administrator extension functions Enables communication between the Administrator program and the Administrator extension DLL. This includes two groups of functions, one group called by the Administrator program and one group called by the Administrator extension DLL.
  • CAdminDialog class Used to create property pages. This C++ class interface is implemented in the EXADMIN library. For more information on these C++ classes, see Implementing Extensions with the CAdminDialog Class.
  • Configuration functions Enables you to manipulate extension data when reading it from or writing it to the Microsoft Exchange Server directory. Functions are included with this SDK. See Using the Configuration Functions.
To create an Administrator extension DLL
  1. Design a Windows dialog-box resource for each custom property page that will be added.
  2. Make sure each property page dialog-box resource contains controls for an icon, a title, and a standard Windows dialog-box message procedure. See Designing Property Pages.
  3. Implement an ADMIN_Initialize function and export it through the .DEF file of the DLL. Administrator program functions called from the DLL (such as PADMIN_GetObjectData and PADMIN_SetObjectData) are passed to the DLL through the ADMIN_Initialize function. The following lines from the SMBADMIN.DEF file show how to do this. SMBADMIN.DEF declares the module parameters for the property page used by the Sample Mailbox Agent.
    EXPORTS    ; Explicit exports can go here
    ADMIN_Initialize    @2
  4. Implement the functions in the DLL that will be called by the Administrator program. The InitSheetProc function is particularly important, because it supplies information to the Administrator program about the new custom property pages such as dialog-box resource IDs and dialog-box message procedures.


Designing Property Pages

Property pages are dialog boxes that you create with a Windows resource editor. They have specific design requirements.

To design a property page dialog box
  1. The following two controls are required on every property page:
    ICON 6031, IDC_ADMINICON,6,6,18,20,WS_GROUP
LTEXT "", IDC_TITLE, 35,8,180,16, WS_GROUP

    These controls define standard positions for displaying a title and an icon on the property page. When the property page dialog box is initialized, it is sent a WM_INITDIALOG message. The Administrator extension DLL calls the PADMIN_SetIcon and PADMIN_SetTitle functions to specify where the icon and title are to be displayed, by passing the IDC_ADMINICON and IDC_TITLE resource IDs to the Administrator program.

    The Platform SDK Resource Editor can be used to create the Icon and Text controls, paying attention to the pixel positions that indicate control size and screen placement. Alternatively, you can type the two lines above, verbatim, into your RC file using a text editor.

  2. Create at least one tab-stopped control for each property page.
  3. Write a standard Windows dialog procedure for each property-page dialog box.
  4. Make sure that the hwnd handle you supply to the dialog procedure of your custom property page is the hwnd handle of the property page itself, not the hwnd of the entire property sheet.

    This is important if you intend to display child message or dialog boxes from within the custom property page. In this case, the parent of the hwnd handle should be passed. You can easily obtain this handle by using the Win32 GetParent function. Failing to pass the hwnd handle of the parent window will cause your new dialog box to be nonmodal. This procedure is illustrated in the validation code in the SGWADMIN.CPP file, which is the extension DLL of the sample gateway application. The SGWADMIN.CPP file is located in the BKOFFICE\samples\exchange\SGWADMIN directory.

    The bValidate member function displays a message box and passes the correct hWnd handle if the user enters invalid data.

Note One Administrator extension DLL can support multiple languages. This means you do not have to write additional DLLs if you must localize your application. The Microsoft Exchange Server Administrator program is currently localized into French, German, English (US), and Japanese versions.


Using the Administrator Extension Functions

To create an Administrator extension DLL, you use the Administrator extension functions and structures that are defined in the ADMINEXT.H file. Two main categories of functions are used to create an extension DLL:

  • Administrator extension functions (called by Administrator Program) You provide these functions in your Administrator extension DLL. The Microsoft Exchange Server Administrator program calls these functions to retrieve information about your property pages and to inform your extension DLL of events. For example, the CommitDataProc function is called when the Apply button is clicked, and tells the extension DLL to store its data permanently.
  • Administrator extension functions (called by extension DLL) This set of functions allows your extension DLL to communicate with the Administrator program. They are used to retrieve and save extension data. They also provide functionality that makes custom property pages behave like standard property pages displayed by the Administrator program.


Using Administrator Extension Functions (Called by Administrator Program)

The following table lists function calls made to the Administrator extension DLL from the Microsoft Exchange Server Administrator program. The Purpose section of the table describes whether the function's presence in the extension DLL is mandatory or optional. If you choose not to implement an optional function, you must pass NULL to the Administrator program to indicate that the function is not implemented.

Except for the ADMIN_Initialize function, entries in the following table refer to prototypes of functions that you write and use in the extension DLL. For more information on the use of these functions, see ADMINEXT.H.

Administrator Extension Functions (Called by Administrator Program)

Function | Purpose | When called
ADMIN_Initialize | Mandatory DLL entry point. This function is called explicitly, not through a pointer reference, and for this reason must have the name ADMIN_Initialize. Initiates handshaking, giving your DLL three MAPI interface pointers (a session handle, an address book object pointer, and an address book container pointer) and pointers to the Administrator extension functions provided by the Administrator program. You need to pass back a list of pointers to the remaining functions listed in this table. For further details, see the information about initializing connections with ADMIN_Initialize in Initializing the Administrator Extension DLL. | After the DLL has been loaded and initialized by Windows.
InstallExtensionProc | Not currently called by the Administrator program. | Not called by the Administrator program.
DeinstallExtensionProc | Mandatory. Called by the Administrator program to report that your object is being deleted. | Called when deleting the directory object.
InitSheetProc | Mandatory. Used by the Administrator program to query the Administrator extension DLL for descriptions of the property pages it supports. See Initializing Property Pages with InitSheetProc. | Called once only, after ADMIN_Initialize has been called.
ShowPageProc | Optional. Tells the Administrator program whether to show standard property pages. It is called once for each standard property page, but not for the extension property pages. Your DLL can prevent a standard page from being displayed by returning FALSE. | After InitSheetProc has been called.
StartPageProc | Optional. Tells the Administrator program which custom property page to display first by returning its index. Omit this function (pass NULL for its function pointer) or return -1 to display the first standard sheet. | Called one time only, after ShowPageProc has been called.
HasHelpProc | Optional. Tells the Administrator program whether the sheet has an associated online Help file. Called for each extension property page in your extension DLL. Return TRUE if the specific sheet has online help. | As each property page is displayed.
DoHelpProc | Optional. Displays sheet-specific Help when the Help button is selected for the active property page. | When Help button is pressed.
SaveDataProc | Optional. When another property page is selected, SaveDataProc is called for the original property page. When OK or Apply is pressed, the Administrator program calls both this function and CommitDataProc. SaveDataProc and CommitDataProc are used together to support multistep data commitment. The SaveDataProc function can be used to validate data in the property page controls, or to copy data from field buffers to an undo buffer. Do not use the SaveDataProc function to save data permanently, or it will be difficult to undo changes if the user clicks the Cancel button. | When a new property page is selected or when the OK or Apply button is pressed.
CommitDataProc | Optional. Instructs the Administrator extension DLL to store data permanently. CommitDataProc should be called only when the OK or Apply button is clicked. When the administrator moves between property pages, SaveDataProc is called to make sure that temporary buffers are updated. This is particularly important when several property pages access the same temporary buffer. | When the OK or Apply button is pressed.
DeinitSheetProc | Mandatory. Called to notify the Administrator extension DLL when the property sheet dialog box is about to be destroyed. | After all property page dialog boxes are destroyed.

Structures listed in the following table communicate information between the Administrator program and the Administrator extension DLL. They are used by the functions listed in the preceding table:

Administrator Extension Structures

Structure | Description
ADMIN_AdministratorConnections | Contains useful connections (MAPI session information) made by the Administrator program.
ADMIN_AdministratorFunction | Contains a list of pointers to the Administrator extension functions (called by extension DLL)
ADMIN_ExtensionFunction | Contains a list of pointers to Administrator extension functions in the Administrator extension DLL. This structure is filled in by the extension DLL, and then passed back to the Administrator program during the DLL initialization process.
ADMIN_ObjectInfo Contains the following information:

· Name of the computer on which the application is running.

· DN of the object being administered.

· DNs of the home server running the information store and the message transfer agent.

· Language that the Administrator program is running, so that the extension DLL can match this language.

· Class of the object being manipulated. An extension DLL should verify that it is running against an object class that it supports. To do this, it uses the list of the object identifiers in ADMINEXT.H.

· Handle to the font that should be used if the extension DLL has any additional dialog boxes of its own that it draws separately from the property pages.
ADMIN_SheetInfo | Specifies a property page dialog box.


Using Administrator Extension Functions (Called by Extension DLL)

The following table lists functions found in the ADMIN_AdministratorFunction structure that is passed as a parameter to your ADMIN_Initialize function. These functions are implemented by the Administrator program and can be called from the Administrator extension DLL:

Administrator Extension Functions (Called by Extension DLL)

Function | Purpose | When to call
PADMIN_GetObjectDataSize | Returns the size in bytes of the Extension-Data attribute associated with a given owner tag. Use this function to determine how much memory to allocate for creating a copy of the Extension-Data attribute. | Before reading extension data out of the directory object, such as during initialization when your property page receives the WM_INITDIALOG message.
PADMIN_GetObjectData | Copies the contents of the Extension-Data attribute associated with a given owner tag. | When you need to read extension data out of the directory object, such as during initialization when your property page receives the WM_INITDIALOG message.
PADMIN_SetObjectData | Writes a block of data to the directory object's Extension-Data attribute. Does not automatically add an owner tag to the binary data block: this is the developer's responsibility. The configuration functions support the addition of owner tags to the structure binary block they create. | When the CommitDataProc function is called.
PADMIN_AddService | Directs the Administrator program to add a service to the list of monitored services. | At any time.
PADMIN_RemoveService | Directs the Administrator program to remove a service from the list of monitored services. | At any time.
PADMIN_InfoHasChanged | Signals the Administrator program to enable the Apply button. | When property page information is changed.
PADMIN_SetIcon | Supplies the control identifier for the standard property page icon to the Administrator program. | When your dialog box receives the WM_INITDIALOG message.
PADMIN_SetTitle | Supplies the control identifier for the standard property page title to the Administrator program. | When your dialog box receives the WM_INITDIALOG message.
PADMIN_GetNameList | Gets the routing table (the address list) of this application. | When access to the routing table is needed.
PADMIN_FreeNameList | Frees the routing table (frees memory used for the address list) for this application, a Mail-Gateway object. | After the routing table is accessed.
PADMIN_SetNameList | Saves changes to the routing table for this application, a Mail-Gateway object. Also causes the Address Space property page to be updated with these changes. | As routing table information is accessed.
PADMIN_LoadDialogResource | Loads a dialog-box resource from the DLL for a given language and sets its font to match that used by Admin. | Before displaying any child dialog boxes of a property page.
PADMIN_FreeDialogResource | Deletes a dialog-box resource allocated by PADMIN_LoadDialogResource. | When you have finished using the child dialog box.


Initializing the Administrator Extension DLL

The Administrator program and the Administrator extension DLL work together to display standard and custom property pages. They can communicate because each supplies the other with the necessary function entry points. This handshaking procedure involves two initializations that usually occur in the following sequence:

To perform an initialization sequence
  1. An administrator selects a directory object that uses one or more custom property pages.
  2. The Administrator program opens the directory object and finds the extension DLL for it.
  3. The Administrator program loads the extension DLL.
  4. The Administrator program looks for the extension DLL entry point (ADMIN_Initialize).
  5. The Administrator program calls the extension DLL entry point. The Administrator program can now locate the DLL functions, and the DLL can now locate the Administrator program functions.
  6. The Administrator program calls the extension DLL InitSheetProc function to read the information about the property pages supported by the extension DLL.

In this sequence, two initialization procedures have been executed—the initialization of functions and connections for the DLL and the initialization of property pages. These initialization procedures are described in the following sections.


Initializing Connections with ADMIN_Initialize

This first initialization establishes connections for the DLL and informs the Administrator program of the available functions within the DLL. This initialization is performed by calling the ADMIN_Initialize function in the extension DLL.

Important This initialization is not the same as the one performed with the Win32 DLLMain function.

The function name must be ADMIN_Initialize (verbatim) and exported from the DLL. It is the only function that must be exported from the DLL. The Administrator program calls the function, passing two input parameters and one output parameter. Parameters passed include:

  • ADMIN_AdministratorConnections * pAdminConnections Ιnput parameter. This structure gives information on connections, the MAPI session pointer, the Address Book pointer, and the Address Book container pointer.
  • ADMIN_AdministratorFunction * pAdminFunctions Ιnput parameter. This structure is a list of function pointers in the Administrator program. The Administrator program is informing the DLL of a set of functions that it can use. For a list of functions provided by the Administrator program, see Using the Administrator Extension Functions.
  • ADMIN_ExtensionFunction ** ppExtensionFunctions Output parameter. This structure contains pointers to functions. Your extension DLL must set its elements to point to functions that you support. For a list of functions you need to provide, see the information about DLL functions in Using the Administrator Extension Functions.

As a result of the ADMIN_Initialize function call, the Administrator program passes a MAPI Address Book interface pointer to the extension DLL. The extension DLL can use this pointer to display an address selection user interface or any other MAPI functionality implemented by the Address Book object. For example, your application might be a mailbox agent that can mail a daily status report to a certain recipient. By having a handle to the Address Book object, your extension DLL can support the ability to let an administrator select a destination for these messages.

If you plan to use any of the MAPI interface pointers contained in the ADMIN_AdministratorConnections structure, you will need to make a copy of these pointers and make a call to the interface's AddRef function. You must do this in your DLL's ADMIN_Initialize function. You need to copy only the pointers that you will be using. Remember to call the MAPI Release function for each pointer when you finish using it.

The ADMIN_Initialize function returns void, so any errors must be handled internally by your DLL. If a severe error occurs, the InitSheetProc call can return an error.

The following is an example of an ADMIN_Initialize function:

// $--ADMIN_Initialize()----------------------------------------------
// Exported function. This is the first function called by Admin after
// the DLL has been initialized by Windows.
// -------------------------------------------------------------------

extern "C" VOID PASCAL ADMIN_Initialize(
    IN  ADMIN_AdministratorConnections* pAdminConnections,
    IN  ADMIN_AdministratorFunction*    pAdminFunctions,
    OUT ADMIN_ExtensionFunction**       ppExtensionFunctions)
{
    if( we want to use the MAPI session handle)
    {   // Keep a global copy of the MAPI session handle pointer.
        pMAPISession = pAdminConnections->psesMapi;
        pMAPISession->AddRef();
    }

    // Tell Admin where it can find the rest of our
    // functions that it needs.
    *ppExtensionFunction = &extensionFunctions;
}
// ---------------------------------------------------------------------


Initializing Property Pages with InitSheetProc

The purpose of the second initialization is to inform the Microsoft Exchange Server Administrator program about the property pages supported by the Administrator extension DLL. The Administrator program calls the InitSheetProc function, which is implemented by the extension DLL, and passes five parameters to the DLL:

  • ADMIN_ObjectInfo * poi Input parameter. This structure contains information about the object for which the property page is being displayed. It gives the name of the computer on which the application is running, the distinguished name (DN) of the object being administered, and the DNs of the home server running the Microsoft Exchange Server information store and the home server running the message transfer agent (MTA).

    The ADMIN_ObjectInfo structure contains the field uObjectID. This field contains an object identifier code that specifies the object type whose property sheet is being displayed. If the extension DLL does not support the object type at this point, it should fail to initialize. The property pages provided by the Administrator program will still display, but not the property that the extension DLL would have displayed. The ADMINEXT.H file contains the object identifier codes to which the uObjectID field can be set.

  • ULONG fFlags Input parameter. One flag is possible here: fxfReadOnly. The top eight bits of this ULONG can be used by the extension DLL for any purpose. The Administrator program guarantees them to be zero. For example, this parameter is used by an extension DLL that can also be run by another program such as a test application.

    If the fxfReadOnly flag is set, the extension DLL must ensure that it does not expose any functions that would change the directory object. DLL access privileges to other resources such as the Windows NT Registry might also be read-only.

  • ADMIN_SheetInfo ** ppsi Output parameter. The DLL must create an array of ADMIN_SheetInfo structures — one element for each property page you're adding to the dialog box. The structure contains the following members:
  • hinstance The instance of the DLL. It is the same in each array element.
  • iddDialog The resource identifier of the dialog box.
  • lpfnDlgProc A pointer to a Windows dialog procedure function. This points to a function in your DLL that processes all windows messages for this dialog box.
  • idsName Identifier for a resource string. This gives the administrator the option of changing the property page name on the fly, using a resource editor.
  • lParam Any information may be placed in this parameter that fits into four bytes. Later, it is passed to the Windows dialog procedure function when the WM_INITDIALOG message occurs (once per dialog box). For example, you can use this to point to a C++ object that will manage the dialog box.
  • UINT * pcsi Output parameter. The number of property pages.
  • VOID ** ppvExtensionData Output parameter that can be used for any data you want maintained and passed back to other functions in the interface.

Because the Administrator program knows the resource identifier of the dialog box after these initializations have been performed, it now calls the Windows CreateDialog function for each custom property page. After that function call, the extension DLL receives Windows messages. The Administrator program makes this call only if the tab for the custom property page is selected. If the user never looks at your property page, the Windows dialog procedure is not called.

The Administrator program displays the dialog box that contains extension property pages, but the functions that handle Windows messages to the dialog box are located in the extension DLL. The Administrator program will also communicate with your dialog box by calling the functions that you returned in the ADMIN_Initialize function.

If an error occurs during initialization, returning FALSE causes the Administrator program to display an error message to the user and not display the property pages for the object. If your DLL failed, you may still want to return TRUE and display a reduced (possibly zero) number of custom property pages.

For a list of functions that the DLL passes back to the Administrator program, see Using Administrator Extension Functions (Called by Administrator Program).


Inhibiting Standard Property Pages

During the handshaking procedure between the Microsoft Exchange Server Administrator program and the Administrator extension DLL, the Administrator program calls the ShowPageProc function once for each property page that is standard for the object type, and passes a property page identifier. Property page identifiers are defined in ADMINEXT.H.

To inhibit the display of a standard property page

When the Administrator program calls the ShowPageProc function in your DLL, return TRUE if you want the page to be displayed (default behavior). If you do not want the page to be displayed, return FALSE.

In the following code sample, the Activation Schedule property page is inhibited:

PASCAL BOOL ShowPageProc(UINT iddAdminPage)
{
if (iddAdminPage == iddGWSchedule)
return (FALSE);
else
return (TRUE);
}


Completing the Administrator Extension DLL

After you have coded the Administrator extension DLL, several tasks remain:

  • Testing
  • Documenting the Administrator extension DLL
  • Creating an online Help file
  • Installation

To test an Administrator extension DLL
  1. Make sure the Administrator extension DLL is properly installed and accessible through the Administrator program. See Installing the Administrator Extension DLL.
  2. Run the Administrator program and verify that all expected standard and custom property pages appear correctly.

    When an error occurs, the Administrator program provides information in an OutputDebugString. To view its contents, run the Administrator program with a debugger.

  3. Change each option on each property page. Observe the application's response to each change to make sure it is correct. For example, the Apply button should be enabled after each change. An important aspect of the application's behavior is the immediacy of its response. That is, have you programmed the application to respond to the change right away, or not until the next time it is launched? In both cases, does it respond at the right time?


Documenting New Property Pages

You need to provide documentation to your customers to help administrators plan the application's configuration by identifying and choosing options needed to meet the organization's messaging requirements. To select the appropriate combination, administrators need to understand the benefits, effects, and relationship of these options.

Administrators should be able to plan for and implement:

  • Required messaging and network topology options.
  • Application operating options required for their organization. Depending on the application's functionality, these options could include message addressing, message and attachment conversion, service accounting, and user access to the application.


Creating Online Help

The online Help file supplied with the Administrator extension should provide administrators with instructions for setting up and configuring the application using the application-specific property pages.

For the property pages that display extension data, you need to create and supply the online Help file with your application. Follow the procedure below to create an online Help file for the property pages governed by the extension DLL.

To create online Help files
  1. Write the Help file, using a text editor that can produce files in the required rich text format (RTF). Microsoft Word is recommended.
  2. Add hypertext jumps and other features you want your Help file to offer. For more information, refer to the Tools User's Guide of the Microsoft Win32 Software Development Kit.
  3. Save the Help text file in .RTF format and compile the .HLP file.


Installing the Administrator Extension DLL

To add property pages to a directory object, you install an Administrator extension DLL by adding and configuring an Admin-Extension object in the directory. You assign a name to this Administrator extension by setting its Extension-Name attribute. You may, for instance, set it to match the service name. The Administrator program builds a Common-Name attribute for the extension from the Extension-Name attribute and the hardware platform designation, in this way:

<extension-name>:<hardware-platform>

For example, you may assign the name GWSample to the Extension-Name attribute for a service called GWSample. If the platform is i386 (Intel), the Common-Name is set to GWSample:i386.

An Administrator extension DLL is associated with a directory object when the <extension-name> part of the Admin-Extension object's common name is written into the Extension-Name attribute of the directory object. The name of the extension DLL file is recorded in the Admin-Extension-DLL attribute of the Admin-Extension object.

Determining the Destination Directory for the Administrator Extension DLL

The installation program also must copy the new Administrator extension DLL into a subdirectory of the ADD-INS directory share, which is created when Microsoft Exchange Server is installed. This subdirectory is determined as follows:

\\SERVER\ADD-INS \<extension-name>\<hardware-platform>

Example: the MS Mail Connector

When the MS Mail Connector is installed, it creates an Admin-Extension directory object in the Add-Ins container, with the common name MS:i386. Through its Admin-Extension-DLL attribute, this object points to a DLL file called CONADMIN.DLL in the \\SERVER\ADD-INS\MS\I386 directory on the Server computer. The MS Mail Connector itself is represented by a directory object in the Connections container, whose Extension-Name attribute is set to the value MS.

Example: GWSample

For an Admin-Extension object whose Extension-Name attribute is GWSample, you would copy extension DLLs into one or more the following directories, depending on the platform:

Platform of Windows NT Server | Destination Directory
Intel CPU architecture | \\SERVER\ADD-INS\GWSample\i386
MIPS CPU architecture | \\SERVER\ADD-INS\GWSample\MIPS
DEC ALPHA CPU architecture | \\SERVER\ADD-INS\GWSample\ALPHA
PowerPC | \\SERVER\ADD-INS\GWSample\PPC

You need both an Administrator extension DLL and a new Admin-Extension object for each supported platform. For this example, you would install the Admin-Extension objects for the i386 and MIPS platforms into the following locations in the DIT:

Example: Installation locations for Admin-Extension objects

The procedure for installing a new Administrator extension DLL is different than that for replacing an installed Administrator extension DLL with a newer version:

To install a new Administrator extension DLL
  1. While the Administrator extension DLL is on the distribution media, get its file version. First, call the HrGetFileVersionInfo function. Then, extract the actual file version from the data returned by HrGetFileVersionInfo using functions such as the Win32 function VerQueryValue.
  2. Copy the Administrator extension DLL into the appropriate directory for the platform.
  3. Install the Admin-Extension object by calling the HrInstallAdminExtension function and passing the DLL file version. This call creates the Admin-Extension object in the directory and sets the following properties on it: Admin-Display-Name, Common-Name, Admin-Extension-DLL, File-Version.

To install a newer version of an existing Administrator extension DLL
  1. While the Administrator extension DLL is on the distribution media, get its file version. First, call the HrGetFileVersionInfo function. Then, extract the actual file version from the data returned by HrGetFileVersionInfo using functions such as the Win32 function VerQueryValue.
  2. If the installed version is newer than the one that the setup program would install, display a dialog box asking the administrator whether to copy the Administrator extension DLL from the distribution media onto the server. If the answer is no, end the setup procedure for this Admin-Extension object. If the answer is yes, continue with the following steps.
  3. Use the HrAdminExtensionExists function to determine whether an Administrator extension with the same name is already installed. If so, remove it using the function HrRemoveAdminExtension.
  4. Delete the existing Administrator extension DLL by using the following steps. This procedure is necessary to ensure deletion of an Administrator extension DLL that may be in use. The steps in this example assume that your existing Administrator extension DLL is named AE.DLL.
    • Ensure that no file with a backup name from a previous attempted installation exists. In this example, delete AE.DLL.BAK.
    • Rename the existing extension DLL by giving it the extension .BAK. For example, if your extension DLL is called AE.DLL, rename it to AE.DLL.BAK.
    • Delete the file with the backup name. In this case, delete AE.DLL.BAK.
  5. Copy the new Administrator extension DLL into the appropriate directory for the platform.
  6. Install the Admin-Extension object by calling the HrInstallAdminExtension function and passing the DLL file version. This call creates the Admin-Extension object in the directory and sets the following properties on it: Admin-Display-Name, Common-Name, Admin-Extension-Dll, File-Version.

The following sample code is from the GWSETUP.C file in the directory \BKOFFICE\SAMPLES\EXCHANGE\GWSETUP. It performs several of the steps needed to install an Administrator extension DLL.

//$--DoInstall----------------------------------------------------------
//  Install the application.
// --------------------------------------------------------------------
void DoInstall(                         // RETURNS: nothing
    void)                               // no arguments
{
    //
    // Check if admin extension object exists
    //

    sprintf(szLocalExtensionDll,  "%s\\%s", szSourcePath,  EXTENSION_DLL);
    sprintf(szRemoteExtensionDll, "%s\\%s", szExtnDestDir, EXTENSION_DLL);
    sprintf(szBackupExtensionDll, "%s.bak", EXTENSION_DLL);
    sprintf(szRemoveExtensionDll, "%s\\%s.bak", szExtnDestDir, EXTENSION_DLL);

    hr = HrVerifyAdminExtensionVersion(        szLocalExtensionDll,
        szServer,
        szSite,
        ADD_INS_TYPE,
        MACHINE_TYPE,
        &dwExtnVersionMS,
        &dwExtnVersionLS,
        &fInstallAdminExt,
        &fDeleteAdminExt);

    //
    // Remove admin extension object
    //

    if((fInstallAdminExt == TRUE) && (fDeleteAdminExt == TRUE))
    {
        hr = HrRemoveAdminExtension(
            szServer,
            szSite,
            ADD_INS_TYPE,
            MACHINE_TYPE);

        RemoveFile(szRemoveExtensionDll, cmoForce);
        RenameFile(szRemoteExtensionDll, szBackupExtensionDll);
        RemoveFile(szRemoveExtensionDll, cmoForce);
    }

    //
    // Add server files to copy list
    //

    ClearCopyList();

    if(fInstallAdminExt == TRUE)
    {
        AddSectionFilesToCopyList(SECTION_EXTENSION, szSourcePath, szExtnDestDir);
    }

    if(fInstallAddrType == TRUE)
    {
        AddSectionFilesToCopyList(SECTION_ADDRESS,   szSourcePath, szAddrDestDir);
    }

    //
    // Copy server files
    //

    if((fInstallAdminExt == TRUE) || (fInstallAddrType == TRUE))
    {
        CopyFilesInCopyList();
    }

    //
    // Install admin extension object
    //

    if(fInstallAdminExt == TRUE)
    {
        hr = HrInstallAdminExtension(
            szServer,
            szSite,
            ADD_INS_DISPLAY_NAME,
            ADD_INS_TYPE,
            dwExtnVersionMS,
            dwExtnVersionLS,
            EXTENSION_DLL,
            MACHINE_TYPE);

    }
}


Implementing Extensions with the CAdminDialog Class

The Microsoft Exchange Server SDK provides a C++ interface that you can use to implement Administrator extension DLLs. It is defined in the exadmin.H file and is based on the MFC CDialog class. It handles the standard interface handshaking.

For examples that show how this class is used, see the sample applications QUEVIEW: Listing Gateway Folders and SMBAGENT: Creating a Sample Mailbox Agent.


Using the Extension-Data Attribute

Every directory object can store two kinds of data: standard configuration data provided by the Microsoft Exchange Server Administrator program, and extension (custom) data provided by an Administrator extension DLL. Extension data is stored in the Extension-Data attribute. You can use extension data on any individual object in the directory, including your application's object and other objects it may interact with.

You should implement extension data when your application needs to expose information about itself that is outside the application's schema. A common example is the use of extension data to configure an application's general behavior. For example, any application that processes messages could store the following as extension data:

  • The default number of attempts at sending a message.
  • The maximum number of threads to use for processing messages.
  • The polling interval: a setting that determines whether to use notifications to look for incoming messages or to poll for them after set intervals.
  • A line-wrap setting: the maximum number of characters to keep on each line in the body of a message is processing.

The Extension-Data attribute is a multivalued, binary attribute available on all directory objects. Each value in the attribute has a maximum size of 64K. It is used to associate application-specific custom data with a Microsoft Exchange Server directory object.

Because more than one application can associate its custom data with the same object, the Administrator extension functions allow each binary part of the Extension-Data attribute to be assigned a unique owner tag. An owner tag is a null-terminated Unicode string added to the start of each Extension-Data binary part. This Unicode string must be in Intel (little-endian) byte order.

The following diagram shows a directory object with an Extension-Data attribute. The Extension-Data attribute has two binary parts, which are identified by their owner tags, Ext1 and Ext2.

Extension Data attribute on a directory object

The following diagram shows the value whose owner tag is Ext2. Within this value, the data in the data fields that follow can be of varying types.

The Extension Data attribute consists of an owner tag and a data section


Storing and Accessing Configuration Information

Configuration information for a service object (a Mailbox-Agent or Mail-Gateway) is stored in the server-application object in the directory. Configuration information for recipients is stored in Mailbox objects in the directory. Both types can be accessed through the Microsoft Exchange Server Address Book provider.

The mechanisms for programmatically reading and writing standard configuration data and extension data are similar, but not identical.

To read standard configuration data using MAPI
  1. Open the directory object. See Finding an Object in the Directory and Using MAPI with Directory Objects.
  2. Read the data with an array of SPropValue structures using the IMAPIProps::GetProps method.
  3. Use MAPI methods to locate the property in the array of SPropValue structures.
  4. Manipulate strings and other types of data using standard C functions.

To read extension data using MAPI
  1. Open the directory object that contains the extension data. See Finding an Object in the Directory and Using MAPI with Directory Objects.
  2. Call IMAPIProps::GetProps to read the extension data attribute into a buffer.
  3. Unpack the extension data attribute using the HrCfgUnpackData function. This gives you the array of SPropValue structures, which you can read using standard C functions to manipulate strings and other types of data.

Configuration data is written when an administrator is editing property pages through the Administrator program and clicks the Apply Now or OK button. The following steps describe how to set up this action.

To write standard configuration data
  1. Express the data in a MAPI SPropValue array.
  2. Write the data using the IMAPIProps::SetProps method.

To write extension data
  1. Express the data in an array of SPropValue structures.
  2. Pack the extension data into a binary value using the HrCfgPackData function. When the extension data attribute is written into a memory buffer, it is still in packed (binary) form.
  3. Write the data using the SetObjectData function.

Note For reading and writing very large individual attributes, it may be better to use the IStream interface than to use IMAPIProps::SetProps and IMAPIProps::GetProps. For more information, see Getting and Setting Properties Efficiently and Minimizing IStream Interface Use.


Using the Configuration Functions

Special configuration functions are used to pack and unpack extension data. The HrCfgPackData function packs extension data (converts an array of SPropValue structures into a binary stream) before you write it to the directory. The HrCfgUnpackData function unpacks this data after you read it from the directory. For more information, see the EDKCFG.H file.

Configuration Functions

Function | Purpose
HrCfgCreateAdviseObj | Begins monitoring a MAPI session for changes to extension data. Should be called once to create an advise object to register for notifications for the MAPI session to be monitored. Then, HrCfgAdvise should be called once for each extension data section (each of the values in a multivalued extension data property) being monitored. If nPollInterval == 0, no monitoring thread is created, and the user must do polling manually by calling HrCfgPollAdviseObj.
HrCfgPollAdviseObj | Checks an advise object against what is stored in the directory. Calls the notification routines if there are any changes.
HrCfgDestroyAdviseObj | Ends monitoring of a MAPI session. Calls HrCfgUnadvise for any extension data sections that are actively being monitored.
HrCfgAdvise | Begins monitoring of an extension data section. When the extension data changes, the specified callback routine is called. The callback routine will be called once from HrCfgAdvise to set the initial extension data values.
HrCfgUnadvise | Ends monitoring of an extension data section.
HrCfgPackData | Takes a configuration name and a set of MAPI properties and packs them into a binary buffer suitable to be saved in the directory information tree for the gateway or other object.
HrCfgUnpackData | Takes a packed binary buffer and unpacks it to yield a configuration name, number of properties, and an array of MAPI properties.
HrOpenSiteContainer | Takes a pointer to a MAPI session and returns an IMAPIProp interface for the current site object.
HrOpenSiteContainerAddressing | Takes a pointer to a MAPI session and returns an IMAPIProp interface for the current site addressing object.
HrOpenSessionObject | Takes a pointer to a MAPI session and returns an IMAPIProp interface on the directory object associated with the session.
HrCfgPropertyTagFromNameId | Takes a pointer to an IMAPIProp interface and a name identifier, and returns the MAPI property tag that represents the given name identifier for that interface.


Using the CFGCODE Utility

CFGCODE is a command-line utility used to create a packed property structure that can be unpacked using the HrCfgUnpackData function. It takes as input a text file containing a list of MAPI properties, and produces a file containing the binary packed property structure. The user can specify the name of the section in the input file to read from, and a configuration name to be placed at the front of the resulting packed (binary format) property structure.

See CFGCODE: Generating a Packed Property Structure.


Modifying Extension Data

The Administrator extension DLL can use configuration functions to register for changes to extension data by creating an advise object. Then, when an administrator opens the directory object and edits its extension data, the extension DLL receives a notification about these changes. It can then modify properties on the directory object, using intermediate steps that pack and unpack the data.

To implement this notification, specify a callback function to be called when your extension data changes. Pass the name of this callback function as a parameter to the HrCfgAdvise function. This monitoring mechanism uses polling to determine changes to extension data. You can set the polling interval in a parameter to the HrCfgCreateAdviseObj function. Because this polling uses a call to the IMAPIProp::GetProps method (which causes an RPC), it involves some network overhead. You can choose to have your application poll on demand by calling the HrCfgPollAdviseObj function.

The following procedure lists the events that occur when an administrator accesses an application-specific property page to view or change extension data.

To change extension data
  1. The administrator double-clicks the application object in the Microsoft Exchange Server directory, which displays the property sheet for that object. The Microsoft Exchange Server Administrator program displays the first standard property page and the Administrator extension DLL displays the tabs representing extension-data property pages, if any.
  2. The administrator clicks a tab to open the property page containing the object's extension data. The Administrator program calls the extension DLL to display this property page.
  3. The extension DLL calls the Administrator extension functions, which in turn call configuration functions to unpack and display the extension data in the object's property pages.
  4. These property pages can now be edited. If the extension data is edited, it must be repacked (using configuration functions) before it is stored in the directory.

These and other related events are described in more detail in A Typical Call Sequence.


A Typical Call Sequence

When a Microsoft Exchange Server administrator performs actions on a custom property page, a sequence of Administrator program functions and Administrator extension DLL functions must be called.

The following illustrations show the Administrator program and extension DLL responses. The shaded sections show custom functionality to be created by application developers. Arrows indicate the movement of control from one program to the other as function calls are made.

For more information on these functions, see Using Administrator Extension Functions (Called by Administrator Program) and Using Administrator Extension Functions (Called by Extension DLL).

Note Although the following sequence includes EDKCFG function calls for packing and unpacking data, you can format the extension data attribute any way you choose. You are not required to pack extension data before writing it to the directory.

In the following table, click an action to see the sequence of function calls made when an administrator performs that action, such as selecting an application through the Microsoft Exchange Server Administrator program.

Illustrated Sequence of Function Calls

Administrator's Action
Selecting an application
Changing the information on a property page
Choosing the Help button
Selecting a different property page
Choosing the Apply button
Choosing the OK button
Choosing the Cancel button


Administrator Selects an Application

The following illustration shows the functions that are called when the administrator selects an application.

In this sequence, the HasHelpProc function in your Administrator extension DLL is called only for the extension property page that is displayed. At the end of this sequence, the dialog box containing all property pages is visible.


Administrator Changes Information on a Property Page

The following illustration shows what happens when the administrator changes the information in a property page.


Administrator Chooses the Help Button

The following illustration shows what happens when the administrator chooses the Help button.


Administrator Chooses a New Property Page

The following illustration shows what happens when the administrator selects a different property page. The actions taken by the Administrator extension DLL are optional.


Administrator Chooses the Apply Button

The following illustration shows what happens when the administrator chooses the Apply button.


Administrator Chooses the OK Button

The following illustration shows what happens when the administrator chooses the OK button.


Administrator Chooses the Cancel Button

The following illustration shows what happens when the administrator chooses the Cancel button.


Administrator Extension DLL Sample Applications

The Microsoft Exchange Server SDK provides sample applications that include a gateway, a mailbox agent, a application that shows an object's extension data, and an application that displays the contents of a gateway's inbound and outbound message queues.

SMBAGENT

SMBAGENT (Sample Mailbox Agent) is a sample list server application that uses extension data. The Administrator extension DLL that provides access to this data is called SMBADMIN.DLL. This DLL adds an additional property page to the standard property pages displayed by the Microsoft Exchange Server Administrator program. SMBADMIN.DLL stores the extension data in the Microsoft Exchange Server directory using the mechanisms described earlier.

SMBAGENT extension DLL files are located in the BKOFFICE\SAMPLES\EXCHANGE\SMBADMIN directory. For more information, see SMBAGENT: Creating a Sample Mailbox Agent.

Sample Gateway

Files for compiling the Administrator extension DLL for the sample gateway are located in the bkoffice\SAMPLES\EXCHANGE\sgwadmin directory. This DLL adds one property page to the sample gateway. For more information, see Sample Gateway and Applications.

EXTDATVW

The EXTDATVW sample application (Extension Data Viewer) is designed to be installed on a gateway or mailbox agent object. It adds a property page that displays the gateway or mailbox-agent object's extension data. EXTDATVW uses Administrator extension functions to implement the Administrator extension DLL. For more information, see EXTDATVW: Viewing and Editing Extension Data.

MBXSERV

The MBXSERV sample application demonstrates how to create a property page attached to a mailbox. On this property page, you can view the titles of all the messages in the mailbox, using a password for security. This sample application works in conjunction with MBXADMIN.DLL, an Administrator program extension that adds a property page to the property sheets of a mailbox.

For more information, see MBXSERV: Viewing Messages in a Mailbox.

QUEVIEW

The QUEVIEW sample application is an Administrator extension DLL that displays information on a property page that you access through the Microsoft Exchange Server Administrator program. QUEVIEW lists the top-level folders of a gateway's mailbox.

Although QUEVIEW is an extension DLL, it uses no extension data. The snapshot of folders and their contents displayed on the QUEVIEW property pages are gathered when the QUEVIEW is started, not simply read from a location in the Microsoft Exchange Server directory.

QUEVIEW files are located in BKOFFICE\SAMPLES\EXCHANGE\QUEVIEW. For more information, see QUEVIEW: Listing a Gateway's Folders.


Setup Programs

You may need to provide a setup program for your server application (mailbox agent or gateway) or client application that includes a server component. This setup program will allow users to install, configure, and remove your application within the Microsoft Exchange Server environment.

This section describes how to write a setup program and identifies the most important installation tasks the program will need to perform. Because an application may need to store and use data from the first time it runs, this section also discusses ways to do this. For example, if an application uses extension data, this data may need to be set up during installation.

For more on writing an application as a service of Windows NT Server, see the information about services and the service control manager in the Platform SDK.

For general information on writing setup programs, see Setup API in the Platform SDK.

Note The installation and configuration of a server application are closely related tasks because applications are usually configured during installation. Moreover, setup and administration operations interact with many of the same components within Microsoft Exchange Server and Microsoft Windows NT Server. Examples given apply to server applications that run as services of Windows NT Server in the Microsoft Exchange Server environment.


About the Setup Process

A primary function of the setup program is to copy all necessary files from the installation medium to the server's hard disk. Depending on the application's level of interaction with Microsoft Exchange Server system components, the setup program must also ensure that the application is recognized by the components and can communicate with them.

The amount of interaction between the server application and Microsoft Exchange Server depends on the application's design. Server applications can be developed that depend very little on Microsoft Exchange Server. For example, a Windows application that displays an icon to start it and supplies an interface to configure and control it may not need to include a MAPI profile or to register with Windows NT Server. You only need to build a simple installation program for this type of application.

However, this independence from Microsoft Exchange Server and Windows NT Server has its drawbacks. For example, if you design your application to use the Windows NT Registry, you can use the utility functions provided with the Microsoft Exchange Server SDK to more easily manage the application's configuration information — including both standard data and extension data.

The following setup program description explains what is gained when Windows NT Server and Microsoft Exchange Server components work closely together.

Most server application setup programs follow the process described in the following illustration.

Tasks performed by a server application during a complete installation on Windows NT Server in a Microsoft Exchange Server environment

If your setup program performs all these tasks, your application can be controlled and monitored through Windows NT (Server or Workstation) and Microsoft Exchange Server and Client by the following methods:

  • Services dialog box of the Windows NT Control Panel Allows an administrator to start, stop, pause, or continue any installed application, as well as pass startup parameters to the application.
  • Microsoft Exchange Server Administrator program Allows an administrator to edit an application's object attributes displayed on property sheets.
  • Microsoft Exchange Client Allows an administrator to log on as the application to verify, for example, that a mailbox agent is receiving messages and if the messages are being processed correctly.


Creating a Complete Setup Program

This section describes the components of a complete setup procedure. Your application may include some or all of the steps described below.

To perform a complete setup procedure
  1. Query and collect system installation requirements from the administrator. See Collecting System Requirements.
  2. Install the application as a service of Windows NT Server by writing its configuration information to the Windows NT Registry. See Installing an Application as a Service.
  3. If you use an Administrator extension DLL to add property pages to the directory object associated with the server application, install its associated Admin-Extension object. See Installing an Admin-Extension Object.
  4. Certain files are required for applications that use Administrator extensions or address types. Copy these directory-related files onto the computer on which the setup program is running. See Copying Files Onto Disk, which also explains how to copy the application's executable file to the computer on which it will run.
  5. Create the application object in the Microsoft Exchange Server directory. See Creating the Directory Object.
  6. Set up performance monitoring for your application. See Installing Performance Monitoring.
  7. For reconfiguring other system elements as required by the application, see Reconfiguring the System.

Additional information is available on the following topics:

  • Creating a MAPI Profile for a Server Application
  • Installing Applications with Server and Client Components
  • Removing a Server Application


Writing the Setup Program

See Setup API in the Platform SDK as a guide when writing a setup program.

Setup API includes a sample installation program template, documentation that explains how to use the installation template, plus functions including those that control basic user dialog boxes. You may need to write additional custom dialog boxes.

The Microsoft Exchange Server SDK provides a sample setup program called GWSETUP for installing a gateway, and a sample setup program called MBSETUP for installing a mailbox agent.


Preliminary System Configuration

The Microsoft Exchange Server Administrator program must be installed and running on any computer onto which a new Microsoft Exchange Server application is installed. This computer does not need to be a Microsoft Exchange Server computer.

If your application is to run as a service of Windows NT Server, it is subject to the following prerequisite. The Microsoft Exchange Server administrator needs to set up a Windows NT account with the right to log on as a service before running the application's installation program. The documentation for your application's installation procedure should make this prerequisite clear.


Collecting System Requirements

Applications are usually installed and configured according to the user's specified needs. It's good practice to collect this data from the user at the beginning of the installation procedure through a series of interactive dialog boxes. The application uses this information to install its components and configure the user's system.

Typical information to be gathered at this point includes the following:

  • Name of the Microsoft Exchange Server computer and the site on which the application will be installed.
  • Display name of the application's directory object, the display name of the application's service, the Windows NT account name of the service, and the service's password.

The setup program should also verify at this point that the destination computer has enough free disk space for the installation.

For more information about the way a setup program gathers information to be used as attribute values of directory objects, see Creating the Directory Object.

Examples: Collecting System Requirements

The sample gateway's setup program uses the following files to collect information at installation time:

  • DIALOGS.RC Contains the dialog boxes that are displayed.
  • GWUISTF.C Contains dialog control routines and validates some of the data entered by the administrator.
  • GWSETUP.C Performs high-level dialog control operations and data validation.


Installing an Application as a Service

If your application runs as a service of Windows NT Server, it must be installed in the service control manager. Making your application a Windows NT Server application gives it the ability to start up automatically when the computer does and to run in its own security context. Users also gain the ability to control the application through the operating system instead of through a custom user interface.

To register an application as a service of Windows NT Server
  1. Connect to the service control manager by calling the Win32 OpenSCManager function.
  2. Create the service by calling the Win32 CreateService function and passing information such as the service name and type, as well as the ways the service should be accessed and started.
  3. In the local Windows NT Registry, open the HKEY_LOCAL_MACHINE\SYSTEM\CURRENTCONTROLSET\SERVICS key. Do this by calling the Win32 RegOpenKeyEx function.
  4. Under this key, create other necessary keys for the service, such as the object key and the parameters key. Registry keys are created by calling the Win32 RegCreateKeyEx function.
  5. Write the configuration information that your application needs into these Windows NT Registry keys.

For an example of this procedure, see the HrInstallService function in the EXCHINST.C file.


Installing an Admin-Extension Object

If your application is to present data to administrators on custom property pages, its setup program should install this functionality. This means installing the Admin-Extension object in the directory and copying the Administrator extension DLL and any other necessary files to specific disk locations. For information about copying files, see Copying Files Onto Disk.

For each Admin-Extension object to be installed, perform the following steps.

To install an Admin-Extension object
  1. Verify whether the Admin-Extension object already exists in the directory, using MAPI functions or the BatchExport function. See Finding an Object in the Directory.
  2. If the Admin-Extension object does exist, check its version. This is a multistep procedure that uses calls to the HrGetFileVersionInfo, VerQueryValue, HrAdminExtensionExists, and HrGetAdminExtensionVersion functions. To see how this is done, refer to the HrVerifyAdminExtensionVersion function in the GWSETUP.C file. If no Admin-Extension object by this name exists in the directory, skip to step 4.
  3. If the installed Admin-Extension object is newer than the one to be installed, use a dialog box to require the administrator to choose whether to overwrite the installed Admin-Extension object with the older one on the distribution medium. If the user answers No, end the installation of this Admin-Extension object; if other Admin-Extension objects are to be installed, begin their installation at step 1.
  4. Call the Win32 CoCreateGuid function to create a GUID. Convert this GUID into a string, and then use that string as a unique extension name for the Admin-Extension object. This is accomplished in the following sample code from the GWSETUP.C file:
    CoCreateGuid(&guid);

sprintf(
    szGatewayName,
    "%08lX-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X",
    guid.Data1,
    guid.Data2,
    guid.Data3,
    guid.Data4[0],guid.Data4[1],guid.Data4[2],guid.Data4[3],
    guid.Data4[4],guid.Data4[5],guid.Data4[6],guid.Data4[7]);
  5. If an Admin-Extension object with the same name as the one you are installing already exists, remove the installed object by calling the HrRemoveAdminExtension function, and passing the extension name of the Admin-Extension object.
  6. Copy the files associated with the Admin-Extension object to the server computer. See Files Used with Directory Objects.
  7. Create the new Admin-Extension object in the directory with the BatchImport or DAPIWrite function. Use the GUID created in step 4 for the extension name of the object.

For sample code that performs these steps, see the GWSETUP.C file in the \BKOFFICE\SAMPLES\EXCHANGE\GWSETUP directory.

For general information about working with Administrator extensions, see Administrator Program Extensions. For information about setting the attribute values of the Extension-Data attribute, see Initializing the Extension-Data Attribute.


Copying Files Onto Disk

Directory information is replicated to all connected servers in a site, but installed files (such as Administrator extension DLLs) are not. Making these types of files centrally accessible lets administrators control the server application through its associated directory object from any computer on the site. An installation program can help make this possible by copying certain important files into specified directories. When the setup program copies files onto the computer, it places them in different locations.


Files Used with Directory Objects

When Microsoft Exchange Server is installed, it creates the publicly exported directory shares \\SERVER\ADD-INS, \\SERVER\ADDRESS, and \\SERVER\CONNECT$. Under these directories, subdirectories called Extension-Name and Platform designate the name of the application being installed and the platform it runs on. (For information about platform designations, see Installing the Administrator Extension DLL.) The Extension-Name and Platform subdirectories, along with the directory for the application's executable file, must be created by the server application setup program.

These directories are used as follows:

  • Files for Administrator extension DLLs Applications that use a DLL to insert extension data into the directory (including mailbox agents) should install their public files in the \\SERVER\ADD-INS share:

    \\SERVER\ADD-INS\EXTENSION-NAME\PLATFORM

  • Files for address types If the server application creates a new address type, files used by the Addr-Type object should be installed in the \\SERVER\ADDRESS share:

    \\SERVER\ADDRESS\EXTENSION-NAME\PLATFORM

  • Other files Other public files, such as those that provide server-specific configuration information, should be installed into the \\SERVER\CONNECT$ share:

    \\SERVER\CONNECT$\EXTENSION-NAME\PLATFORM


The Executable File

Your server application's executable file is copied into a directory specified by the administrator installing the application. For a Windows NT Server application, this directory must be on the computer on which you are running the installation program, though this computer need not be a Microsoft Exchange Server computer.

For example, if you want to run a gateway on Computer A, you must run the setup program and install the executable file on Computer A, even though Computer B may be the Microsoft Exchange Server computer to which you will connect the gateway.

Example: Installing a Gateway

An SMTP gateway called Pro-SMTP is written by the fictitious company Pro-Electron, Inc. When this gateway is installed to a Microsoft Exchange Server called Proton, the gateway name Pro-SMTP is used as the Extension-Name, and the files are to be used on the i386 (Intel) platform.

In this installation, the setup program copies both PROADMIN.DLL (the Administrator extension DLL) and PROADMIN.HLP (the Help file for the gateway's extension property pages) to \\PROTON\ADD-INS\PRO-SMTP\I386. The proxy generation DLL for this gateway is copied to the \\PROTON\ADDRESS\PRO-SMTP\I386 directory.

The gateway setup program displays a dialog box so the administrator can choose the destination of the gateway's executable file. This destination directory is saved into the Windows NT Registry on the server application's computer.

Note The Common-Name attribute of a directory object is a concatenation of the values used for Extension-Name and Platform. For example, the gateway in the preceding example would have a Common-Name of Pro-SMTP:i386, and the Microsoft Exchange Server Administrator program would recognize it by this name only. Therefore, your installation program must use the Extension-Name and Platform values consistently when it copies files and when it is imports the application's directory object.

The GWSETUP.C and MBSETUP.C sample installation files first build a list of files to be copied, and then call the CopyFilesInCopyList function of the Setup toolkit.


Creating the Directory Object

Your server application needs to be recognized by other programs such as the Microsoft Exchange Server Administrator program. Therefore, the setup program must create a new object for your application in the Microsoft Exchange Server directory and provide initial object attribute values. The setup program can set most of these values as defaults, while others (such as the server name) can be specified by the user through a setup dialog box. When you add a new Mail-Gateway object or a new Mailbox-Agent object to the directory, an associated mailbox and folder hierarchy is created in the information store.

To create the object that represents the application in the directory, your setup program calls the BatchImport and DAPIWrite functions. The setup program also uses these functions to set the object's attribute values. Directory access functions are described in Directory Operations.

To know how to import a directory object, the setup program first gathers configuration information by reading default data from the application's header files and using default values that correspond to the type of application being installed. It also copies extension data from the extension data file on the distribution medium. For more information about extension data, see Initializing the Extension-Data Attribute.

The setup program presents dialog boxes to the administrator for entering attribute values. For example, a gateway's setup program would prompt the administrator for the address space serviced by the gateway. For an example of code that prompts administrators for information, see the ShowInstallDlg function call in GWSETUP.C. It requests, for example, a display name to use for the application being installed.


Initializing the Extension-Data Attribute

The Extension-Data attribute can be used by server applications to store custom data in the directory. This data can be manipulated through custom property pages implemented by Administrator extension DLLs. For more information, see Administrator Program Extensions.

During the setup procedure, the Extension-Data attribute must be initialized. You can use the CFGCODE utility to create a file holding default Extension-Data values. Once this extension data file is created, it can be used during application setup. When the customer runs the setup program, the file can be copied directly into the directory object's Extension-Data attribute. Its binary contents are formatted correctly for storage in the Microsoft Exchange Server directory as an attribute on the application object. For more information on CFGCODE.EXE, see CFGCODE: Generating a Packed Property Structure.

The setup program also performs this write operation using directory access function calls.


Installing Performance Monitoring

A setup program can also set up the counters for performance monitoring, which define the data for monitoring server application performance. These counters are used by the Windows NT Performance Monitor when it is launched.

As shown in the GWSETUP.C sample gateway setup program, you can install performance monitoring in two steps:

To install performance monitoring
  1. Call the HrInstallServicePerfMon function of EXCHINST.C. This function creates a performance monitor object (or class) in the Windows NT Registry, and creates keys for that object. It also creates a single registry instance of this class.
  2. Call the FLoadCounters function, which loads performance counters into the newly created Windows NT Registry entry. Later, when you run the Windows NT Performance Monitor, the object and instance (with default counters) are available. You should call FLoadCounters only for the first instance of the service being monitored. The FLoadCounters function is defined in EDKSETUP.H.


Reconfiguring the System

In most cases, your server application expects to operate within a system configured to work in a specific way. For example, it may regularly check the home telephone number stored in a human resources database on a different server, and update a corresponding attribute on the recipient objects in the local directory.

Or it may regularly receive satellite weather photos and send them to a public folder named GeoSync. For these actions to occur, directory elements must be in place. The GeoSync public folder or a recipient attribute that holds a home telephone number must have already been created. Your setup program is responsible for making sure the system is configured correctly before the application is run the first time.

For more information on using extension data attributes on an individual object (such as a recipient) or on groups of individual objects (such as a partial selection of recipient), see Administrator Program Extensions.

Creating or Modifying Information Store Objects

The setup program can create new objects (such as public folders) in the information store. These objects can be used by the active server application or by the application's clients. For example, if your application feeds information into recipient folders, it may need to create these folders for subscribing recipients. You use MAPI calls to create or modify objects in the information store. For more information, see the MAPI Programmer's Reference.

Creating or Modifying Directory Objects

In addition to the new application object, other directory objects can be created or modified by the setup program. It can also add custom data to object attributes reserved for this purpose. For example, your application can link an external database of additional data (such as images) to some or all recipient objects during setup. Depending on this action's scope, your application might edit recipient attributes or use an extension data attribute.

The setup program uses directory access functions to make all necessary directory changes. For more informations, see Using Directory Access Functions.


Creating a MAPI Profile for a Server Application

A server application with a MAPI profile can initiate a MAPI session. This enables it to perform actions such as managing mailboxes or creating public folders. A MAPI profile also lets administrators log on as the application to view any messages it may have received.

The server application — not its setup program — calls the function that actually creates the MAPI profile. This is done because the profile must be created in the security context of the server application, which may not be the same as the security context of a running setup program. It is advisable to first call the HrMAPIProfileExists function to check for an existing profile of the name you plan to use for the server application's new profile.


Installing Applications with Server and Client Components

In many cases, a server application is installed on a server and runs from that location only. However, some applications contain both server and client components. These applications need to be installed in two steps.

To install an application with both a server and a client component
  1. Run a setup program on the server to install server application components. This step also copies files needed for client component installation to the server's public share, where they can be accessed by clients.
  2. When the server installation is complete, run a different setup program on the client to install and download client components from the server.


Removing a Server Application

The DoRemove function in GWSETUP.C removes a gateway service's entire configuration. To write a custom application-removal routine, decide which steps are relevant for removing your own server application. The following procedure lists these steps in the order that DoRemove performs them:

To remove a server application
  1. Present a dialog box that lets the administrator select an application to remove. The ShowChooseServiceDlg function displays this type of dialog box.
  2. Determine whether the application's service is running by calling the FServiceRunning function. If it is running, attempt to stop the service.
  3. Remove the directory object. Call the HrRemoveGateway function to remove a gateway object and the HrRemoveMailboxAgent function to remove a mailbox agent from a given site. Both functions are defined in EXCHINST.C.
  4. Remove performance monitoring for the service by calling the HrRemoveServicePerfMon function. If the lpfUnloadCounters parameter returned from this function call is TRUE, continue with step 5. If it is FALSE, multiple instances of the application are installed. In this case, perform steps 7 and 8, and then begin again at step 1.
  5. Call the FUnloadCounters function to unload the counters used in performance monitoring.
  6. Remove the server application's keys from the Windows NT Registry. Do this by calling the HrRemoveRegistry function.
  7. Remove the service from service control manager of Windows NT. Do this by calling the HrRemoveService function.
  8. Delete the files belonging to the service using the EDKDeleteNode function.

The DoRemove function removes components from the local computer. Server components in the Microsoft Exchange Server directory must be removed in a separate step using directory access functions. For example, address types and Administrator extensions are not removed because they may be needed by other applications.


Functions

Functions used to create server and client applications that run within a Microsoft Exchange Server environment belong to one of the following categories:

  • Core Functions

    Microsoft Exchange Server core interface functions.

  • Non-Core Functions

    Microsoft Exchange Server application functions, gateway support functions, and utility functions.


Core Functions

The following functions act as the core interface to Microsoft Exchange Server.

Function | Header File
ADMIN_Initialize | ADMINEXT.H
BatchExport | DAPI.H
BatchImport | DAPI.H
CloseProxies | PROXYGEN.H
CommitDataProc | ADMINEXT.H
DAPI_FNErrorCallback | DAPI.H
DAPI_FNExportEntry | DAPI.H
DAPIAllocBuffer | DAPI.H
DAPIEnd | DAPI.H
DAPIFreeMemory | DAPI.H
DAPIGetSiteInfo | DAPI.H
DAPIRead | DAPI.H
DAPIStart | DAPI.H
DAPIUninitialize | DAPI.H
DAPIWrite | DAPI.H
DeinitSheetProc | ADMINEXT.H
DeinstallExtensionProc | ADMINEXT.H
DoHelpProc | ADMINEXT.H
EndProgressProc | DAPI.H
FHasAdminPrivs | EXCHINST.H
FIsPublicStore | EDKMAPI.H
FreeProxy | PROXYGEN.H
GetAdrBookPtr | GWMAIN.H
GetGWDefaultStore | GWMAIN.H
GetGWExchangeServerName | GWMAIN.H
GetGWGAL | GWMAIN.H
GetGWNewMailEvent | GWMAIN.H
HasHelpProc | ADMINEXT.H
HrActionToString | RULECLS.H
HrAddressTemplateExists | EXCHINST.H
HrAddressTypeExists | EXCHINST.H
HrAdminExtensionExists | EXCHINST.H
HrAdminProgramExists | EXCHINST.H
HrCopyActions | RULECLS.H
HrCopyRestriction | RULECLS.H
HrCreateGatewayProfile | EXCHINST.H
HrCreateMailboxAgentProfile | EXCHINST.H
HrDRAddToDeliveredRecipList | GWREPORT.H
HrDRCreate | GWREPORT.H
HrDRCreateDeliveredRecipList | GWREPORT.H
HrDRGetDeliveredRecip | GWREPORT.H
HrDRGetProps | GWREPORT.H
HrEnumContainers | EXCHINST.H
HrEnumOrganizations | EXCHINST.H
HrEnumProductServices | EXCHINST.H
HrEnumSiteAdmins | EXCHINST.H
HrEnumSites | EXCHINST.H
HrFindExchangePublicStore | EDKMAPI.H
HrFolderACLsOpen | ACLCLS.H
HrFolderRulesGetProviders | RULECLS.H
HrFolderRulesOpen | RULECLS.H
HrGatewayExists | EXCHINST.H
HrGetAddressTypeVersion | EXCHINST.H
HrGetAdminExtensionVersion | EXCHINST.H
HrGetServiceAccountName | EXCHINST.H
HrGetServiceCommonName | EXCHINST.H
HrGetServiceDisplayName | EXCHINST.H
HrGetServiceExecutableName | EXCHINST.H
HrGetServiceObjectGUID | EXCHINST.H
HrGetServiceProductGUID | EXCHINST.H
HrGetServiceServerName | EXCHINST.H
HrGetServiceSiteDN | EXCHINST.H
HrGWFindMtsInFolder | EDKMAPI.H
HrGWFindMtsOutFolder | EDKMAPI.H
HrInstallAddressTemplate | EXCHINST.H
HrInstallAddressType | EXCHINST.H
HrInstallAdminExtension | EXCHINST.H
HrInstallGateway | EXCHINST.H
HrInstallGatewayProxy | EXCHINST.H
HrInstallMailboxAgent | EXCHINST.H
HrInstallMessageConverter | EXCHINST.H
HrInstallService | EXCHINST.H
HrInstallServicePerfMon | EXCHINST.H
HrMailboxAgentExists | EXCHINST.H
HrMAPIAppendAddressList | EDKMAPI.H
HrMAPIAppendEntryList | EDKMAPI.H
HrMAPIAppendSPropValues | EDKMAPI.H
HrMAPICloseCachedProp | EDKMAPI.H
HrMAPICopyMessage | EDKMAPI.H
HrMAPICreateAddressList | EDKMAPI.H
HrMAPICreateEntryList | EDKMAPI.H
HrMAPICreateSizedAddressList | EDKMAPI.H
HrMAPIDeleteMessage | EDKMAPI.H
HrMAPIDestroyEntryList | EDKMAPI.H
HrMAPIFindDefaultMsgStore | EDKMAPI.H
HrMAPIFindFolder | EDKMAPI.H
HrMAPIFindFolderEx | EDKMAPI.H
HrMAPIFindInbox | EDKMAPI.H
HrMAPIFindIPMSubtree | EDKMAPI.H
HrMAPIFindMsgByProp | EDKMAPI.H
HrMAPIFindOutbox | EDKMAPI.H
HrMAPIFindStore | EDKMAPI.H
HrMAPIFindSubfolderEx | EDKMAPI.H
HrMAPIGetFirstSRowSet | EDKMAPI.H
HrMAPIGetNextSRowSet | EDKMAPI.H
HrMAPIGetPropBinary | EDKMAPI.H
HrMAPIGetPropBoolean | EDKMAPI.H
HrMAPIGetPropLong | EDKMAPI.H
HrMAPIGetPropString | EDKMAPI.H
HrMAPIGetPropSystime | EDKMAPI.H
HrMAPIGetPropToFile | EDKMAPI.H
HrMAPIGotoFirstSRow | EDKMAPI.H
HrMAPIGotoNextSRow | EDKMAPI.h
HrMAPIGotoSRow | EDKMAPI.H
HrMAPIMoveMessage | EDKMAPI.H
HrMAPIMoveOneProp | EDKMAPI.H
HrMAPIOpenCachedProp | EDKMAPI.H
HrMAPIOpenFolderEx | EDKMAPI.H
HrMAPIOpenStreamOnProperty | EDKMAPI.H
HrMAPIProfileExists | EXCHINST.H
HrMAPISetAddressList | EDKMAPI.H
HrMAPISetPropBinary | EDKMAPI.H
HrMAPISetPropBoolean | EDKMAPI.H
HrMAPISetPropFromFile | EDKMAPI.H
HrMAPISetPropLong | EDKMAPI.H
HrMAPISetPropString | EDKMAPI.H
HrMAPISetPropSystime | EDKMAPI.H
HrMAPISetStreamSize | EDKMAPI.H
HrMAPIWriteAttachmentToFile | EDKMAPI.H
HrMAPIWriteFileToStream | EDKMAPI.H
HrMAPIWriteMemoryToStream | EDKMAPI.H
HrMAPIWriteStreamToFile | EDKMAPI.H
HrMAPIWriteStreamToMemory | EDKMAPI.H
HrMonCollectAssociationStats | MONITOR.H
HrMonCollectMessageXferStats | MONITOR.H
HrMonCollectNDRStats | MONITOR.H
HrMonInit | MONITOR.H
HrMonLockCounters | MONITOR.H
HrMonUninit | MONITOR.H
HrMonUnlockCounters | MONITOR.H
HrOpenExchangePrivateStore | EDKMAPI.H
HrOpenExchangePublicFolders | EDKMAPI.H
HrOpenExchangePublicStore | EDKMAPI.H
HrRemoveAddressTemplate | EXCHINST.H
HrRemoveAddressType | EXCHINST.H
HrRemoveAdminExtension | EXCHINST.H
HrRemoveGateway | EXCHINST.H
HrRemoveGatewayProxy | EXCHINST.H
HrRemoveMailboxAgent | EXCHINST.H
HrRemoveMessageConverter | EXCHINST.H
HrRemoveProfile | EXCHINST.H
HrRemoveRegistry | EXCHINST.H
HrRemoveService | EXCHINST.H
HrRemoveServicePerfMon | EXCHINST.H
HrRestrictionToString | RULECLS.H
HrSetGatewayBit | EXCHINST.H
HrStringToAction | RULECLS.H
HrStringToRestriction | RULECLS.H
HrTextFromCompressedRTFStreamEx | RTFLIB.H
HrTraceAppendEntryList | EDKMAPI.H
HrTraceCopyEntry | EDKMAPI.H
HrTraceCreateEntryList | EDKMAPI.H
HrTraceGetEntryList | EDKMAPI.H
HrTraceGetEntryListSize | EDKMAPI.H
HrTraceGotoEntry | EDKMAPI.H
HrTraceGotoFirstEntry | EDKMAPI.H
HrTraceGotoNextEntry | EDKMAPI.H
HrTraceOpenEntry | EDKMAPI.H
HrTraceSetEntryList | EDKMAPI.H
HrTraceSetInfo | EDKMAPI.H
HrTraceUpdateInfo | EDKMAPI.H
InitProgressProc | DAPI.H
InitSheetProc | ADMINEXT.H
InstallExtensionProc | ADMINEXT.H
NTExport | DAPI.H
NWExport | DAPI.H
PADMIN_AddService | ADMINEXT.H
PADMIN_FreeDialogResource | ADMINEXT.H
PADMIN_FreeNameList | ADMINEXT.H
PADMIN_GetNameList | ADMINEXT.H
PADMIN_GetObjectData | ADMINEXT.H
PADMIN_GetObjectDataSize | ADMINEXT.H
PADMIN_InfoHasChanged | ADMINEXT.H
PADMIN_LoadDialogResource | ADMINEXT.H
PADMIN_RemoveService | ADMINEXT.H
PADMIN_SetIcon | ADMINEXT.H
PADMIN_SetNameList | ADMINEXT.H
PADMIN_SetObjectData | ADMINEXT.H
PADMIN_SetTitle | ADMINEXT.H
RcGenerateProxy | PROXYGEN.H
RcInitProxies | PROXYGEN.H
RcUpdateProxy | PROXYGEN.H
RcValidateProxy | PROXYGEN.H
RcValidateSiteProxy | PROXYGEN.H
ResetProgressProc | DAPI.H
SAD_EcGetProxies | SADAPI.H
SAD_EcGetProxiesBI | SADAPI.H
SAD_FreeProxyListNode | SADAPI.H
SAD_ScBind | SADAPI.H
SAD_ScBulkCreateMultiProxy | SADAPI.H
SAD_ScBulkCreateProxy | SADAPI.H
SAD_ScBulkProxyHalt | SADAPI.H
SAD_ScBulkUpdateMultiProxy | SADAPI.H
SAD_ScGetBulkProxyStatus | SADAPI.H
SAD_ScIsProxyUnique | SADAPI.H
SAD_ScRunRID | SADAPI.H
SAD_ScRunRIDEx | SADAPI.H
SAD_ScSaveGatewayTrackingData | SADAPI.H
SAD_Unbind | SADAPI.H
SchemaPreload | DAPI.H
ShowPageProc | ADMINEXT.H
StartPageProc | ADMINEXT.H
UpdateProgressProc | DAPI.H
UpdateProgressTextProc | DAPI.H


Non-Core Functions

The following functions provide specialized support and general utilities for the development of Microsoft Exchange Server applications and gateways.

Function | Header File
ADVISECALLBACK | EDKCFG.H
BackupFree | EDBBCLI.H
CloseFolderMetrics | STATS.H
EventLogMsg | EDKEVENT.H
FIsService | WINWRAP.H
FreeThreadParameter | GWMAIN.H
FServiceReportStatus | WINWRAP.H
GetGWDefaultStore | GWMAIN.H
GetGWFindData | GWMAIN.H
GetGWFindDataSize | GWMAIN.H
GetGWGALEntryId | GWMAIN.H
GetGWGALEntryIdSize | GWMAIN.H
GetGWMtsInFolder | GWMAIN.H
GetGWMtsOutFolder | GWMAIN.H
GetGWNewMailEvent | GWMAIN.H
GetGWNewMailStatus | GWMAIN.H
GetGWPath | GWMAIN.H
GetGWRootFolder | GWMAIN.H
GetGWSession | GWMAIN.H
GetGWSRowSet | GWMAIN.H
GetGWSubmitInterval | GWMAIN.H
GetServiceInstance | WINWRAP.H
GetServiceStopEvent | WINWRAP.H
GWMain | GWMAIN.H
HrBackupClose | EDBBCLI.H
HrBackupEnd | EDBBCLI.H
HrBackupGetBackupLogs | EDBBCLI.H
HrBackupGetDatabaseNames | EDBBCLI.H
HrBackupOpenFile | EDBBCLI.H
HrBackupPrepare | EDBBCLI.H
HrBackupRead | EDBBCLI.H
HrBackupTruncateLogs | EDBBCLI.H
HrCfgAdvise | EDKCFG.H
HrCfgCreateAdviseObj | EDKCFG.H
HrCfgDestroyAdviseObj | EDKCFG.H
HrCfgPackData | EDKCFG.H
HrCfgPollAdviseObj | EDKCFG.H
HrCfgPropertyTagFromNameId | EDKCFG.H
HrCfgUnadvise | EDKCFG.H
HrCfgUnpackData | EDKCFG.H
HrCleanupPSTGlobals | NEWPST.H
HrConvConvert | CONVCWRP.H
HrConvInitGlobals | CONVCWRP.H
HrConvInitInstance | CONVCWRP.H
HrConvUninitGlobals | CONVCWRP.H
HrConvUninitInstance | CONVCWRP.H
HrCreateDateTimeString | MSGEMIT.H
HrCreateDirEntryId | EDKUTILS.H
HrCreateDirEntryIDEx | EDKUTILS.H
HrCreatePersonalStore | NEWPST.H
HrEDKDecodeBinaryStreamDataToStream | MSGEMIT.H
HrEDKEncodeBinaryStreamDataToStream | MSGEMIT.H
HrEDKParseSubjectPrefix | MSGEMIT.H
HrEventCloseLog | EDKEVENT.H
HrEventGetCounts | EDKEVENT.H
HrEventGetHandle | EDKEVENT.H
HrEventOpenLog | EDKEVENT.H
HrEventUseExisting | EDKEVENT.H
HrFileTimeToSeconds | STATS.H
HrFindExchangeGlobalAddressList | ADDRLKUP.H
HrGetExchangeStatus | EDKUTILS.H
HrGetFileVersionInfo | STATS.H
HrGetFolderMetrics | STATS.H
HrGetMailboxDN | EDKUTILS.H
HrGetProgManGroups | EDKSETUP.H
HrGetPropTagName | PROPTAG.H
HrGetPropTagValue | PROPTAG.H
HrGetRecipientList | MSGEMIT.H
HrGetServiceStatus | EDKUTILS.H
HrGWLogoff | GWMAIN.H
HrGWLogon | GWMAIN.H
HrGWResolveAddress | ADDRLKUP.H
HrGWResolveProxy | ADDRLKUP.H
HrGWStartNewFileHandler | GWMAIN.H
HrGWStartNewMailHandler | GWMAIN.H
HrGWWaitForStop | GWMAIN.H
HrIdentifyRegistryRootKey | EDKUTILS.H
HrJSCollectDataPoint | STATS.H
HrJSGetValue | STATS.H
HrJSOpen | STATS.H
HrMailboxLogoff | MBLOGON.H
HrMailboxLogon | MBLOGON.H
HrNDRAddToFailedRecipList | GWREPORT.H
HrNDRCreate | GWREPORT.H
HrNDRCreateFailedRecipList | GWREPORT.H
HrNDRGetFailedRecipList | GWREPORT.H
HrNDRGetFailedProps | GWREPORT.H
HrOpenFolderMetrics | STATS.H
HrOpenSessionObject | EDKCFG.H
HrOpenSiteContainer | EDKCFG.H
HrOpenSiteContainerAddressing | EDKCFG.H
HrRestoreEnd | EDBBCLI.H
HrRestoreGetDatabaseLocations | EDBBCLI.H
HrRestorePrepare | EDBBCLI.H
HrRestoreRegister | EDBBCLI.H
HrRestoreRegisterComplete | EDBBCLI.H
HrRTFCompressedToText | EDKUTILS.H
HrSendProgManCommand | EDKSETUP.H
HrServiceConfirmStop | WINWRAP.H
HrServiceGetArgv | WINWRAP.H
HrServiceGetName | WINWRAP.H
HrServiceProcessControl | WINWRAP.H
HrServiceShutdown | WINWRAP.H
HrServiceStartup | WINWRAP.H
HrServiceWaitForContinue | WINWRAP.H
HrServiceWaitForControl | WINWRAP.H
HrServiceWaitForStop | WINWRAP.H
HrSetCurrentBackupLog | EDBBCLI.H
HrStrAToStrA | EDKUTILS.H
HrStrAToStrW | EDKUTILS.H
HrStrstriW | CONVREGH.H
HrStrTokAll | EDKUTILS.H
HrStrWToStrA | EDKUTILS.H
HrStrWToStrW | EDKUTILS.H
HrTextToRTFCompressed | EDKUTILS.H
HrTrackInitLog | EDKTRACK.H
HrTrackUninitLog | EDKTRACK.H
HrTrackWriteLog | EDKTRACK.H
HServiceCreateThread | WINWRAP.H
JSClose | STATS.H
PCONVDLLCONV | CONVSTRC.H
PCONVDLLENTRYFN | CONVSTRC.H
PCONVDLLQUERY | CONVSTRC.H
ServiceMain | WINWRAP.H
ServiceStop | WINWRAP.H
SetServiceExitCode | WINWRAP.H


Return Values

Microsoft Exchange Server functions can return either their own values, MAPI values, or WIN32 values. For an explanation of the MAPI return values, see MAPICODE.H. For an explanation of the WIN32 return values, see WINERR.H.

BOOL Return Values

The return values for functions returning a BOOL data type are as follows:

TRUE
The function completed successfully.
FALSE
The function did not complete successfully.

HRESULT Return Values

The return values for functions returning a HRESULT data type are as follows:

NOERROR
The function completed successfully.
EC_EDK_E_FAIL
Unknown failure.
EC_EDK_E_INVALIDARG
Invalid argument (bad input).
EC_EDK_E_OUTOFMEMORY
Not enough memory to perform operation.

RC Return Values

The return values for functions returning a RC data type are as follows:

RC_SUCCESS
The function completed successfully.
RC_CONFIG
A configuration error occurred.
RC_CONTENTION
A contention error occurred.
RC_DISKSPACE
The system ran out of disk space.
RC_EOF
The function reached the end of the file.
RC_ERROR
A general (unspecified) error occurred.
RC_EXPIRED
Time expired before the function could complete.
RC_IMPLEMENTATION
The function is not yet implemented.
RC_INVALID_PARAMETER
There was an invalid function parameter.
RC_MEMORY
A memory allocation error occurred.
RC_NOTFOUND
The object is not found.
RC_PROTOCOL
A protocol error occurred.
RC_SHUTDOWN
A service shutdown occurred.
RC_SOFTWARE
An unspecified error occurred in the software.
RC_SYNTAX
A syntax error occurred.
RC_TIMEOUT
An operation timed out before the function could complete.

RPC_SC Return Values

The return values for functions returning a RPC_SC data type are as follows:

SC_OK
No errors.
SC_Error
General error.
SC_BPActive
Bulk proxy address generation is currently running.
SC_BPInactive
Bulk proxy address generation is not currently running.
SC_BPShutdownPending
A shutdown in bulk proxy address generation is in progress.
SC_BPSiteAddressMismatch
A site address mismatch between the rgszOldSiteAddress and rgszNewSiteAddress lists in SAD_ScBulkUpdateMultiProxy.

SCODE Return Values

The return values for functions returning a SCODE data type are as follows:

EC_EDK_E_ALREADY_EXISTS
The object that the function sought already exists.
EC_EDK_E_AMBIGUOUS
An argument has more than one match.
EC_EDK_E_END_OF_FILE
The function reached the end of the file.
EC_EDK_E_NOT_FOUND
The property tag value was not found.
EC_EDK_E_PARSE
An error was encountered while parsing an argument.
EC_EDK_E_SHUTDOWN_SERVICE
The service was shut down.


Function Descriptions

This section contains a description of each of the Microsoft Exchange Server functions. Each function is formatted in the following manner.

Function Name

A short description of the function.

Quick Info

Contains the .H file containing the function prototype, .LIB and Unicode information, plus the syntax of a call to the function.

Parameters

A brief discussion of each function parameter.

Return Values

Usually contains a jump to Return Values.

Remarks

Any more information that relates to the use and implementation of the function.

See Also

Other related functions


ADMIN_Initialize

The ADMIN_Initialize function is called by the file-based batch processing functions of the directory access functions to initiate the handshaking between the Microsoft Exchange Server Administrator program and the Administrator extension DLL. Unlike the other user-supplied DLL functions, the Administrator program calls this mandatory Administrator extension DLL function by name, not through a pointer reference. Therefore, this function must have the name ADMIN_Initialize.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID ADMIN_Initialize(
  ADMIN_AdministratorConnections * pac,
  ADMIN_AdministratorFunction * pAdminFunction,
  ADMIN_ExtensionFunction ** ppExtensionFunction
);

Parameters

pac
Input parameter. Points to an ADMIN_AdministratorConnections structure containing handles to the MAPI session, the address book, and the address book container opened by the Administrator program.
pAdminFunction
Input parameter. Points to an ADMIN_AdministratorFunction structure containing pointers to the functions available in the Administrator program.
ppExtensionFunction
Output parameter. Points to an ADMIN_ExtensionFunction structure containing pointers to functions in the Administrator extension DLL that are passed to the Administrator program.

Return Values

None.

Remarks

The Microsoft Exchange Server Administrator program calls the Administrator extension DLL in an initial handshake to exchange pointers to the other extension functions. ADMIN_Initialize is the only function that is exported by the Administrator extension DLL.

Because there is no return value, this function must succeed. If an error occurs (such as when an ADMIN_AdministratorConnections or ADMIN_AdministratorFunction member pointer is NULL), the extension DLL must not call the InitSheetProc function to initialize any property sheets.

Typically, this function does little more than save the pointers supplied in the parameters.

For more information on this function, see Using Administrator Extension Functions (Called by Administrator Program).

See Also

CommitDataProc, DeinitSheetProc, DoHelpProc, HasHelpProc, SaveDataProc, ShowPageProc, StartPageProc


ADVISECALLBACK

The ADVISECALLBACK function is called when a change occurs to the object being monitored by the HrCfgAdvise function.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT ADVISECALLBACK(
  LPVOID lpvUserContext,
  LPWSTR lpwszOwnerTag,
  ULONG cProps,
  LPSPropValue lpProps
);

Parameters

lpvUserContext
Input parameter. Points to the user-defined context.
lpwszOwnerTag
Input parameter. Points to the user-defined name of configuration.
cProps
Output parameter. Specifies the number of properties where lpProps points.
lpProps
Output parameter. Points to a MAPI SPropValue structure containing a property tag and its value.

Return Values

See Return Values.

Remarks

For information on the SPropValue structure, see the MAPI Programmer's Reference.

For more information on this function, see Using the Configuration Functions.

See Also

ADVISENOTIFY


BackupFree

The BackupFree function frees a backup memory buffer.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

VOID BackupFree(
  PVOID pvBuffer
);

Parameters

pvBuffer
Input parameter. Points to the memory buffer to be freed.

Return Values

None.

Remarks

The BackupFree function frees the buffer that was allocated for the call to the HrBackupRead function.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrBackupOpenFile


BatchExport

The BatchExport function exports objects from the Microsoft Exchange Server directory.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

DWORD BatchExport (
  LPBEXPORT_PARMS lpBexportParms
);

Parameters

lpBexportParms
Input parameter. Points to a BEXPORT_PARMS structure containing parameters for directory export operations.

Return Values

DWORD
Indicates the number of entries logged into the Microsoft Windows NT application log. This value does not indicate whether BatchExport completed successfully.

Remarks

The BatchExport function exports directory service objects. It uses the information in the BEXPORT_PARMS structure to control tasks such as error handling, progress monitoring, output format, and object export. This structure also specifies whether the output is written to a text file or processed in memory by a user-specified callback routine.

The return value does not indicate success or failure. The return value indicates the number of errors encountered and logged in the Windows NT application event log. See the event log for information about each error.

For more information on this function, see Using Directory Access Functions.

See Also

BatchImport


BatchImport

The BatchImport function imports directory service objects from a text file in a single function call.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

DWORD BatchImport(
  LPBIMPORT_PARMS lpBimportParms
);

Parameters

lpBimportParms
Input parameter. Points to a BIMPORT_PARMS structure that specifies the parameters for this function call.

Return Values

DWORD
Indicates the number of entries logged into the Windows NT Application Event Log. This value does not indicate whether BatchImport completed successfully.

Remarks

The BatchImport function uses the import file name specified in the BIMPORT_PARMS structure to import directory objects, but does not provide a high degree of control over the import operation.

The return value does not indicate whether BatchImport succeeded or failed. The return value specifies the number of errors encountered and logged in the Windows NT application event log. See the event log for information on the error.

For more information on this function, see Using Directory Access Functions.

See Also

BatchExport


CloseFolderMetrics

The CloseFolderMetrics function closes the folder snapshot statistics for this folder.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

VOID CloseFolderMetrics(
  HFLDMTRC hFolderMetric
);

Parameters

hFolderMetric
Input parameter. Specifies the handle to the calculations for this folder.

Return Values

None.

Remarks

The CloseFolderMetrics function closes the folder snapshot statistics for the folder. It is typically called at gateway shutdown.

For more information on this function, see Folder Snapshot Functions in the Gateway Programmer's Reference.

See Also

HrGetFolderMetrics, HrOpenFolderMetrics


CloseProxies

The CloseProxies function closes a proxy address generation session.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

VOID CloseProxies(
  HANDLE hProxySession
);

Parameters

hProxySession
Input parameter. Specifies the handle to the proxy address generation session, as returned in the RcInitProxies function.

Return Values

None.

Remarks

The CloseProxies function closes a proxy address generation session and frees any associated data pretaining thereto. Your program can then unload the proxy generation DLL.

For more information on this function, see Proxy Generation DLL Entry Points in the Gateway Programmer's Reference.

See Also

FreeProxy, RcGenerateProxy, RcValidateProxy


CommitDataProc

The CommitDataProc function permanently stores extension data.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL CommitDataProc(
  VOID * pvExtensionData,
  HWND hwnd
);

Parameters

pvExtensionData
Input parameter. Points to the Administrator extension DLL-managed block of memory.
hwnd
Input parameter. Specifies the handle to the property sheet window.

Return Values

This function must return a value as defined in Return Values.

Remarks

The CommitDataProc function is an optional Administrator extension DLL that is called by the Microsoft Exchange Server Administrator program when the Apply or OK button is pressed in a Properties dialog window. You save the extension data in the extension data attribute of the object with a call to PADMIN_SetObjectData in CommitDataProc.

For more information on this function, see Using the Configuration Functions.

See Also

ADMIN_Initialize, DeinitSheetProc, InitSheetProc, SaveDataProc


DAPI_FNErrorCallback

The DAPI_FNErrorCallback function is invoked by the BatchExport or BatchImport function each time an error is encountered during an export or import operation, respectively.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

BOOL DAPI_FNErrorCallback(
  LPVOID lpvAppDefined,
  PDAPI_EVENT pDapiEvent
);

Parameters

lpvAppDefined
Input parameter. Points to an application-defined parameter, passed in the EXPORT_CALLBACK structure on initialization. This parameter can be used to distinguish between different invocations of directory access functions.
pDapiEvent
Input parameter. Points to a DAPI_EVENT structure describing the event log error. The data in the event record is not valid after this function returns.

Return Values

TRUE
The operation completed successfully.
FALSE
Aborts the import or export operation.

Remarks

The DAPI_FNErrorCallback function is based on the DAPI_FNErrorCallback prototype.

If your application provides its own error handler, set the lpBexportParms->ErrorCallback parameter members of the BatchExport and BatchImport functions to point to this function.

For more information on this function, see Using Directory Access Functions.

See Also

InitProgressProc, UpdateProgressProc


DAPI_FNExportEntry

The DAPI_FNExportEntry function is invoked by BatchExport each time it exports an object in the directory.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

BOOL DAPI_FNExportEntry(
  EXP_TYPE ExportDataType,
  LPVOID lpvAppDefined,
  PDAPI_ENTRY pExportEntry
);

Parameters

ExportDataType
Input parameter. Specifies the type of data being exported:
EXPORT_HEADER
The first header line
EXPORT_ENTRY
Subsequent data lines
lpvAppDefined
Input parameter. Points to an application-defined parameter, passed in the EXPORT_CALLBACK structure on initialization.
pExportEntry
Input parameter. Points to a DAPI_ENTRY structure describing the exported entry data. Data in this structure is not valid after this function returns.

Return Values

TRUE
The operation completed successfully.
FALSE
Aborts the import or export operation.

Remarks

The DAPI_FNExportEntry callback function is based on the DAPI_FNExportEntry prototype. You set the lpBexportParms->ErrorCallback parameter member of the BatchExport function to point to this function.

For more information on this function, see Using Directory Access Functions.

See Also

InitProgressProc, UpdateProgressProc


DAPIAllocBuffer

The DAPIAllocBuffer function allocates or reallocates a block of memory.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

LPVOID DAPIAllocBuffer(
  ULONG cbSize,
  LPVOID pvAllocBase
);

Parameters

cbSize
Input parameter. Specifies the size (in bytes) of the requested memory block.
pvAllocBase
Input/output parameter. Points to the base address for the allocated memory block.

Return Values

NULL
If the memory is not available or pvAllocBase is not a legal allocation base.
A pointer to the allocated block of memory.
The function completed successfully.

Remarks

If pvAllocBase is not NULL, pvAllocBase must point to a memory block that was either previously allocated by DAPIAllocBuffer or returned by another directory function.

You release the allocated memory with a call to DAPIFreeMemory.

See Also

DAPIFreeMemory


DAPIEnd

The DAPIEnd function closes a directory operation session.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

VOID DAPIEnd(
  LPDAPI_HANDLE lphDAPISession
);

Parameters

lphDAPISession
Input parameter. Points to the handle of the current directory operation session.

Return Values

None.

Remarks

The DAPIEnd function closes a directory operation session opened by a call to DAPIStart. This function invalidates the DAPI_HANDLE obtained by the call to DAPIStart.

For more information on the DAPIEnd function, see Using Directory Access Functions.

See Also

DAPIRead, DAPIWrite


DAPIFreeMemory

The DAPIFreeMemory function releases or frees a block of memory.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

VOID DAPIFreeMemory(
  LPVOID lpVoid
);

Parameters

lpVoid
Points to the memory block to free.

Return Values

None.

Remarks

The DAPIFreeMemory function releases memory that was either allocated by DAPIAllocBuffer or allocated for structures returned by other directory functions.

See Also

DAPIStart


DAPIGetSiteInfo

The DAPIGetSiteInfo function retrieves the site information for a directory service agent.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

PDAPI_EVENT DAPIGetSiteInfo(
  DWORD dwFlags,
  LPTSTR pszDSA,
  PSITE_INFO * ppSiteInfo
);

Parameters

dwFlags
Input parameter. Reserved for future use.
pszDSA
Input parameter. Points to the name of the directory service agent (Microsoft Exchange Server name) from which to retrieve information.
ppSiteInfo
Output parameter. Points to a SITE_INFO structure.

Return Values

NULL
No errors were encountered.
A pointer to a DAPI_EVENT structure
An error was encountered.

Remarks

If the DAPIGetSiteInfo function fails and returns a pointer to a DAPI_EVENT, you must free the memory allocated for that structure with a call to the DAPIFreeMemory function.

For more information on this function, see Using Directory Access Functions.

See Also

DAPIFreeMemory


DAPIRead

The DAPIRead function reads (exports) attributes from a directory object.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

PDAPI_EVENT DAPIRead (
  DAPI_HANDLE hDAPISession,
  DWORD dwFlags,
  LPTSTR pszObjectName,
  DAPI_ENTRY pAttList,
  PDAPI_ENTRY * ppValues,
  PDAPI_ENTRY * ppAttributes
);

Parameters

hDAPISession
Input parameter. Specifies the directory operation session handle obtained through DAPIStart.
dwFlags
Input parameter. Accepts defined values that control the directory read operations. Use the bitwise OR operator (|) to enable multiple operations:
DAPI_READ_DEFINED_ATTRIBUTES
Returns all attributes that are set for the current object.
DAPI_READ_ALL_ATTRIBUTES
Returns all attributes that are defined for the class of the current object.
DAPI_MODIFY_REPLACE_PROPERTIES
Overwrites any existing properties when modifying.

You can also set these flags in the lpDAPIParms->dwFlags parameter member in the DAPIStart function. They remain in effect unless you override them. If both of these flags are set, DAPI_READ_ALL_ATTRIBUTES takes precedence.

pszObjectName
Input parameter. Points to a string containing the name of the object to read. If specified as a relative distinguished name (RDN), it is combined with the lpDAPIParms->pszBasePoint and lpDAPIParms->pszParentContainer parameter members in the DAPIStart function. If specified with the prefix "/cn=", the string is concatenated to the session pszBasePoint. If specified with the prefix "/o=", the string is taken to be a fully qualified distinguished name (DN).
pAttList
Input parameter. Points to a DAPI_ENTRY structure containing the names of the attributes to read. The session default list is overridden for the present call only. This parameter is ignored if either DAPI_READ_ALL_ATTRIBUTES or DAPI_READ_DEFINED_ATTRIBUTES is set in dwFlags.

If you specify export attributes in pAttList, the first attribute in pAttList must be NM_OBJECT_CLASS; otherwise, DAPIRead fails.

Normally, you cannot read the attributes of deleted objects. If you want to read the attributes of an object that has been deleted, but not purged, include the NM_IS_DELETED attribute.

ppValues
Output parameter. Points to the address where the pointer to a DAPI_ENTRY structure containing the values read from the DIT entry is stored. The pointer returned must be freed by a call to DAPIFreeMemory.
ppAttributes
Output parameter. If either DAPI_READ_ALL_ATTRIBUTES or DAPI_READ_DEFINED_ATTRIBUTES is set in dwFlag, points to the address where a DAPI_ENTRY structure containing the names of the attributes read from the DIT is stored. Otherwise, this parameter is NULL. If this value is not NULL, you must release the pointer with a call to DAPIFreeMemory before your program exits.

Return Values

NULL
No errors were encountered.
A pointer to a DAPI_EVENT structure
An error was encountered.

Remarks

If the return value is non-NULL, you must release the DAPI_EVENT structure with a call to DAPIFreeMemory before your program exits.

For more information on the DAPIRead function, see Using Directory Access Functions.

See Also

BatchExport, BatchImport, DAPIEnd, DAPIWrite


DAPIStart

The DAPIStart function initializes a directory operation session.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

PDAPI_EVENT DAPIStart (
  LPDAPI_HANDLE lphDAPISession,
  LPDAPI_PARMS lpDAPIParms
);

Parameters

lphDAPISession
Output parameter. Points to the handle of the directory operation session.
lpDAPIParms
Input parameter. Points to a DAPI_PARMS structure containing the directory interface object.

Note The value of the lpDAPIParms->pAttributes parameter member takes precedence over any conflicting lpDAPIParms->dwFlags parameter member values.

Return Values

NULL
No errors were encountered.
A pointer to a DAPI_EVENT structure
An error was encountered.

Note If you set the DAPI_EVENT_MIN bit in the lpDAPIParms->dwFlags parameter member, DAPIStart does not return a pointer to a DAPI_EVENT structure if it encounters an error. If an error occurs when you set the DAPI_EVENT_MIN bit in lpDAPIParms->dwFlags, the pointer to the directory operation session handle, lphDAPISession, is 0xFFFFFFFF.

Remarks

You can have no more than ten directory operation sessions open simultaneously.

The DAPI_HANDLE returned in lphDAPISession must be released through a call to DAPIEnd.

If the return value is non-NULL, you must release the DAPI_EVENT structure with a call to DAPIFreeMemory before your program exits.

For more information on this function, see Using Directory Access Functions.

See Also

DAPIRead, DAPIWrite


DAPIUninitialize

The DAPIUninitialize function terminates background processes.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

VOID DAPIUnitialize(
  DWORD dwFlags
);

Parameters

dwFlags
Unused. Must be 0 (zero).

Return Values

None.

Remarks

The SchemaPreload function is an example of a process terminated by DAPIUninitialize.

See Also

DAPIStart


DAPIWrite

The DAPIWrite function writes (imports) information to a directory object.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

PDAPI_EVENT DAPIWrite (
  DAPI_HANDLE hDAPISession,
  DWORD dwFlags,
  PDAPI_ENTRY pAttributes,
  PDAPI_ENTRY pValues,
  PULONG lpulUSN,
  LPTSTR * lppszCreatedAccount,
  LPTSTR * lppszPassword
);

Parameters

hDAPISession
Input parameter. Specifies the directory operation session handle obtained through DAPIStart.
dwFlags
Accepts defined values that control the directory write operations. Use the bitwise OR operator (|) to enable multiple operations:
DAPI_WRITE_UPDATE
If an object exists, you modify it; if it doesn't exist, you create it. This is the default mode.
DAPI_WRITE_CREATE
Creates the object. If the object exists, DAPIWrite fails.
DAPI_WRITE_MODIFY
Modifies the object. If the object does not exist, DAPIWrite fails.
DAPI_WRITE_DELETE
Deletes the object.
pAttributes
Input parameter. Points to a DAPI_ENTRY structure containing the names of attributes to write. If NULL, This function uses the session default list specified by DAPIStart.
pValues
Input parameter. Points to a DAPI_ENTRY structure containing the values to set on the DIT entry.

Note You can override the DAPI_WRITE_CREATE, DAPI_WRITE_DELETE, DAPI_WRITE_MODIFY, and DAPI_WRITE_UPDATE values in dwFlags by setting the second value in pAttributes to Mode and the second value in pValues to create, delete, modify, or update.

lpulUSN
Input/output parameter. Points to the USN of the updated DIT entry. If NULL, DAPIWrite does not update this value.
lppszCreatedAccount
Input parameter. Points to the name of created Windows NT account.
lppszPassword
Input parameter. Points to the password generated if a Windows NT account is created.

Return Values

NULL
No errors were encountered.
A pointer to a DAPI_EVENT structure
An error was encountered.

Remarks

If the return value is non-NULL, you must release the DAPI_EVENT structure with a call to DAPIFreeMemory before your program exits.

For more information on this function, see Using Directory Access Functions.

See Also

BatchImport, DAPIEnd, DAPIRead


DeinitSheetProc

The DeinitSheetProc function releases the memory for a property sheet dialog window.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID DeinitSheetProc(
  VOID * pvExtensionData
);

Parameters

pvExtensionData
Input parameter. Points to the Administrator extension DLL-managed block of memory to release.

Return Values

None.

Remarks

The DeinitSheetProc function is a mandatory Administrator extension DLL. It is called by the Microsoft Exchange Server Administrator program when a property sheet dialog window is about to be dismissed.

For more information on this function, see Using the Configuration Functions.

See Also

ADMIN_Initialize, CommitDataProc, InitSheetProc, SaveDataProc


DeinstallExtensionProc

The DeinstallExtensionProc function deletes a directory object.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL (* DeinstallExtensionProc)(
  ADMIN_ObjectInfo * poi
);

Parameters

poi
Input parameter. Points to an ADMIN_ObjectInfo structure containing the directory object that is being deleted.

Return Values

This function must return a value as defined in Return Values.

Remarks

The DeinstallExtensionProc function is a mandatory Administrator extension DLL. It is called by the Microsoft Exchange Server Administrator program, which then calls DeinitSheetProc to release any resources it holds by calling the MAPI_FreeBuffer function.

For information about MAPI_FreeBuffer, see the MAPI Programmer's Reference.

For more information on this function, see Using the Configuration Functions.

See Also

ADMIN_Initialize, CommitDataProc, InstallExtensionProc, SaveDataProc


DoHelpProc

The DoHelpProc function displays online Help for an extension data property sheet.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID DoHelpProc(
  VOID * pvExtensionData,
  HWND hwnd
);

Parameters

pvExtensionData
Input parameter. Points to the block of memory containing the extension data.
hwnd
Input parameter. Specifies the handle to the property sheet window.

Return Values

None.

Remarks

The DoHelpProc function is an optional Administrator extension DLL. If the HasHelpProc function of your Administrator extension DLL returns TRUE for an extension data property sheet, the Microsoft Exchange Server Administrator program calls this function when the Help button is pressed in that property sheet.

For more information on this function, see Using the Configuration Functions.

See Also

ADMIN_Initialize


EndProgressProc

The EndProgressProc function is invoked by the file-based batch processing functions of the directory access functions (BatchImport and BatchExport) based on the EndProgressProc prototype to dismiss the update dialog box or when a fatal processing condition has been encountered.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

BOOL (* EndProgressProc)(
  LPVOID lpvAppDefined
);

Parameters

lpvAppDefined
Points to an application-defined parameter that is supplied in the CALLBACKPROGRESS structure member of the BEXPORT_PARMS structure or the BIMPORT_PARMS structure argument to the BatchExport or BatchImport function, respectively.

Return Values

FALSE
The user cancelled the operation.
TRUE
Otherwise.

Remarks

The EndProgressProc function must deallocate any memory that was allocated by the call to InitProgressProc.

For more information on the EndProgessProc function, see Using Directory Access Functions.

See Also

NTExport, NTEXPORT_PARMS, NWExport, NWEXPORT_PARMS, ResetProgressProc, UpdateProgressProc


EventLogMsg

The EventLogMsg function logs an event to the event log, and, optionally, logs the original error(s) that caused the event.

Quick Info

Header file: | EDKEVENT.H
Library: | EDKEVENT.LIB
Unicode: | Yes

VOID EventLogMsg(
  DWORD dwEvent,
  DWORD cStrings, {text string parameters},
  DWORD cErrorCodes, {error code parameters}
);

Parameters

dwEvent
Input parameter. Specifies the error code of the event to log.
cStrings
Input parameter. Specifies the number of text string parameters.
{text string parameters}
Input parameter. Specifies the text string parameters:
[LPTSTR pszString1]
[LPTSTR pszString2]
[...................]
[LPTSTR pszStringN]
cErrorCodes
Input parameter. Specifies the number of error code parameters.
{error code parameters}
Input parameter. Specifies the error code parameters:
[DWORD dwErrorCode1]
[DWORD dwErrorCode2]
[.....................]
[DWORD dwErrorCodeN]

Return Values

None.

Remarks

Each of these strings and error codes are used as parameters to the message in their order of appearance. This means that all of the error-message replacement parameters in event messages must have higher numbers than all of the string replacement parameters. For example:

EventLogMsg(MYAPP_CANNOT_COPY_FILE, 2, pszSourceFile, pszDestFile, 1, dwError);

The message would be defined as:

MessageId=
Severity=Error
Facility=Application
SymbolicName=MYAPP_CANNOT_COPY_FILE
Language=English
Cannot copy file from %1 to %2 due to the following error:%n%3.

The error code count and error code list are required after the text string count and text string list. Failure to include the error code argument(s) may cause unexpected results.

This routine preserves the last error value returned by the MAPI IMAPIProp::GetLastError method.

For information on the IMAPIProp::GetLastError method, see the MAPI Programmer's Reference.

See Also

HrEventCloseLog, HrEventGetCounts, HrEventGetHandle, HrEventOpenLog, HrEventUseExisting


FHasAdminPrivs

The FHasAdminPrivs function determines whether the current user is an administrator.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

BOOL FHasAdminPrivs(
  VOID
);

Parameters

None.

Return Values

TRUE
The current user has administrator privileges.
FALSE
The current user does not have administrator privileges.

Remarks

None.

See Also

HrEnumSiteAdmins


FIsPublicStore

The FIsPublicStore function determines whether an information store is a public store.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

BOOL FIsPublicStore(
  LPMDB lpmdb
);

Parameters

lpmdb
Input parameter. Points to a MAPI IMsgStore interface containing the information store.

Return Values

TRUE
Points to a public store.
FALSE
Does not point to a public store.

Remarks

For information on obtaining a pointer to the IMsgStore interface, see the IMAPISession::OpenMsgStore method in the MAPI Programmer's Reference.

For more information on this function, see Determining the Type of Information Store.


FIsService

The FIsService function determines whether an application is running as a service of Windows NT Server.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

BOOL FIsService(
  VOID
);

Parameters

VOID

Return Values

TRUE
The application is running as a service of Windows NT Server.
FALSE
The application is not running as a service of Windows NT Server.

Remarks

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


FreeProxy

The FreeProxy function frees memory allocated for a proxy address string.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

VOID FreeProxy(
  LPWSTR pszProxy
);

Parameters

pszProxy
Input parameter. Points to a Unicode string containing the proxy address to free.

Return Values

None.

Remarks

The FreeProxy function frees the allocated memory with a call to RcGenerateProxy.

For more information on the this function, see Proxy Generation DLL Entry Points in the Gateway Programmer's Reference.

See Also

CloseProxies, RcInitProxies, RcValidateProxy


FreeThreadParameter

The FreeThreadParameter function frees the thread context.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

VOID FreeThreadParameter(
  LPVOID lpParameter
);

Parameters

lpParameter
Input parameter. Points to the thread context to free.

Return Values

None.

Remarks

For more information on the FreeThreadParameter function, see the PROCESS.C file under the GWMAIN code sample in the Code Samples folder.

See Also

HrGWStartNewFileHandler, HrGWStartNewMailHandler


FServiceReportStatus

The FServiceReportStatus function updates the status of a service of Windows NT Server to the Windows NT service control manager.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

BOOL FServiceReportStatus(
  DWORD dwCurrentState,
  DWORD dwWin32ExitCode,
  DWORD dwServiceSpecificExitCode,
  DWORD dwCheckPoint,
  DWORD dwWaitHint
);

Parameters

dwCurrentState
Input parameter. Indicates the current state of the service of Windows NT Server. Value can be one of the following:
SERVICE_CONTINUE_PENDING
SERVICE_PAUSE_PENDING
SERVICE_PAUSED
SERVICE_RUNNING
SERVICE_START_PENDING
SERVICE_STOP_PENDING
SERVICE_STOPPED
dwWin32ExitCode
Input parameter. Specifies a Win32 error code used by the service of Windows NT Server to report a starting or stopping error.
dwServiceSpecificExitCode
Input parameter. Specifies the service-specific exit code.
dwCheckPoint
Input parameter. Specifies the value that the service of Windows NT Server increments periodically to report its progress during a lengthy start, stop, or continue operation.
dwWaitHint
Input parameter. Specifies the time period (in milliseconds) that the service of Windows NT Server expects a pending start, stop, or continue operation to take.

Return Values

See Return Values.

Remarks

FServiceReportStatus is called by the ServiceMain function to update the service's status to the service control manager.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceStop


GetAdrBookPtr

The GetAdrBookPtr function gets the address book for the gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPADRBOOK GetAdrBookPtr(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IAddrBook interface containing the address book for the gateway.

Remarks

For information on the IAddrBook interface, see the MAPI Programmer's Reference.

See Also

HrFindExchangeGlobalAddressList


GetGWDefaultStore

The GetGWDefaultStore function obtains a pointer to the default gateway store.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPMDB GetGWDefaultStore(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IMsgStore interface containing the default gateway store.

Remarks

For information on the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrGWFindMtsInFolder, HrGWFindMtsOutFolder


GetGWExchangeServerName

The GetGWExchangeServerName function obtains the name of the server for the current gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPSTR GetGWExchangeServerName(
  VOID
);

Parameters

None.

Return Values

A pointer to the name of the server for the current gateway.

Remarks

None. See Also

HrInstallGateway


GetGWFindData

The GetGWFindData function retrieves a WIN32_FIND_DATA structure.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPWIN32_FIND_DATA GetGWFindData(
  LPVOID lpParameter
);

Parameters

lpParameter
Input parameter. Points to the thread handle from HrGWStartNewMailHandler.

Return Values

A pointer to a Win32 WIN32_FIND_DATA structure. You can determine the size of this structure with a call to the GetGWFindDataSize function.

Remarks

For more information on the WIN32_FIND_DATA structure, see the Win32 Structures documentation in the "Reference" section of the Microsoft Platform SDK.

See Also

HrGWStartNewMailHandler


GetGWFindDataSize

The GetGWFindDataSize function retrieves the size of the WIN32_FIND_DATA structure of the gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

ULONG GetGWFindDataSize(
  LPVOID lpParameter
);

Parameters

lpParameter
Points to the thread handle from HrGWStartNewMailHandler.

Return Values

A ULONG specifying the size (in bytes) of the Win32 WIN32_FIND_DATA structure of the gateway.

Remarks

You must determine the size of the WIN32_FIND_DATA structure of the gateway so you can allocate enough space for the GetGWFindData function.

For information on the WIN32_FIND_DATA structure, see the Win32 Structures documentation in the "Reference" section of the Microsoft Platform SDK.

See Also

HrGWStartNewMailHandler


GetGWGAL

The GetGWGAL function retrieves a pointer to the global address list (GAL) for the gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPABCONT GetGWGAL(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IABContainer interface containing the global address list (GAL) for the gateway.

Remarks

For information on the IABContainer interface, see the MAPI Programmer's Reference.

See Also

GetGWGALEntryId, GetGWGALEntryIdSize


GetGWGALEntryId

The GetGWGALEntryId function obtains the global address list (GAL) entry identifier.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPENTRYID GetGWGALEntryId(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI ENTRYID structure containing the global address list entry identifier.

Remarks

You must allocate the space for the ENTRYID structure that this function returns. Use the GetGWGALEntryIdSize function to determine the correct size.

For information on the ENTRYID structure, see the MAPI Programmer's Reference.

See Also

GetGWGAL


GetGWGALEntryIdSize

The GetGWGALEntryIdSize function obtains the number of bytes in the global address list (GAL) entry identifier.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

ULONG GetGWGALEntryIdSize(
  VOID
);

Parameters

None.

Return Values

A ULONG value specifying the size (in bytes) of the GAL entry identifier.

Remarks

The GetGWGALEntryIdSize function determines the size of the MAPI ENTRYID structure representing the GAL entry identifier. You can use this size to determine the amount of memory to allocate for the information returned by the GetGWGALEntryId function.

For information on the ENTRYID structure, see the MAPI Programmer's Reference.

See Also

GetGWGAL


GetGWMtsInFolder

The GetGWMtsInFolder function retrieves the inbound message folder, MTS-IN.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPMAPIFOLDER GetGWMtsInFolder(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IMAPIFolder interface containing the inbound message folder, MTS-IN.

Remarks

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

GetGWMtsOutFolder


GetGWMtsOutFolder

The GetGWMtsOutFolder function retrieves the outbound message folder, MTS-OUT.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPMAPIFOLDER GetGWMtsOutFolder(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IMAPIFolder interface containing the outbound message folder, MTS-OUT.

Remarks

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

GetGWMtsInFolder


GetGWNewMailEvent

The GetGWNewMailEvent function obtains a new mail event.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

HANDLE GetGWNewMailEvent(
  VOID
);

Parameters

None.

Return Values

A handle to a new mail event.

Remarks

If no events are pending, the GetGWNewMailEvent function returns NULL.

See Also

GetGWNewMailStatus


GetGWNewMailStatus

The GetGWNewMailStatus function determines whether there is new mail in the user's Inbox.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

BOOL GetGWNewMailStatus(
  VOID
);

Parameters

None.

Return Values

TRUE
There is new mail in the user's mailbox.
FALSE
There is no new mail in the user's mailbox.

See Also

GetGWNewMailEvent


GetGWPath

The GetGWPath function retrieves the full path to the gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPTSTR GetGWPath(
  LPVOID lpParameter
);

Parameters

lpParameter
The thread handle from HrGWStartNewMailHandler.

Return Values

A pointer to a string containing the full path to the gateway.

See Also

HrGWStartNewMailHandler


GetGWRootFolder

The GetGWRootFolder function retrieves the root folder.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPMAPIFOLDER GetGWRootFolder(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IMAPIFolder interface containing the root folder.

Remarks

For information about the IMAPIFolder interface and MAPIFOLDER structure, see the MAPI Programmer's Reference.


GetGWSession

The GetGWSession function retrieves the gateway session.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPMAPISESSION GetGWSession(
  VOID
);

Parameters

None.

Return Values

A pointer to a MAPI IMAPISession interface containing the gateway session.

Remarks

For information on the IMAPISession interface, see the MAPI Programmer's Reference.


GetGWSRowSet

The GetGWSRowSet function obtains a set of properties on the current object.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

LPSRowSet GetGWSRowSet(
  LPVOID lpParameter
);

Parameters

lpParameter
Points to the thread handle from HrGWStartNewMailHandler.

Return Values

A pointer to a MAPI SRowSet structure containing a set of properties on the current object.

Remarks

The returned value is a pointer to a SRowSet structure, which is a table of properties for the current object. This structure contains an array of MAPI SRow structures, each of which is a row of the table of object properties.

Note To release memory that you have allocated for a SRowSet structure, use the MAPI FreeProws function. If you use the MAPI MAPIFreeBuffer function, your application will leak memory.

For information on the FreeProws function, MAPIFreeBuffer function, SPropValue structure, SRow structure, and SRowSet structure, see the MAPI Programmer's Reference.

See Also

HrGWStartNewMailHandler


GetGWSubmitInterval

The GetGWSubmitInterval function retrieves the current submission interval (in seconds).

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

DWORD GetGWSubmitInterval(
  LPVOID lpParameter
);

Parameters

lpParameter
Points to the thread handle from HrGWStartNewMailHandler.

Return Values

The current submission interval (in seconds).

Remarks

Whenever a gateway transfers a message to a server's MTS-IN folder, it submits the message to that server. Occassionally, Microsoft Exchange Server cannot accept the submission of a message, and the gateway must wait a period of time before it should attempt a re-submission. This period of time is called the submission interval.

See Also

HrGWStartNewMailHandler


GetServiceInstance

The GetServiceInstance function obtains the handle for the service instance.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HANDLE GetServiceInstance(
  VOID
);

Parameters

None.

Return Values

The handle for this instance of the service.

Remarks

The GetServiceInstance function is a non-core function.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

HrGetServiceStatus, HrServiceStartup


GetServiceStopEvent

The GetServiceStopEvent function obtains the handle for the service stop event.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HANDLE GetServiceStopEvent(
  VOID
);

Parameters

None.

Return Values

The handle for this service stop event.

Remarks

For more information on GetServiceStopEvent function, see Using WINWRAP Functions.

For more information on the WINWRAP library, see Mandatory Entry Points and Variables, and Events Signalled.


GWMain

The GWMain function executes a separate thread.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

VOID GWMain(
  VOID
);

Parameters

None.

Return Values

None.

Remarks

For more information on this function, see Using WINWRAP Functions.

See Also

HrGWLogoff, HrGWLogon


HasHelpProc

The HasHelpProc function determines whether online Help is available for the Administrator extension DLL property sheets.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL HasHelpProc(
  VOID * pvExtensionData,
  HWND hwnd
);

Parameters

pvExtensionData
Input parameter. Points to the block of memory.
hwnd
Input parameter. Specifies the handle of the property sheet window.

Return Values

TRUE
The property sheet has a Help file available.
FALSE
The property sheet does not have a Help file available.

Remarks

The HasHelpProc function is an optional Administrator extension DLL. It is called by the Microsoft Exchange Server Administrator program for each extension data property page. For more information on this function, see Using Administrator Extension Functions (Called by Administrator Program).

See Also

DoHelpProc, ADMIN_Initialize


HrActionToString

The HrActionToString function produces a string from an ACTION structure.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrActionToString(
  LPMAPISESSION lpSession,
  LPACTION lpAction,
  LPSTR FAR * lppszString
);

Parameters

lpSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session.
lpAction
Input parameter. Points to an ACTION structure, which identifies the action to be converted to a string.
lppszString
Output parameter. Points to the address of the string.

Return Values

See Return Values.

Remarks

If the call to HrActionToString fails, lppszString is NULL.

For information on the IMAPISession interface, see the MAPI Programmer's Reference.

See Also

HrStringToAction


HrAddressTemplateExists

The HrAddressTemplateExists function determines whether a given site has an address template.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrAddressTemplateExists(
  LPTSTR lpszServer,
  LPTSTR lpszSiteDN,
  LPTSTR lpszCommonName,
  LPTSTR lpszAddressType,
  LPTSTR lpszLanguage)
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name (DN) of the site.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the site.
lpszAddressType
Input parameter. Points to a null-terminated string containing the address type supported by the template.
lpszLanguage
Input parameter. Points to a null-terminated string containing the language supported by the template.

Return Values

See Return Values.

Remarks

For more information on address templates, see Installing Addressing Objects.

See Also

HrInstallAddressTemplate, HrRemoveAddressTemplate


HrAddressTypeExists

The HrAddressTypeExists function determines whether an address type exists on a given site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrAddressTypeExists(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName,
  LPSTR lpszMachineType)
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the site.
lpszMachineType
Input parameter. Points to a null-terminated string containing the computer type, such as i386.

Return Values

See Return Values.

Remarks

The HrAddressTypeExists function determines whether there is a gateway available on the server for a given type of address (Addr-Type). For more information on address types, see The Addr-Type Object in the Gateway Programmer's Reference.

See Also

HrGetAddressTypeVersion, HrInstallAddressType, HrRemoveAddressType


HrAdminExtensionExists

The HrAdminExtensionExists function determines whether an Administrator extension exists on a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrAdminExtensionExists(
  LPTSTR lpszServer,
  LPTSTR lpszSiteDN,
  LPTSTR lpszCommonName,
  LPTSTR lpszMachineType
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the site.
lpszMachineType
Input parameter. Points to a null-terminated string containing the computer type, such as i386.

Return Values

See Return Values.

Remarks

For more information on the HrAdminExtensionExists function, see Using Administrator Extension Functions (Called by Administrator Program).

See Also

HrGetAdminExtensionVersion, HrInstallAdminExtension, HrRemoveAdminExtension


HrAdminProgramExists

The HrAdminProgramExists function determines whether the Microsoft Exchange Server Administrator program has been installed on the local computer.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrAdminProgramExists(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

If the Administrator program is not installed on the local computer, the HrAdminProgramExists function returns NULL.

See Also

HrInstallAdminExtension


HrBackupClose

The HrBackupClose function closes the file that is being backed up.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

HRESULT HrBackupClose(
  HBC pvBackupContext
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.

Return Values

See Return Values.

Remarks

For more information on the HrBackupClose function, see Backing Up and Restoring Data.

See Also

HrBackupOpenFile


HrBackupEnd

The HrBackupEnd function cleans up after a backup operation is finished.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

HRESULT HrBackupEnd(
  HBC pvBackupContext
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.

Return Values

See Return Values.

Remarks

The HrBackupEnd function closes outstanding binding handles and does whatever is necessary to clean up after a successful or unsuccessful backup attempt.

For more information on the HrBackupEnd function, see Backing Up and Restoring Data.

See Also

HrRestoreEnd


HrBackupGetBackupLogs

The HrBackupGetBackupLogs function obtains the list of log files to back up.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrBackupGetBackupLogs(
  HBC pvBackupContext,
  LPSTR *szBackupLogFile,
  PDWORD pcbSize
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.
szBackupLogFile
Output parameter. Points to a list of null-terminated log names as UNC paths. The list is terminated by a double-null character (\0\0).
pcbSize
Output parameter. Points to the number of bytes returned in the buffer.

Return Values

See Return Values.

Remarks

The list of log files are the only files that need to be backed up for a differential or incremental backup. For a full backup, these files need to be backed up in addition to those returned by the HrBackupGetDatabaseNames function.

For more information on the HrBackupGetBackupLogs function, see Backing Up and Restoring Data.

See Also

HrBackupGetDatabaseNames


HrBackupGetDatabaseNames

The HrBackupGetDatabaseNames function obtains the list of attached databases on the remote computer.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrBackupGetDatabaseNames(
  HBC pvBackupContext,
  LPSTR *ppszAttachmentInformation,
  LPDWORD pcbSize
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.
ppszAttachmentInformation
Output parameter. Points to a list of null-terminated database names as UNC paths. The list is terminated by a double-null character (\0\0).
pcbSize
Output parameter. Points to the total number of bytes returned in the buffer.

Return Values

See Return Values.

Remarks

The HrBackupGetDatabaseNames function allocates a buffer of sufficient size to hold the entire attachment list. These files need to be backed up for a full backup, but not for a differential or incremental backup. In addition, the files returned by HrBackupGetBackupLogs must be backed up for a full backup.

For more information on the HrBackupGetDataBaseNames function, see Backing Up and Restoring Data.

See Also

HrBackupGetBackupLogs


HrBackupOpenFile

The HrBackupOpenFile function opens a remote file for backup and performs whatever client and server side operations are necessary to prepare for the backup.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrBackupOpenFile(
  HBC pvBackupContext,
  WCHAR * wszAttachmentName,
  DWORD cbReadHintSize,
  LARGE_INTEGER * pliFileSize
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.
wszAttachmentName
Input parameter. Specifies the name of the file to back up.
cbReadHintSize
Input parameter. The size of the buffer (in 4096-byte multiples) that is passed as the pvBuffer argument to HrBackupRead. The backup functions use this value to optimize the network traffic.
pliFileSize
Output parameter. Points to the size (in bytes) of the file to back up.

Return Values

See Return Values.

Remarks

For more information on the HrBackupOpenFile function, see Backing Up and Restoring Data.

See Also

HrBackupRead


HrBackupPrepare

The HrBackupPrepare function connects to a remote Microsoft Exchange Server database and prepares it for backup.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrBackupPrepare(
  char * szBackupServer,
  char * szBackupAnnotation,
  unsigned long grbit,
  unsigned long btBackupType,
  HBC * hbcBackupContext
);

Parameters

szBackupServer
Input parameter. Specifies the name of the server to backup. Preceding backslashes are optional. An example of a server name is \\server1.

Note The server name cannot contain an underscore.

szBackupAnnotation
Input parameter. Specifies the database to backup.
grbit
Input parameter. Determines whether to back up all log files during an incremental backup or the uncommitted log files during a full backup.
1
Backup the log files.
0
Do not backup the log files.
btBackupType
Input parameter. Specifies the type of backup to perform.
BACKUP_TYPE_FULL
Full backup. All data is backed up and transaction log files are truncated.
BACKUP_TYPE_LOGS_ONLY
Backup only database logs, but not the database. This is normally used when performing a differential or incremental backup.

Note Use this parameter to test whether this type of backup can be performed at this time. If this function fails with a certain btBackupType, this type of backup is not allowed.

hbcBackupContext
Output parameter. Specifies the client-side context handle for the backup.

Return Values

See Return Values.

Remarks

The HrBackupPrepare function requires that the caller is a member of the Backup Operators group on the server.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrBackupEnd


HrBackupRead

The HrBackupRead function reads one block from a backup file.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

HRESULT HrBackupRead(
  HBC pvBackupContext,
  PVOID pvBuffer,
  DWORD cbBuffer,
  PDWORD pcbRead
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.
pvBuffer
Input parameter. Points to the buffer in which to hold the data being backed up.
cbBuffer
Input parameter. Specifies the size of the buffer where pvBuffer points. If the communication protocol is not TCP/IP, this value must be a multiple of 4096 bytes.
pcbRead
Output parameter. Points to the number of bytes read.

Note The number of bytes read, pcbRead, may be less than the size of the buffer, cbBuffer. This does not indicate an error. Some transports fragment the buffer being transmitted instead of filling the entire buffer with data.

Return Values

See Return Values.

Remarks

Your application must allocate the space for the buffer where pvBuffer points and release this space with a call to BackupFree when you are finished with the buffer.

If the client or server cannot communicate via TCP/IP, the buffer must be a multiple of 4096 bytes. If your application does not use buffer sizes that are a multiple of 4096 bytes or the TCP/IP communication protocol, HrBackupRead fails.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrBackupOpenFile


HrBackupTruncateLogs

The HrBackupTruncateLogs function deletes the committed database log files.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

HRESULT HrBackupTruncateLogs(
  HBC pvBackupContext
);

Parameters

pvBackupContext
Input parameter. Points to the client-side context handle of the backup.

Return Values

See Return Values.

Remarks

Use the HrBackupTruncateLogs function when a full or incremental backup has completed successfully.

Warning Do not use this function after a differential backup.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrSetCurrentBackupLog


HrCfgAdvise

The HrCfgAdvise function monitors an extension data section.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrCfgAdvise(
  LPADVISEOBJ lpAdviseObj,
  LPSTR lpszSection,
  LPADVISECALLBACK lpfnCallback,
  LPVOID lpvUserContext
);

Parameters

lpAdviseObj
Input parameter. Points to an ADVISEOBJ structure containing an advise object.
lpszSection
Input parameter. Points to the name of the extension data section.
lpfnCallback
Input parameter. Points to an ADVISECALLBACK function to call on changes.
lpvUserContext
Input parameter. Points to a user-defined context.

Return Values

See Return Values.

Remarks

When the extension data changes, Microsoft Exchange Server calls the callback routine specified in the ADVISECALLBACK function where the lpfnCallback parameter points. The callback routine is called by the HrCfgAdvise function to initialize the extension data values.

Note You must first call the HrCfgCreateAdviseObj function to obtain the pointer to the ADVISEOBJ structure for the lpAdviseObj parameter.

For more information on this function, see Using the Configuration Functions.

See Also

HrCfgDestroyAdviseObj, HrCfgPollAdviseObj, HrCfgUnadvise


HrCfgCreateAdviseObj

The HrCfgCreateAdviseObj function monitors a MAPI session for changes to the extension data.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrCfgCreateAdviseObj(
  LPMAPISESSION lpSession,
  ULONG nPollInterval,
  LPADVISEOBJ * lppAdviseObj
);

Parameters

lpSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session to monitor.
nPollInterval
Input parameter. Specifies the interval (in milliseconds) between polling.
lppAdviseObj
Output parameter. Points to a pointer to the ADVISEOBJ structure containing created advise object.

Return Values

See Return Values.

Remarks

The HrCfgCreateAdviseObj function should be called once to create an advise object for a MAPI session that is being monitored. Then, you should call HrCfgAdvise once for each extension data section that is being monitored. If nPollInterval == 0, then no monitoring thread is created, and the user must do polling manually by calling HrCfgPollAdviseObj.

For more information on this function, see Using the Configuration Functions.

For information on the IMAPISession interface, see the MAPI Programmer's Reference.

See Also

HrCfgDestroyAdviseObj, HrCfgUnadvise


HrCfgDestroyAdviseObj

The HrCfgDestroyAdviseObj function ends the monitoring of a MAPI session.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrCfgDestroyAdviseObj(
  LPADVISEOBJ lpAdviseObj
);

Parameters

lpAdviseObj
Input parameter. Points to the ADVISEOBJ structure containing advise object to destroy.

Return Values

See Return Values.

Remarks

The HrCfgDestroyAdviseObj function releases any resources allocated for the monitoring of a MAPI session that began with a call to the HrCfgCreateAdviseObj function, which in turn calls HrCfgUnadvise for any extension data sections that are actively being monitored.

For more information on this function, see Using the Configuration Functions.

See Also

HrCfgAdvise, HrCfgPollAdviseObj


HrCfgPackData

The HrCfgPackData function packs a configuration name and a set of MAPI properties into a binary buffer suitable to be saved in the directory information tree for the gateway or other object.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB
Unicode: | Yes

HRESULT HrCfgPackData(
  LPTSTR lpszConfigName,
  ULONG cProps,
  LPSPropValue lpProps,
  ULONG * lpcbConfigData,
  LPBYTE * lppbConfigData
);

Parameters

lpszConfigName
Input parameter. Points to the name of the configuration (NULL is valid).
cProps
Input parameter. Specifies the number of MAPI properties that are packed.
lpProps
Input parameter. Points to a MAPI SPropValue structure containing the properties that are packed.
lpcbConfigData
Output parameter. Poiints to the size of the resulting binary buffer.
lppbConfigData
Output parameter. Points to a pointer to the resulting binary buffer.

Return Values

See Return Values.

Remarks

For information on the SPropValue structure, see the MAPI Programmer's Reference.

For more information on the HrCfgPackData function, see Using the Configuration Functions.

See Also

HrCfgUnpackData


HrCfgPollAdviseObj

The HrCfgPollAdviseObj function checks an advise object against what is stored in the directory.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrCfgPollAdviseObj(
  LPADVISEOBJ lpAdviseObj
);

Parameters

lpAdviseObj
Input parameter. Points to the ADVISEOBJ structure containing the advise object to poll.

Return Values

See Return Values.

Remarks

The HrCfgPollAdviseObj function calls the notification functions if there are any changes.

For more information on this function, see Using the Configuration Functions.

See Also

HrCfgAdvise, HrCfgCreateAdviseObj, HrCfgDestroyAdviseObj, HrCfgUnadvise


HrCfgPropertyTagFromNameId

The HrCfgPropertyTagFromNameId function retrieves the MAPI property tag and name identifier for an IMAPIProp interface.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrCfgPropertyTagFromNameId(
  LPMAPIPROP lpMAPIProp,
  LONG lNameID,
  ULONG * lpulPropTag
);

Parameters

lpMAPIProp
Input parameter. Points to an IMAPIProp interface.
lNameID
Input parameter. Specifies the name identifier for an IMAPIProp interface.
lpulPropTag
Output parameter. Points to the MAPI property tag of the name identifier.

Return Values

See Return Values.

Remarks

For more information on the HrCfgPropertyTagFromNameId function, see Using the Configuration Functions.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference


HrCfgUnadvise

The HrCfgUnadvise function ends the monitoring of an extension data section.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrCfgUnadvise(
  LPADVISEOBJ lpAdviseObj,
  LPTSTR lpszSection
);

Parameters

lpAdviseObj
Input parameter. Points to the ADVISEOBJ structure containing the advise object.
lpszSection
Input parameter. Points to the name of the extension data section.

Return Values

See Return Values.

Remarks

For more information on the HrCfgUnadvise function, see Using the Configuration Functions.

See Also

HrCfgAdvise, HrCfgCreateAdviseObj, HrCfgDestroyAdviseObj, HrCfgPollAdviseObj


HrCfgUnpackData

The HrCfgUnpackData function unpacks a packed binary buffer to yield a configuration name, a number of properties, and an array of MAPI properties.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB
Unicode: | Yes

HRESULT HrCfgUnpackData(
  ULONG cbConfigData,
  LPBYTE lpbConfigData,
  LPTSTR * lppszConfigName,
  ULONG * lpcProps,
  LPSPropValue * lppProps
);

Parameters

cbConfigData
Input parameter. Specifies the size of the unpacked binary structure.
lpbConfigData
Input parameter. Points to an unpacked binary structure.
lppszConfigName
Output parameter. Points to a pointer to the name of the configuration (NULL is valid).
lpcProps
Output parameter. Points to the number of MAPI properties that are unpacked.
lppProps
Output parameter. Points to a pointer to the MAPI SPropValue structure containing the properties that are unpacked.

Return Values

See Return Values.

Remarks

The HrEDKCfgUnpackData function creates a buffer in memory, then unpacks and copies the extension data from the directory object into the buffer.

If lppszConfigName returns NULL, there is no configuration name at the start of the buffer.

For more information on this function, see Using the Configuration Functions.

For information on the SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrCfgPackData, HrOpenSiteContainer


HrCleanupPSTGlobals

The HrCleanupPSTGlobals function releases any objects involved in the creation of a new PST.

Quick Info

Header file: | NEWPST.H
Library: | NEWPST.LIB

HRESULT HrCleanupPSTGlobals(
  LPSTR lpszProfileName
);

Parameters

lpszProfileName
Input parameter. Temporary profile name from HrCreatePersonalStore.

Return Values

See Return Values.

Remarks

The HrCleanupPSTGlobals function should be called after the MAPI IMAPISession::Logoff method and the MAPI IMAPISession::Release (the Release method is inherited from the Win32 IUnknown interface) methods are called for the MAPI session and before the MAPI MAPIUninitialize function is called.

For more information on the IMAPISession::Logoff and IMAPISession::Release methods, as well as the MAPIUninitialize function, see the MAPI Programmer's Reference.

See Also

HrCreatePersonalStore


HrConvConvert

The HrConvConvert function converts a message and then returns the results of the conversion.

Quick Info

Header file: | CONVCWRP.H
Library: | CONVCWRP.LIB

HRESULT HrConvConvert(
  PVOID pvConvInst,
  PEDKCNVENV pEnv,
  LPCWSTR pszContentClass,
  PVOID pContentIn,
  PVOID pContentOut,
  EDKCNVRES * pcrResult
);

Parameters

pvConvInst
Input parameter. Points to an instance of the conversion engine.
pEnv
Input parameter. Points to the environment of the conversion.
pszContentClass
Input parameter. Points to the class of source to be converted.
pContentIn
Input parameter. Points to the source to be converted.
pContentOut
Input parameter. Points to the converted object.
pcrResult
Output parameter. Points to the finished conversion, if the conversion is successful. Otherwise, pcrResult is undefined.

Return Values

See Return Values.

Remarks

For more information on the HrConvConvert function, see Translating Messages Using a Translation DLL in the Gateway Programmer's Reference.


HrConvInitGlobals

The HrConvInitGlobals function initializes common data areas for the gateway conversion engine.

Quick Info

Header file: | CONVCWRP.H
Library: | CONVCWRP.LIB

VOID HrConvInitGlobals(
  VOID
);

Parameters

None.

Return Values

None.

Remarks

The HrConvInitGlobals function is called only once by the gateway. It must be called before any other gateway conversion function.

For more information on this function, see Translating Messages Using a Translation DLL section in the Gateway Programmer's Reference.

See Also

HrConvUninitGlobals


HrConvInitInstance

The HrConvInitInstance function creates a new instance of the conversion engine.

Quick Info

Header file: | CONVCWRP.H
Library: | CONVCWRP.LIB

HRESULT HrConvInitInstance(
  HANDLE hEventSource,
  PVOID * ppvConvInst
);

Parameters

hEventSource
Input parameter. Specifies the handle of the event source.
ppvConvInst
Output parameter. Points to a pointer to the memory storing the conversion engine instance.

Return Values

See Return Values.

Remarks

Each instance of the conversion engine is single-threaded. Multiple instances can be used in separate threads.

For more information on the HrConvInitInstance function, see Translating Messages Using a Translation DLL in the Gateway Programmer's Reference.

See Also

HrConvUninitInstance


HrConvUninitGlobals

The HrConvUninitGlobals function uninitializes the common data areas for the gateway conversion engine.

Quick Info

Header file: | CONVCWRP.H
Library: | CONVCWRP.LIB

VOID HrConvUninitGlobals(
  VOID
);

Parameters

None.

Return Values

None.

Remarks

The HrConvUninitGlobals function is called by the gateway after all of the gateway conversion functions are complete.

See Also

HrConvInitGlobals


HrConvUninitInstance

The HrConvUninitInstance function deletes a previously allocated conversion engine instance.

Quick Info

Header file: | CONVCWRP.H
Library: | CONVCWRP.LIB

HRESULT HrConvUninitInstance(
  PVOID pvConvInst
);

Parameters

pvConvInst
Input parameter. Points to the memory storing the conversion engine instance to be freed.

Return Values

See Return Values.

Remarks

For more information on the HrConvUninitInstance function, see Translating Messages Using a Translation DLL section in the Gateway Programmer's Reference.

See Also

HrConvInitInstance


HrCopyActions

The HrCopyActions function creates a copy of an ACTIONS structure.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrCopyActions(
  LPACTIONS lpActsSrc,
  LPVOID lpObject,
  LPACTIONS FAR * lppActsDest
);

Parameters

lpActsSrc
Input parameter. Points to the ACTIONS structure to be copied.
lpObject
Input parameter. Points to an existing MAPI buffer allocated by the MAPI MAPIAllocateBuffer function, or returns NULL if the returned structure is to be allocated by HrCopyActions.
lppActsDest
Output parameter. Points to a pointer to the copy of the ACTIONS structure pointed to by lpActsSrc.

Return Values

See Return Values.

Remarks

For information on the MAPIAllocateBuffer function, see the MAPI Programmer's Reference.

See Also

ACTIONS


HrCopyRestriction

The HrCopyRestriction function creates a copy of a MAPI SRestriction structure.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrCopyRestriction(
  LPSRestriction lpResSrc,
  LPVOID lpObject,
  LPSRestriction FAR * lppResDest
);

Parameters

lpResSrc
Input parameter. Points to the SRestriction structure to be copied.
lpObject
Input parameter. Points to an existing MAPI buffer allocated by the MAPI MAPIAllocateBuffer function, or NULL if the returned structure is to be allocated by HrCopySRestriction.
lppResDest
Output parameter. Points to a pointer to the copy of the restriction structure pointed to by lpResSrc.

Return Values

See Return Values.

Remarks

For information on the MAPIAllocateBuffer function and SRestriction structure, see the MAPI Programmer's Reference.

See Also

HrCopyActions


HrCreateDateTimeString

The HrCreateDateTimeString function creates a string containing the time from a MAPI FILETIME structure.

Quick Info

Header file: | MSGEMIT.H
Library: | MSGEMIT.LIB
Unicode: | Yes

HRESULT HrCreateDateTimeString(
  LPFILETIME lpFileTime
  LPSTR * lppTimeString
);

Parameters

lpFileTime
Input parameter. Points to the FILETIME structure containing the time.
lppTimeString
Output parameter. Points to a pointer to the string buffer where the converted time is stored.

Return Values

See Return Values.

Remarks

For more information on the FILETIME structure, see the MAPI Programmer's Reference.


HrCreateDirEntryId

The HrCreateDirEntryId function creates a directory entry identifier for a MAPI object.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrCreateDirEntryId(
  LPSTR lpszAddress,
  ULONG *lpcbeid,
  LPENTRYID *lppeid
);

Parameters

lpszAddress
Input parameter. Points to the address of the entry identifier.
lpcbeid
Output parameter. Points to the number of bytes in the entry identifier.
lppeid
Output parameter. Points to a pointer to the MAPI ENTRYID structure containing an entry identifier.

Return Values

See Return Values.

Remarks

For information on the ENTRYID structure, see the MAPI Programmer's Reference.

See Also

HrCreateDirEntryIdEx


HrCreateDirEntryIdEx

The HrCreateDirEntryIdEx function creates an directory identifier for a MAPI object, given the address of the object in the directory.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrCreateDirEntryIdEx(
  LPADRBOOK lpAdrBook,
  LPSTR lpszDN,
  ULONG * lpcbEntryID,
  LPENTRYID *lppEntryID
);

Parameters

lpAdrBook
Input parameter. Points to a MAPI IAddrBook interface containing the address book (directory) in which to look.
lpszDN
Input parameter. Points to the distinguished name (DN) of the object.
lpcbEntryID
Output parameter. Points to the number of bytes in the entry identifier.
lppEntryID
Output parameter. Points to a pointer to the MAPI ENTRYID structure containing an entry identifier.

Return Values

See Return Values.

Remarks

For more information on the HrCreateDirEntryIdEx function, see Using MAPI with Directory Objects.

For information on the ENTRYID structure and IAddrBook interface, see the MAPI Programmer's Reference.

See Also

HrCreateDirEntryId


HrCreateGatewayProfile

The HrCreateGatewayProfile function installs a MAPI profile for a gateway.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrCreateGatewayProfile(
  LPSTR lpszServiceName,
  LPSTR lpszProfileName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lpszProfileName
Input parameter. Points to a null-terminated string containing the name of the profile.

Return Values

See Return Values.

Remarks

You should be aware that a service does not require administrator privileges unless it is doing something that specifically requires those privileges.

See Also

HrMAPIProfileExists, HrRemoveProfile


HrCreateMailboxAgentProfile

The HrCreateMailboxAgentProfile function creates a MAPI profile for a mailbox agent.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrCreateMailboxAgentProfile(
  LPSTR lpszServiceName,
  LPSTR lpszProfileName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lpszProfileName
Input parameter. Points to a null-terminated string containing the name of the profile.

Return Values

See Return Values.

Remarks

You can determine whether a mailbox agent exists with a call to the HrMailboxAgentExists function. In addition, you can remove an existing mailbox agent with a call to HrRemoveMailboxAgent.

See Also

HrMailboxAgentExists, HrRemoveMailboxAgent


HrCreatePersonalStore

The HrCreatePersonalStore function creates a personal folder (PST) with properties determined by the input parameters in a temporary profile.

Quick Info

Header file: | NEWPST.H
Library: | NEWPST.LIB

HRESULT HrCreatePersonalStore(
  LPSTR lpszPSTPath,
  DWORD dwEncryption,
  LPSTR lpszPSTDisplayName,
  LPSTR lpszPSTPassword,
  LPSTR * lppszProfileName,
  LPSTR * lppszProfilePassword
);

Parameters

lpszPSTPath
Input parameter. Points to the full distinguished name (DN) of the PST. This value is assigned to the PR_PST_PATH property.
dwEncryption
Input parameter. Specifies the encryption method. This value is assigned to the PR_PST_ENCRYPTION property.
lpszPSTDisplayName
Input parameter. Points to the value of the MAPI PR_DISPLAY_NAME property for the new PST.
lpszPSTPassword
Input parameter. Points to the PST password. This value is assigned to the PR_PST_PW_SZ_NEW property. This value cannot be NULL.
lppszProfileName
Output parameter. Points to a pointer to the temporary profile name. This value may be used to establish a MAPI session.
lppszProfilePassword
Output parameter. Points to a pointer the temporary profile password. This may be used to establish a MAPI session.

Return Values

See Return Values.

Remarks

The name and password of the temporary PST are returned to the user in lppszProfileName and lppszProfilePassword, respectively.

Do not make successive calls to HrCreatePersonalStore without intervening calls to HrCleanupPSTGlobals. Since Microsoft Exchange Server uses internal static storage for objects and profile strings, you should only create and use one new PST at a time.

See Also

HrCleanupPSTGlobals


HrDRAddToDeliveredRecipList

The HrDRAddToDeliveredRecipList function adds a recipient entry to the delivered recipient list.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrDRAddToDeliveredRecipList(
  ULONG cDeliveredProps,
  LPSPropValue lpDeliveredProps,
  LPADRLIST * lppAdrList
);

Parameters

cDeliveredProps
Input parameter. Specifies the number of properties in lpDeliveredProps.
lpDeliveredProps
Input parameter. Points to a MAPI SPropValue structure containing the delivered properties.
lppAdrList
Input/output parameter. Points to a pointer to the delivered recipient address list.

Return Values

See Return Values.

Remarks

You must call the HrDRCreateDeliveredRecipList function to create the initial, empty delivered recipient list for the lppAdrList parameter.

You must call the HrDRGetDeliveredRecip function to create each recipient entry and to get the values for the cDeliveredProps and lpDeliveredProps parameters.

For information on the SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrDRCreateDeliveredRecipList, HrDRGetDeliveredRecip


HrDRCreate

The HrDRCreate function creates a delivery report for a message.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrDRCreate(
  LPADRBOOK lpAdrBook,
  LPMAPIFOLDER lpFolder,
  LPMESSAGE lpMessage,
  LPADRLIST lpAdrList,
  ULONG cProps,
  LPSPropValue lpProps,
  LPMESSAGE lppReport
);

Parameters

lpAdrBook
Input parameter. Points to a MAPI IAddrBook interface containing the address book.
lpFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the folder where the message ended up.
lpMessage
Input parameter. Points to a MAPI IMessage interface containing the message about which the delivery report is made.
lpAdrList
Input parameter. Points to a MAPI ADRLIST structure containing the delivered recipient address list.
cProps
Input parameter. Specifies the number of properties in the lpProps parameter.
lpProps
Input parameter. Points to a MAPI SPropValue structure containing the message properties.
lppReport
Output parameter. Points to a pointer to the MAPI IMessage interface containing the delivery report.

Return Values

See Return Values.

Remarks

Use the HrDRGetProps function to retrieve the delivery report properties for both the lpProps and cProps parameters.

For information on the ADRLIST structure, IAddrBook interface, IMAPIFolder interface, IMessage interface and SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrDRGetProps


HrDRCreateDeliveredRecipList

The HrDRCreateDeliveredRecipList function creates an empty delivered recipient list.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrDRCreateDeliveredRecipList(
  LPADRLIST * lppAdrList
);

Parameters

lppAdrList
Output parameter. Points to a pointer to the MAPI ADRLIST structure that creates the empty delivered recipient list.

Return Values

See Return Values.

Remarks

The HrDRCreateDeliveredRecipList function prepares an empty delivered recipient list that you can fill in with entries that you first create with a call to HrDRGetDeliveredRecip and then add to the list with a call to HrDRAddToDeliveredRecipList.

For information on the ADRLIST structure, see the MAPI Programmer's Reference.

See Also

HrDRAddToDeliveredRecipList, HrDRGetDeliveredRecip


HrDRGetDeliveredRecip

The HrDRGetDeliveredRecip function creates a delivered recipient list entry.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrDRGetDeliveredRecip(
  LPADRENTRY lpAdrEntry,
  ULONG cExtraProps,
  LPSPropValue lpExtraProps,
  ULONG * lpcDeliveredProps,
  LPSPropValue * lppDeliveredProps
);

Parameters

lpAdrEntry
Input parameter. Points to a MAPI ADRENTRY structure containing the address entry for which you are creating the delivered recipient address list entry.
cExtraProps
Input parameter. Specifies the number of extra properties in lpExtraProps.
lpExtraProps
Input parameter. Points to an array of MAPI SPropValue structures containing the extra properties.
lpcDeliveredProps
Output parameter. Points to the number of delivered properties in lppDeliveredProps.
lppDeliveredProps
Output parameter. Points to a pointer to an array of SPropValue structures containing the delivered properties.

Return Values

See Return Values.

Remarks

Use the HrDRAddToDeliveredRecipList function to add this entry to the existing delivered recipient list.

For information on the ADRENTRY and SPropValue structures, see the MAPI Programmer's Reference.

See Also

HrDRAddToDeliveredRecipList


HrDRGetProps

The HrDRGetProps function retrieves the delivery report properties from the original message.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrDRGetProps(
  LPMESSAGE lpMessage,
  ULONG * lpcProps,
  LPSPropValue * lppProps
);

Parameters

lpMessage
Input parameter. Points to a MAPI IMessage interface containing the original message.
lpcProps
Output parameter. Points to the number of properties in the lppProps parameter.
lppProps
Output parameter. Points to a pointer to the MAPI SPropValue array containing the delivery report properties.

Return Values

See Return Values.

Remarks

For more information on the IMessage interface and the SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrDRCreate


HrEDKDecodeBinaryStreamDataToStream

The HrEDKDecodeBinaryStreamDataToStream function reads attachment hexadecimal encoding from input stream to attachment.

Quick Info

Header file: | MSGEMIT.H
Library: | MSGEMIT.LIB

HRESULT HrEDKDecodeBinaryStreamDataToStream(
  LPSTREAM lpStreamIn,
  ULONG cb,
  LPSTREAM lpStreamOut
);

Parameters

lpStreamIn
Input parameter. Points to the input stream.
cb
Input parameter. Specifies the number of bytes in the original binary data.
lpStreamOut
Input parameter. Points to an open Win32 IStream interface containing the output stream.

Return Values

See Return Values.

Remarks

For information on the Istream interface, see the "COM and ActiveX Object Services" section in the Microsoft Platform SDK.

See Also

HrEDKEncodeBinaryStreamDataToStream


HrEDKEncodeBinaryStreamDataToStream

The HrEDKEncodeBinaryStreamDataToStream function copies binary data from an input stream or specified output stream.

Quick Info

Header file: | MSGEMIT.H
Library: | MSGEMIT.LIB

HRESULT HrEDKEncodeBinaryStreamDataToStream(
  LPSTREAM lpStreamIn,
  LPSTREAM lpStreamOut
);

Parameters

lpStreamIn
Input parameter. Points to an open Win32 IStream interface containing the input stream.
lpStreamOut
Input parameter. Points to an open Win32 IStream interface containing the output stream.

Return Values

See Return Values.

Remarks

The HrEDKEncodeBinaryStreamDataToStream function encodes each byte as a two-character hexadecimal ASCII-representation of the byte.

For information on the Istream interface, see the "COM and ActiveX Object Services" section in the Microsoft Platform SDK.

See Also

HrEDKDecodeBinaryStreamDataToStream


HrEDKParseSubjectPrefix

The HrEDKParseSubjectPrefix function breaks a subject into its prefix component and its original subject component.

Quick Info

Header file: | MSGEMIT.H
Library: | MSGEMIT.LIB

HRESULT HrEDKParseSubjectPrefix(
  LPTSTR pszSubject,
  LPTSTR * ppszPrefix,
  LPTSTR * ppszOrigSub
);

Parameters

pszSubject
Input parameter. Points to the subject text.
ppszPrefix
Output parameter. Points to a pointer to the subject prefix.
ppszOrigSub
Output parameter. Points to a pointer to the original subject text.

Return Values

See Return Values.

Remarks

The prefix includes everything up to and including the first colon and the first space after the colon (if any).


HrEnumContainers

The HrEnumContainers function lists the names of the containers on the server.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrEnumContainers(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  BOOL fSubtree,
  LPSTR * lppszContainers
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site.
fSubtree
Input parameter. Determines whether to enumerate the names of any child containers:
TRUE
Name any subcontainers.
FALSE
Do not name any subcontainers.
lppszContainers
Output parameter. Points to a pointer to an array of strings (terminated by a NULL entry) containing the names of the containers.

Return Values

See Return Values.

See Also

HrEnumOrganizations, HrEnumSites


HrEnumOrganizations

The HrEnumOrganizations function lists the names of the organizations on the server.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrEnumOrganizations(
  LPSTR lpszRootDN,
  LPSTR lpszServer,
  LPSTR * lppszOrganizations
);

Parameters

lpszRootDN
Input parameter. Points to a null-terminated string containing the distinguished name (DN) of the directory information tree (DIT) root.
lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lppszOrganizations
Output parameter. Points to a pointer to an array of strings (terminated by a NULL entry) containing the names of the organizations in this DIT.

Return Values

See Return Values.

See Also

HrEnumContainers, HrEnumSites


HrEnumProductServices

The HrEnumProductServices function lists the services for a product.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrEnumProductServices(
  LPSTR lpszProductGuid,
  LPSTR * lppszServices,
  LPSTR * lppszDisplayNames
);

Parameters

lpszProductGuid
Input parameter. Points to a null-terminated string containing the product GUID.
lppszServices
Output parameter. Points to a pointer to an array of strings (terminated by a NULL entry) containing the names of the services.
lppszDisplayNames
Output parameter. Points to a pointer to an array of strings (terminated by a NULL entry) containing the display names of the services.

Return Values

See Return Values.

See Also

HrInstallService


HrEnumSiteAdmins

The HrEnumSiteAdmins function lists the administrators for a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrEnumSiteAdmins(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR * lppszAdmins
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site.
lppszAdmins
Output parameter. Points to a pointer to an array of strings (terminated by a NULL entry) containing the administrators for the site.

Return Values

See Return Values.

See Also

HrEnumSites


HrEnumSites

The HrEnumSites function lists all of the sites in an organization.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrEnumSites(
  LPSTR lpszServer,
  LPSTR lpszOrganizationDN,
  LPSTR * lppszSites
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszOrganizationDN
Input parameter. Points to a null-terminated string containing the distinguished name of the organization.
lppszSites
Output parameter. Points to a pointer to an array of strings (terminated by a NULL entry) containing the sites within the organization.

Return Values

See Return Values.

Remarks

The HrEnumSites function lists all of the sites in an organization, not just the sites to which the server belongs.

See Also

HrEnumOrganizations, HrEnumSiteAdmins


HrEventCloseLog

The HrEventCloseLog function shuts down event logging for the Microsoft Exchange Server application.

Quick Info

Header file: | EDKEVENT.H
Library: | EDKEVENT.LIB

HRESULT HrEventCloseLog(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

Use the HrEventOpenLog function to initialize event logging for a Microsoft Exchange Server application.

See Also

HrEventOpenLog


HrEventGetCounts

The HrEventGetCounts function retrieves the number of events logged by the current program.

Quick Info

Header file: | EDKEVENT.H
Library: | EDKEVENT.LIB

HRESULT HrEventGetCounts(
  LPEDKEVENTCOUNT lpsEventCount
);

Parameters

lpsEventCount
Output parameter. Points to the EDKEVENTCOUNT structure containing a count of events.

Return Values

See Return Values.

Remarks

The Error, Warning, and Information events retrieved by the HrEventGetCounts function are logged thru the EventLogMsg function.

See Also

EventLogMsg


HrEventGetHandle

The HrEventGetHandle function obtains an event handle for the current executable file.

Quick Info

Header file: | EDKEVENT.H
Library: | EDKEVENT.LIB

HRESULT HrEventGetHandle(
  HANDLE phEventLog
);

Parameters

phEventLog
Input parameter. Points to the handle of the Windows NT application event log.

Return Values

See Return Values.

Remarks

The event handle returned will be NULL if there is no open event log. DLLs may not call the HrEventGetHandle function to retrieve the event handle which their parent executable set. If the parent executable sets an event handle, then it must pass the event handle to the DLL.

See Also

HrMAPIGetPropBinary, HrMAPIGetPropBoolean, HrMAPIGetPropString, HrMAPIGetPropSystime


HrEventOpenLog

The HrEventOpenLog function initializes event logging for a Microsoft Exchange Server application.

Quick Info

Header file: | EDKEVENT.H
Library: | EDKEVENT.LIB

HRESULT HrEventOpenLog(
  LPTSTR pszApplicationName,
  LPTSTR pszExecutableName,
  LPTSTR pszEventMessageFile,
  LPTSTR pszParameterMessageFile,
  LPTSTR pszCategoryMessageFile,
  LPHANDLE phEventSourceOut
);

Parameters

pszApplicationName
Input parameter. Points to the name of this application.
pszExecutableName
Input parameter. Points to the name of the executable file.
pszEventMessageFile
Input parameter. Points to the name of the event message file.
pszParameterMessageFile
Input parameter. Points to the name of the parameter message file.
pszCategoryMessageFile
Input parameter. Points to the name of the category message file.
phEventSourceOut
Output parameter. Points to an event logging handle.

Return Values

See Return Values.

Remarks

Use the HrEventCloseLog function to shut down event logging for the Microsoft Exchange Server application.

See Also

HrCfgPackData, HrCfgUnpackData


HrEventUseExisting

The HrEventUseExisting function initializes event logging for a Microsoft Exchange Server application by connecting to an already open event log handle.

Quick Info

Header file: | EDKEVENT H
Library: | EDKEVENT.LIB

HRESULT HrEventUseExisting(
  HANDLE hExistingEventSource
);

Parameters

hExistingEventSource
Input parameter. Specifies the handle of an open event log.

Return Values

See Return Values.

Remarks

Connecting to an already open event log handle allows EventLogMsg to log events to a handle that was opened elsewhere. Calling HrEventCloseLog after calling this routine will do an internal cleanup, but will not close the event log handle. An example of where this routine is useful is within a DLL that is called by code in which event logging has already been initialized.

See Also

HrEventOpenLog


HrFileTimeToSeconds

The HrFileTimeToSeconds function converts computer time units to seconds.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrFileTimeToSeconds(
  FILETIME * pft,
  DWORD * pdwSec
);

Parameters

pft
Input parameter. Points to a time duration measured in MAPI FILETIME type units.
pdwSec
Output parameter. Points to the same time duration measured in seconds.

Return Values

See Return Values.

Remarks

The HrFileTimeToSeconds function converts a time-duration measurement from FILETIME type into seconds. It can be used whenever a result expressed as a FILETIME type needs to be reported to the end user.

For more information on this function, see Jump Window Functions in the Gateway Programmer's Reference.

For information on the FILETIME structure, see the MAPI Programmer's Reference.

See Also

HrJSCollectDataPoint, HrJSGetValue, HrJSOpen, JSClose


HrFindExchangeGlobalAddressList

THe HrFindExchangeGlobalAddressList function retrieves the entry identifier of the global address list (GAL) container in the address book.

Quick Info

Header file: | ADDRLKUP.H
Library: | ADDRLKUP.LIB

HRESULT HrFindExchangeGlobalAddressList(
  LPADRBOOK lpAdrBook,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpAdrBook
Input parameter. Points to a MAPI IAddrBook interface containing the address book.
lpcbeid
Output parameter. Points to the count of bytes in the entry identifier.
lppeid
Output parameter. Points to a pointer to the address where the entry identifier is stored.

Return Values

See Return Values.

Remarks

For more information on the HrFindExchangeGlobalAddressList function, see Finding the Global Address List.

For information on the IAddrBook interface, see the MAPI Programmer's Reference.

See Also

GetAdrBookPtr


HrFindExchangePublicStore

The HrFindExchangePublicStore function retrieves the root folder of a public information store.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrFindExchangePublicStore(
  LPMDB lpMdb,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the message store.
lpcbeid
Output parameter. Points to the count of bytes in the entry identifier of the public store.
lppeid
Output parameter. Points to a pointer to the entry identifier of the public store.

Return Values

See Return Values.

Remarks

For more information on the HrFindExchangePublicStore function, see Working with Public Folders.

For information on the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

FIsPublicStore


HrFolderACLsOpen

The HrFolderACLsOpen function retrieves a pointer to an object that implements the IExchangeFolderACLs interface.

Quick Info

Header file: | ACLCLS.H
Library: | ACLCLS.LIB
Unicode: |

HRESULT HrFolderACLsOpen(
  LPMDB lpMDB,
  ULONG cbentryid,
  LPENTRYID lpentryid,
  LPFOLDERACLS FAR * lppFolderACLs
);

Parameters

lpMDB
Input parameter. Points to a MAPI IMsgStore interface containing the information store with the target folder.
cbentryid
Input parameter. Specifies the number of bytes in lpentryid.
lpentryid
Input parameter. Points to the entry identifier of the folder whose access control list (ACL) will be accessed.
lppFolderACLs
Output parameter. Points to a pointer to the IExchangeFolderACLs interface for the ACL. Returns NULL, if none.

Return Values

See Return Values. In addition, HrFolderACLsOpen can return the following value:

E_NOINTERFACE
The ACL table does not exist.

Remarks

The methods of the IExchangeFolderACLs interface returned by the HrEventOpenLog function can be used to manipulate the ACL on the folder. You can obtain the entry identifier for lpentryid with either the HrMAPIFindFolderEx function (for public information store folders) or the IMsgStore::GetReceiveFolder method (for a user's Inbox folder).

For more information on this function, see Manipulating ACLs.

For information on the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrEventOpenLog, HrMAPIFindFolderEx


HrFolderRulesGetProviders

The HrFolderRulesGetProviders function retrieves the list of rules providers for the specified folder.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrFolderRulesGetProviders(
  LPMDB lpMDB,
  ULONG cbentryid,
  LPENTRYID lpentryid,
  LPULONG lpcProviders,
  LPSTR FAR * FAR * lpppszProviders
);

Parameters

lpMDB
Input parameter. Points to a MAPI IMsgStore interface containing the information store with the folder.
cbentryid
Input parameter. Specifies the number of bytes in the entry identifier (lpentryid) for the folder.
lpentryid
Input parameter. Points to an ENTRYID structure containing the entry identifier for the folder.
lpcProviders
Output parameter. Points to the number of providers in the list where lpppszProviders points.
lpppszProviders
Output parameter. Points to a pointer that points to a pointer to an array of providers.

Return Values

See Return Values. In addition, HrFolderRulesGetProviders can return the following value:

E_NOINTERFACE
No rules table exists for this folder.

Remarks

For information on the ENTRYID structure and the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrFolderRulesOpen


HrFolderRulesOpen

The HrFolderRulesOpen function gets a pointer to an IExchangeFolderRules interface object.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrFolderRulesOpen(
  LPMDB lpMDB,
  ULONG cbentryid,
  LPENTRYID lpentryid,
  LPSTR lpszProvider,
  LPFOLDERRULES FAR * lppFolderRules
);

Parameters

lpMDB
Input parameter. Points to a MAPI IMsgStore interface containing the message store with the folder.
cbentryid
Input parameter. Specifies the number of bytes in the folder's entry identifier pointed to by lpentryid.
lpentryid
Input parameter. Points to an ENTRYID structure containing the folder's entry identifier.
lpszProvider
Input Parameter. Points to a STRING8 containing the name of the provider for the requested rules.
lppFolderRules
Output parameter. Points to a pointer to an IExchangeFolderRules interface object.

Return Values

See Return Values. In addition, HrFolderRulesOpen can return the following value:

E_NOINTERFACE
The rules table does not exist on the folder.

Remarks

Because more than one provider can have rules on a folder, use the IExchangeFolderRules interface to access the rules associated with a specific provider. For more information on HrFolderRulesOpen function, see Working with Rules.

For information on the ENTRYID structure and the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrFolderRulesGetProviders


HrGatewayExists

The HrGatewayExists function determines whether a gateway exists at a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGatewayExists(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name (DN) of the site.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the site.

Return Values

See Return Values.

See Also

HrInstallGateway, HrRemoveGateway


HrGetAddressTypeVersion

The HrGetAddressTypeVersion function obtains the version of an Addr-Type object in a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetAddressTypeVersion(
  LPTSTR lpszServer,
  LPTSTR lpszSiteDN,
  LPTSTR lpszCommonName,
  LPTSTR lpszMachineType,
  DWORD * lpdwFileVersionMS,
  DWORD * lpdwFileVersionLS
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name (DN) of the site.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the site.
lpszMachineType
Input parameter. Points to a null-terminated string containing the type of computer, such as i386.
lpdwFileVersionMS
Output parameter. Points to the high-order 32 bits of the file version.
lpdwFileVersionLS
Output parameter. Points to the low-order 32 bits of the file version.

Return Values

See Return Values.

Remarks

For more information on the HrGetAddressTypeVersion function, see Addr-Type Object in the Gateway Programmer's Reference.

See Also

HrAddressTypeExists, HrInstallAddressType, HrRemoveAddressType


HrGetAdminExtensionVersion

The HrGetAdminExtensionVersion function returns the file version information contained in an Admin-Extension object.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetAdminExtensionVersion(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName,
  LPSTR lpszMachineType,
  DWORD * lpdwFileVersionMS,
  DWORD * lpdwFileVersionLS
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the site.
lpszMachineType
Input parameter. Points to a null-terminated string containing the computer type, such as i386.
lpdwFileVersionMS
Output parameter. Points to the high-order 32 bits of the file version.
lpdwFileVersionLS
Output parameter. Points to the low-order 32 bits of the file version.

Return Values

See Return Values.

Remarks

For more information on the HrGetAdminExtensionVersion function, see Installing an Admin-Extension Object.

See Also

HrAdminExtensionExists, HrInstallAdminExtension, HrRemoveAdminExtension


HrGetExchangeStatus

The HrGetExchangeStatus function obtains the current state of the server on a computer.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrGetExchangeStatus(
  LPTSTR lpszMachineName,
  DWORD *lpdwService,
  DWORD *lpdwCurrentState
);

Parameters

lpszMachineName
Input parameter. Points to the computer name.
lpdwService
Output parameter. Points to the service on the computer.
lpdwCurrentState
Output parameter. Points to the current state of the server.

Return Values

See Return Values.

See Also

FServiceReportStatus


HrGetFileVersionInfo

The HrGetFileVersionInfo function retrieves the version information on a file.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrGetFileVersionInfo(
  LPSTR lpszFileName,
  LPVOID * lppVersionInfo
);

Parameters

lpszFileName
Input parameter. Points to the name of the file.
lppVersionInfo
Output parameter. Points to a pointer to the file version information.

Return Values

See Return Values.

Remarks

For more information on the HrGetFileVersionInfo function, see Installing an Admin-Extension Object.

See Also

HrAdminExtensionExists, HrGetAdminExtensionVersion


HrGetFolderMetrics

The HrGetFolderMetrics function retrieves folder statistics.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrGetFolderMetrics(
  HFLDMTRC hFolderMetric,
  FILETIME * pftNow,
  DWORD fMetric,
  DWORD * pcMessages,
  FILETIME * pftLongestWait,
  FILETIME * pftTotalWait
);

Parameters

hFolderMetric
Input parameter. Specifies the handle to the calculations for this folder.
pftNow
Input parameter. Points to the current time.
fMetric
Input parameter. Specifies the calculations to make:
FM_CMESSAGES
Returns a value in pcMessages.
FM_LONGEST_WAIT
Returns a value in pftLongestWait.
FM_TOTAL_WAIT
Returns a value in pftTotalWait.
pcMessages
Output parameter. Points to the number of messages in the folder (calculated if FM_CMESSAGES is specified in fMetric).
pftLongestWait
Output parameter. Points to the duration of the longest wait in the current message list (calculated if FM_LONGEST_WAIT is specified in fMetric).
pftTotalWait
Output parameter. Points to the total of the wait durations of all messages in the folder (calculated if FM_TOTAL_WAIT is specified in fMetric).

Return Values

See Return Values.

Remarks

Three statistics are available:

  • Number of messages in the folder.
  • Duration of wait for the message that has been in the folder for the longest period of time.
  • Total wait duration for all messages in the folder.

One, two, or all three calculations can be requested in the same call.

The statistics require different amounts of overhead to calculate. Calculating the number of messages in a folder is the least expensive statistic. Calculating the total of the wait durations is the most expensive. To optimize performance, request only the statistics you need.

All parameters in the call are mandatory, even if fewer than three calculations are requested. For example, if you do not request the number of messages calculation, you must still provide a value for pcMessages.

For more information on this function, see Folder Snapshot Functions in the Gateway Programmer's Reference.

See Also

CloseFolderMetrics, HrOpenFolderMetrics


HrGetMailboxDN

The HrGetMailboxDN function retrieves the distinguished names (DNs) for a server and mailbox.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrGetMailboxDN(
  LPSTR pszServer,
  LPSTR pszMailbox,
  LPSTR * ppszServerDN,
  LPSTR * ppszMailboxDN
);

Parameters

pszServer
Input parameter. Points to the name of the server.
pszMailbox
Input parameter. Points to the name of the mailbox.
ppszServerDN
Output parameter. Points to a pointer to the distinguished name (DN) of the server.
ppszMailboxDN
Output parameter. Points to a pointer to the DN of the mailbox.

Return Values

See Return Values.

Remarks

The completed output strings appears as follows:

/O=Organization/OU=Site/CN=Servers/CN=ServerName/CN=NULL
/O=Organization/OU=Site/CN=Recipients/CN=MailboxName

For more information on distinguished names (DNs), see Using MAPI with Directory Objects and Viewing the Contents of Mailboxes with MBLSAMPL.

See Also

HrGetServiceSiteDN


HrGetProgManGroups

The HrGetProgManGroups function obtains the names of the program groups.

Quick Info

Header file: | EDKSETUP.H
Library: | EDKSETUP.LIB

HRESULT HrGetProgManGroups(
  LPDWORD lpIdInst,
  LPSTR * lppszGroups
);

Parameters

lpIdInst
Input parameter. Points to the instance identifier of the names of the program group.
lpszGroups
Input parameter. Points to the group's string address variable.

Return Values

See Return Values.


HrGetPropTagName

The HrGetPropTagName function obtains the property tag name string of a property tag value.

Quick Info

Header file: | PROPTAG.H
Library: | PROPTAG.LIB

HRESULT HrGetPropTagName(
  ULONG ulPropTag,
  LPSTR FAR * lppszPropName
);

Parameters

ulPropTag
Input parameter. Property tag value.
lppszPropName
Output parameter. Points to the address of the returned property-tag name string upon success. If the value is not found in the property-tag string table, a string of one of the following formats is returned:
PT_STRING8
"[S " <HexNumber> "]"
PT_LONG
"[N " <HexNumber> "]"
All others
"[" <HexNumber> "]"

Return Values

See Return Values.

Remarks

Use the MAPIFreeBuffer function to free lppszPropName. For information on the MAPIFreeBuffer function, see the MAPI Programmer's Reference.

See Also

HrGetPropTagValue


HrGetPropTagValue

The HrGetPropTagValue function obtains the property-tag value for a property-tag name string.

Quick Info

Header file: | PROPTAG.H
Library: | PROPTAG.LIB

HRESULT HrGetPropTagValue(
  LPSTR lpszPropName,
  ULONG * pulPropTag
);

Parameters

lpszPropName
Input parameter. Points to the property-tag name string.
pulPropTag
Output parameter. Points to a ULONG that is set to the returned property-tag value upon success.

Return Values

See Return Values.

See Also

HrGetPropTagName


HrGetRecipientList

The HrGetRecipientList function obtains the selected columns from a MAPI recipient table.

Quick Info

Header file: | MSGEMIT.H
Library: | MSGEMIT.LIB

HRESULT HrGetRecipientList(
  LPMESSAGE lpMessage,
  LPSPropTagArray lpPropTags,
  LPSRowSet * lppRows
);

Parameters

lpMessage
Input parameter. Points to a MAPI IMessage interface containing the message.
lpPropTags
Input parameter. Points to the list of columns (properties) to retrieve.
lppRows
Output parameter. Points to the array of rows returned.

Return Values

See Return Values.

Remarks

To release memory that you have allocated for a MAPI SRowSet structure, use the MAPI FreeProws function. If you use the MAPIFreeBuffer function, your application will leak memory.

For information on the FreeProws function, MAPIFreeBuffer function, and IMessage interface, see the MAPI Programmer's Reference.


HrGetServiceAccountName

The HrGetServiceAccountName function obtains the account name for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceAccountName(
  LPSTR lpszServiceName,
  LPSTR * lppszAccountName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszAccountName
Output parameter. Points to the address of a null-terminated string containing the Windows NT user name of the person who administers the service.

The account name has the following format:

DomainName\UserName

If the returned value is .\UserName, the account belongs to the built-in domain. If the returned value is NULL, the service is logged in under the LocalSystem account.

Return Values

See Return Values.

See Also

HrGetServiceCommonName, HrGetServiceDisplayName, HrGetServiceExecutableName, HrGetServiceObjectGUID, HrGetServiceProductGUID, HrGetServiceServerName, HrGetServiceSiteDN


HrGetServiceCommonName

The HrGetServiceCommonName function obtains the common name of the object for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceCommonName(
  LPTSTR lpszServiceName,
  LPTSTR * lppszCommonName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszCommonName
Output parameter. Points to the address of a null-terminated string containing the relative distinguished name (RDN) of the object where the service is running.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceDisplayName, HrGetServiceExecutableName, HrGetServiceObjectGUID, HrGetServiceProductGUID, HrGetServiceServerName, HrGetServiceSiteDN


HrGetServiceDisplayName

The HrGetServiceDisplayName function obtains the display name for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceDisplayName(
  LPTSTR lpszServiceName,
  LPTSTR * lppszDisplayName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszDisplayName
Output parameter. Points to the address of a null-terminated string containing the name that the Microsoft Exchange Server Administrator program displays for the service.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceCommonName, HrGetServiceExecutableName, HrGetServiceObjectGUID, HrGetServiceProductGUID, HrGetServiceServerName, HrGetServiceSiteDN


HrGetServiceExecutableName

The HrGetServiceExecutableName function obtains the executable name for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceExecutableName(
  LPTSTR lpszServiceName,
  LPTSTR * lppszExecutableName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszExecutableName
Output parameter. Points to the address of a null-terminated string containing the fully distinguished path to the file containing the executable program for the service.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceCommonName, HrGetServiceDisplayName, HrGetServiceObjectGUID, HrGetServiceProductGUID, HrGetServiceServerName, HrGetServiceSiteDN


HrGetServiceObjectGUID

The HrGetServiceObjectGUID function obtains the object GUID for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceObjectGUID(
  LPTSTR lpszServiceName,
  LPTSTR * lppszObjectGUID
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszObjectGUID
Output parameter. Points to the address of a null-terminated string containing the GUID of the object where the service is running.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceCommonName, HrGetServiceDisplayName, HrGetServiceExecutableName, HrGetServiceProductGUID, HrGetServiceServerName, HrGetServiceSiteDN


HrGetServiceProductGUID

The HrGetServiceProductGUID function obtains the product GUID for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceProductGUID(
  LPSTR lpszServiceName,
  LPSTR * lppszProductGUID
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszProductGUID
Output parameter. Points to the address of a null-terminated string containing the GUID of the product where the service is running.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceCommonName, HrGetServiceDisplayName, HrGetServiceExecutableName, HrGetServiceObjectGUID, HrGetServiceServerName, HrGetServiceSiteDN


HrGetServiceServerName

The HrGetServiceServerName function obtains the server name for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceServerName(
  LPSTR lpszServiceName,
  LPSTR * lppszServerName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszServerName
Output parameter. Points to the address of a null-terminated string containing the name of the server where the service is running.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceCommonName, HrGetServiceDisplayName, HrGetServiceExecutableName, HrGetServiceObjectGUID, HrGetServiceProductGUID, HrGetServiceSiteDN


HrGetServiceSiteDN

The HrGetServiceSiteDN function obtains the site distinguished name (DN) of the Microsoft Exchange Server object for a service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrGetServiceSiteDN(
  LPSTR lpszServiceName,
  LPSTR * lppszSiteDN
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.
lppszSiteDN
Output parameter. Points to the address of a null-terminated string containing the distinguished name of the site where the service is running.

Return Values

See Return Values.

See Also

HrGetServiceAccountName, HrGetServiceCommonName, HrGetServiceDisplayName, HrGetServiceExecutableName, HrGetServiceObjectGUID, HrGetServiceProductGUID, HrGetServiceServerName


HrGetServiceStatus

The HrGetServiceStatus function obtains the current state of a service on a computer.

Quick Info

Header file: | EDKUTILS H
Library: | EDKUTILS.LIB

HRESULT HrGetServiceStatus(
  LPTSTR lpszMachineName,
  LPTSTR lpszServiceName,
  DWORD *lpdwCurrentState
);

Parameters

lpszMachineName
Input parameter. Specifies the computer name.
lpszServiceName
Input parameter. Specifies the service name.
lpdwCurrentState
Output parameter. Specifies the current state.

Return Values

See Return Values.


HrGWFindMtsInFolder

The HrGWFindMtsInFolder function retrieves the MTS-IN folder of a gateway object.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrGWFindMtsInFolder(
  LPMDB lpMdb,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the message store.
lpcbeid
Output parameter. Number of bytes in the entry identifier.
lppeid
Output parameter. Entry identifier of MTS-IN.

Return Values

See Return Values.

Remarks

When a gateway object is created in the Microsoft Exchange Server directory, a special mailbox is created in the information store, including two folders (MTS-IN and MTS-OUT) which are used as queues for incoming and outgoing messages. HrGWFindMtsInFolder returns the entry identifier of the MTS-IN folder when the mailbox of the gateway object is specified.

For information on the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrGWFindMtsOutFolder


HrGWFindMtsOutFolder

The HrGWFindMtsOutFolder function retrieves the MTS-OUT folder of a gateway object.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrGWFindMtsOutFolder(
  LPMDB lpMdb,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the message store.
lpcbeid
Output parameter. Number of bytes in the entry identifier.
lppeid
Output parameter. Entry identifier of MTS-OUT.

Return Values

See Return Values.

Remarks

When a gateway object is created in the Microsoft Exchange Server directory, a special mailbox is created in the information store, including two folders (MTS-IN and MTS-OUT) which are used as queues for incoming and outgoing messages. HrGWFindMtsOutFolder returns the entry identifier of the MTS-OUT folder when the mailbox of the gateway object is specified.

For information on the IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrGWFindMtsInFolder


HrGWLogoff

The HrGWLogoff function logs the user off the gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

HRESULT HrGWLogoff(
  VOID
);

Parameters

None.

Return Values

See Return Values.

See Also

HrGWLogon, GWMain


HrGWLogon

The HrGWLogon function logs the user on the gateway.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

HRESULT HrGWLogon(
  VOID
);

Parameters

None.

Return Values

See Return Values.

See Also

HrGWLogoff, GWMain


HrGWResolveAddress

The HrGWResolveAddress function determines the entry identifier from the address of a recipient.

Quick Info

Header file: | ADDRLKUP.H
Library: | ADDRLKUP.LIB
Unicode: | Yes

HRESULT HrGWResolveAddress(
  LPABCONT lpGalABCont,
  LPTSTR lpszAddress,
  BOOL * lpfMapiRecip,
  ULONG * lpcbEntryID,
  LPENTRYID * lppEntryID
);

Parameters

lpGalABCont
Input parameter. Points to a MAPI IABContainer interface containing the address book.
lpszAddress
Input parameter. Points to a proxy address.
lpfMapiRecip
Output parameter. Indicates whether a MAPI recipient has been added.
lpcbEntryID
Output parameter. Points to the count of bytes in the entry identifier.
lppEntryID
Output parameter. Points to the entry identifier.

Return Values

See Return Values.

Remarks

The HrGWResolveAddress function is called for each message recipient. It uses each recipient's physical address to look up their recipient entry identifier (PR_ENTRYID). For more information on this function, see Using the Address Lookup Functions, Implementing Address Lookup Functions, and Mapping Inbound Addresses in the Gateway Programmer's Reference.

For information on the IABContainer interface and the PR_ENTRYID property, see the MAPI Programmer's Reference.

See Also

HrGWResolveProxy


HrGWResolveProxy

The HrGWResolveProxy function determines the recipient proxy address of a specified type from an entry identifier.

Quick Info

Header file: | ADDRLKUP.H
Library: | ADDRLKUP.LIB
Unicode: | Yes

HRESULT HrGWResolveProxy(
  LPADRBOOK lpAdrBook,
  ULONG cbeid,
  LPENTRYID lpeid,
  LPTSTR lpszAddrType,
  LPTSTR * lppszAddress
);

Parameters

lpAdrBook
Input parameter. Points to a MAPI IAddrBook interface containing the address book where HrGWResolveProxy looks up the proxy address.
cbeid
Input parameter. Specifies the count of bytes in the entry identifier.
lpeid
Input parameter. Points to a MAPI ENTRYID structure containing the entry identifier that specifies the recipient.
lpszAddrType
Input parameter. Points to the proxy address type.
lppszAddress
Output parameter. Points to the address where the recipient proxy address is stored.

Return Values

See Return Values.

Remarks

Call the MAPIFreeBuffer function to free the buffer where lppszAddress points.

For more information on this function, see Using the Address Lookup Functions, Implementing Address Lookup Functions, and Mapping Inbound Addresses in the Gateway Programmer's Reference.

For information on the ENTRYID structure, IAddrBook interface, MAPIAllocateBuffer function, and MAPIFreeBuffer function, see the MAPI Programmer's Reference.

See Also

HrGWResolveAddress


HrGWStartNewFileHandler

The HrGWStartNewFileHandler function starts a thread to process new files.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB
Unicode: | Yes

HRESULT HrGWStartNewFileHandler(
  DWORD dwSubmitInterval,
  DWORD dwPollingInterval,
  DWORD cMessages,
  DWORD cThreads,
  LPCTSTR lpszAddrType,
  LPCTSTR lpszFileMask,
  LPCTSTR lpszPath,
  LPTHREAD_START_ROUTINE lpStartAddress
);

Parameters

dwSubmitInterval
Input parameter. Submit interval.
dwPollingInterval
Input parameter. Polling interval.
cMessages
Input parameter. Number of messages per thread.
cThreads
Input parameter. Number of threads.
lpszAddrType
Input parameter. Address type.
lpszFileMask
Input parameter. File mask.
lpszPath
Input parameter. Path.
lpStartAddress
Input parameter. Points to a THREAD_START_ROUTINE, which identifies the function that processes the new file.

Return Values

See Return Values.

See Also

FreeThreadParameter, HrGWStartNewMailHandler


HrGWStartNewMailHandler

The HrGWStartNewMailHandler function starts a thread to process new mail.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB
Unicode: | Yes

HRESULT HrGWStartNewMailHandler(
  DWORD dwSubmitInterval,
  DWORD dwPollingInterval,
  DWORD cMessages,
  DWORD cThreads,
  LPCTSTR lpszAddrType,
  LPCTSTR lpszPath,
  LPTHREAD_START_ROUTINE lpStartAddress
);

Parameters

dwSubmitInterval
Input parameter. Submit interval.
dwPollingInterval
Input parameter. Polling interval.
cMessages
Input parameter. Number of messages per thread.
cThreads
Input parameter. Number of threads.
lpszAddrType
Input parameter. Address type.
lpszPath
Input parameter. Path.
lpStartAddress
Input parameter. Points to a THREAD_START_ROUTINE structure that identifies the function that processes the new file.

Return Values

See Return Values.

Remarks

You must have at least one thread running for each address type that your gateway supports.

See Also

FreeThreadParameter, HrGWStartNewFileHandler


HrGWWaitForStop

The HrGWWaitForStop function waits for the gateway to stop.

Quick Info

Header file: | GWMAIN.H
Library: | GWMAIN.LIB

HRESULT HrGWWaitForStop(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

Use the HrGWWaitForStop function to begin shutting down a gateway. If this function completes successfully, you can then call the HrServiceConfirmStop function to ensure the gateway is no longer running as a service of Windows NT Server.

See Also

HrGWLogoff


HrIdentifyRegistryRootKey

The HrIdentifyRegistryRootKey function checks that a fully qualified key name begins with one of predefined Windows NT Registry keys.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrIdentifyRegistryRootKey(
  CHAR *pszKey,
  HKEY *phkKeyHandle,
  CHAR **ppszSubKey
);

Parameters

pszKey
Input parameter. Points to a fully qualified key name.
phkKeyHandle
Output parameter. Points to the key handle.
ppszSubKey
Output parameter. Points to a subkey section of pszKey.

Return Values

See Return Values.

Remarks

The HrIdentifyRegistryRootKey function checks for the following predefined Windows NT Registry keys: HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, and HKEY_USERS. The output from this function can be passed to Win32 registry functions such as RegOpenKeyEx.

Upon successful completion, hkKey is the Windows NT Registry key handle and ppszSubKey points to the remainder of the subkey string. The value returned in ppszSubKey is NULL when the user tries to access values in the root of one of the predefined Windows NT Registry keys.


HrInstallAddressTemplate

The HrInstallAddressTemplate function loads an address template into a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallAddressTemplate(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszDisplayName,
  LPSTR lpszCommonName,
  LPSTR lpszAddressSyntax,
  LPSTR lpszAddressType,
  LPSTR lpszPerMessageDDT,
  LPSTR lpszPerRecipientDDT,
  LPSTR lpszAddressEntryDDT,
  LPSTR lpszLanguage,
  LPSTR lpszHelpData16,
  LPSTR lpszHelpData32,
  LPSTR lpszHelpFile
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the server where the address template is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the distinguished name (DN) of the site where the address template is installed.
lpszDisplayName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the address template as displayed by the Microsoft Exchange Server Administrator program.

Although the Windows NT service control manager preserves the case of the name that is displayed, comparisons between display names are case-insensitive.

lpszCommonName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the relative distinguished name (RDN) of the address template object. Common names have the following format:

extension-name:hardware-platform

For example, suppose you have an address template called Net with an Extension-Name attribute of Net. If your platform is Intel, set lpszCommonName to Net:i386.

lpszAddressSyntax
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the file that generates the address syntax.
lpszAddressType
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the type of address that this template supports.
lpszPerMessageDDT
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the per-message dialog file.
lpszPerRecipientDDT
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the per-recipient dialog file.
lpszAddressEntryDDT
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the per-address entry dialog file.
lpszLanguage
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the language supported by the template.
lpszHelpData16
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full path to the file containing the binary Help information for 16-bit clients.
lpszHelpData32
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full path to the file containing the binary Help information for 32-bit clients.
lpszHelpFile
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full path to the client Help program.

Return Values

See Return Values.

See Also

HrAddressTemplateExists, HrRemoveAddressTemplate


HrInstallAddressType

The HrInstallAddressType function loads an address type object into a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallAddressType(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszDisplayName,
  LPSTR lpszServiceName,
  LPSTR lpszCommonName,
  DWORD dwFileVersionMS,
  DWORD dwFileVersionLS,
  LPSTR lpszProxyGenDLL,
  LPSTR lpszMachineType
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the server where the address type is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the distinguished name (DN) of the site where the address type is installed.
lpszDisplayName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the address type as displayed by the Microsoft Exchange Server Administrator program.

Although the Windows NT service control manager preserves the case of the name that is displayed, comparisons between display names are case-insensitive.

lpszServiceName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the address type which is installed. You cannot use either the forward slash (/) or back slash (\) character in a service name.
lpszCommonName
Input parameter. Points to a null-terminated string containing the relative distinguished name (RDN) of the address type object. Common names have the following format:

extension-name:hardware-platform

For example, suppose you have an address template called Net with an Extension-Name attribute of Net. If your platform is Intel, set lpszCommonName to Net:i386.

dwFileVersionMS
Input parameter. The high-order 32 bits of the file version number.
dwFileVersionLS
Input parameter. The low-order 32 bits of the file version number.
lpszProxyGenDLL
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full path to the proxy generation DLL file.
lpszMachineType
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the computer type such as i386.

Return Values

See Return Values.

See Also

HrAddressTypeExists, HrGetAddressTypeVersion, HrInstallGateway, HrRemoveAddressType


HrInstallAdminExtension

The HrInstallAdminExtension function loads an Admin-Extension object into a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallAdminExtension(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszDisplayName,
  LPSTR lpszCommonName,
  DWORD i,
  DWORD dwFileVersionLS,
  LPSTR lpszExtensionDLL,
  LPSTR lpszMachineType
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the server where the Admin-Extension object is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the distinguished name (DN) of the site where the Admin-Extension object is installed.
lpszDisplayName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the Admin-Extension object as displayed by the Microsoft Exchange Server Administrator program.

Although the Windows NT service control manager preserves the case of the name that is displayed, comparisons between display names are case-insensitive.

lpszCommonName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the relative distinguished name (RDN) of the Admin-Extension object. Common names have the following format:

extension-name:hardware-platform

For example, suppose you have an Admin-Extension object called MonNet with an Extension-Name attribute of MonNet. If your platform is Intel, set lpszCommonName to MonNet:i386.

dwFileVersionMS
Input parameter. The high-order 32 bits of the file version number.
dwFileVersionLS
Input parameter. The low-order 32 bits of the file version number.
lpszExtensionDLL
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the file name of the Administrator extension DLL.
lpszMachineType
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the computer type such as i386.

Return Values

See Return Values.

Remarks

For more information on this function, see Installing the Administrator Extension DLL.

See Also

HrAdminExtensionExists, HrGetAdminExtensionVersion, HrRemoveAdminExtension


HrInstallGateway

The HrInstallGateway function loads a gateway into a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallGateway(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszDisplayName,
  LPSTR lpszCommonName,
  LPSTR lpszExtensionName,
  LPSTR lpszExtensionData,
  LPSTR lpszAddressType,
  LPSTR lpszAccountName,
  BOOL fCanPreserveDNs
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) containing the name of the server where the gateway is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) containing the distinguished name (DN) of the site where the gateway is installed.
lpszDisplayName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) containing the name of the gateway as displayed by the Microsoft Exchange Server Administrator program.

Although the Windows NT service control manager preserves the case of the name that is displayed, comparisons between display names are case-insensitive.

lpszCommonName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the relative distinguished name (RDN) of the gateway object. Common names have the following format:

extension-name:hardware-platform

For example, suppose you have a gateway called ToNet with an Extension-Name attribute of ToNet. If your platform is Intel, set lpszCommonName to ToNet:i386.

lpszExtensionName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the Administrator extension program that supports this gateway.
lpszExtensionData
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the extension data file.
lpszAddressType
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the address type that the gateway supports.
lpszAccountName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the Windows NT user account of the person who administers the gateway.
fCanPreserveDNs
Input parameter. Determines whether the gateway preserves distinguished names:
TRUE
The gateway preserves distinguished names.
FALSE
The gateway does not preserve distinguished names.

Return Values

See Return Values.

See Also

HrGatewayExists, HrInstallService, HrRemoveGateway


HrInstallGatewayProxy

The HrInstallGatewayProxy function adds a site proxy address to the Gateway-Proxy attribute on the Site-Addressing object in the directory.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallGatewayProxy(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszProxy
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the server where the site proxy address is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the distinguished name (DN) of the site where the site proxy address is installed.
lpszProxy
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the site proxy address to install.

Return Values

See Return Values.

Remarks

The Gateway-Proxy attribute is a multi-valued attribute. The site proxy address is used by the proxy generation DLL for a given address type to create a new email address of that type.

See Also

HrRemoveGatewayProxy


HrInstallMailboxAgent

The HrInstallMailboxAgent function loads a mailbox agent object into a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallMailboxAgent(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszDisplayName,
  LPSTR lpszRDN,
  LPSTR lpszExtensionName,
  LPSTR lpszExtensionData,
  LPSTR lpszAccountName
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the server where the mailbox agent is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the distinguished name (DN) of the site where the mailbox agent is installed.
lpszDisplayName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the mailbox agent as displayed by the Microsoft Exchange Server Administrator program.

Although the Windows NT service control manager preserves the case of the name that is displayed, comparisons between display names are case-insensitive.

lpszRDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the relative distinguished name (RDN) of this mailbox agent.
lpszExtensionName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the Administrator extension program that supports this mailbox agent.
lpszExtensionData
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the extension data file.
lpszAccountName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the Windows NT user account of the person who administers this mailbox agent.

Return Values

See Return Values.

See Also

HrCreateMailboxAgentProfile, HrMailboxAgentExists, HrRemoveMailboxAgent


HrInstallMessageConverter

The HrInstallMessageConverter function loads a message conversion DLL.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallMessageConverter(
  LPSTR lpszConverter,
  LPSTR lpszDllName,
  LPSTR lpszMessageClasses,
  LPSTR lpszOptions,
  LPSTR lpszPoint
);

Parameters

lpszConverter
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the converter.
lpszDllName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full path to the conversion DLL.
lpszMessageClasses
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the message classes the DLL handles.

This parameter is terminated by two null values, such as in the following example, which specifies the DLL handles both SMTP and X.400 messages:

"SMTP\0X.400\0\0"

lpszOptions
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains any arguments to the DLL.
lpszPoint
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that specifies whether the DLL performs inbound (messages that are converted from another format to MAPI format) or outbound (messages that are converted from MAPI format to another format) conversion:
"INBOUND"
The DLL converts inbound messages.
"OUTBOUND"
The DLL converts outbound messages.

Return Values

See Return Values.

Remarks

The lpszMessageClasses and lpszPoint parameters define which messages the DLL converts.

See Also

HrRemoveMessageConverter


HrInstallService

The HrInstallService function loads a service for a server object.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallService(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszServiceDisplayName,
  LPSTR lpszServiceName,
  LPSTR lpszCommonName,
  LPSTR lpszObjectGuid,
  LPSTR lpszProductGuid,
  LPSTR lpszExeName,
  LPCSTR lpszDependencies,
  LPSTR lpszAccount,
  LPSTR lpszPassword
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the server where the service is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters), containing the distinguished name (DN) of the site where the service is installed.
lpszServiceDisplayName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the service as displayed by the Microsoft Exchange Server Administrator program.

Although the service control manager preserves the case of the name that is displayed, comparisons between display names are case-insensitive.

lpszServiceName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the service which is installed. You cannot use either the forward slash (/) or back slash (\) character in a service name.
lpszCommonName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the relative distinguished name (RDN) of the service object. Common names have the following format:

extension-name:hardware-platform

For example, suppose you have a service called NetLink with an Extension-Name attribute of NetLink. If your platform is Intel, set lpszCommonName to NetLink:i386.

lpszObjectGuid
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the service object GUID.
lpszProductGuid
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the product object GUID.
lpszExeName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full path to the service program.
lpszDependencies
Input parameter. Points to an array of NULL-separated strings (with a maximum length of 256 characters) that is terminated by two NULL entries. This array contains the names of services or load ordering groups that must start before this service can start.

If the entry is the name of a service, this service will not start unless this lpszDependencies service is running. If the entry is a group name, this service will not start unless at least one of the lpszDependencies group members is running. Groups names must contain the SC_GROUP_IDENTIFIER prefix character, which is defined in WINSVC.H. Note that this also means that service names cannot begin with the SC_GROUP_IDENTIFIER prefix character.

If this parameter is NULL or the string is an empty string, this service has no dependencies.

lpszAccount
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the Windows NT user account of the person who administers the service.

The account name has the following format:

DomainName\UserName

If the account belongs to the built-in domain, you can use .\UserName. If this parameter is NULL, the service is logged in under the LocalSystem account and lpszPassword must be NULL.

lpszPassword
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the user account password. If this parameter is NULL or points to an empty string, the service has no password.

Return Values

See Return Values.

Remarks

For more information on HrInstallService, see Installing an Application as a Service.

See Also

HrRemoveService


HrInstallServicePerfMon

The HrInstallServicePerfMon function loads the Windows NT performance monitor on the server.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrInstallServicePerfMon(
  LPSTR lpszServiceName,
  LPSTR lpszClassName,
  LPSTR lpszLibraryName,
  LPSTR lpszLibraryOpenFunction,
  LPSTR lpszLibraryCollectFunction,
  LPSTR lpszLibraryCloseFunction
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the name of the service to monitor.
lpszClassName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the class of service to monitor.
lpszLibraryName
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the full pathname of the DLL containing the performance monitoring functions.
lpszLibraryOpenFunction
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the performance monitoring function that opens (begins) performance monitoring on the service.
lpszLibraryCollectFunction
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the performance monitoring function that collects the statistics from the service that is monitored.
lpszLibraryCloseFunction
Input parameter. Points to a null-terminated string (with a maximum length of 256 characters) that contains the performance monitoring function that closes (halts) performance monitoring on the service.

Return Values

See Return Values.

Remarks

For more information on this function, see Installing Performance Monitoring.

See Also

HrRemoveServicePerfMon


HrJSCollectDataPoint

The HrJSCollectDataPoint function provides a snapshot value to the jump window.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrJSCollectDataPoint(
  HJSWINDOW hJSWindow,
  FILETIME * pftNow,
  DWORD dwValue
);

Parameters

hJSWindow
Input parameter. Handle to the jump window.
pftNow
Input parameter. Points to the current time.
dwValue
Input parameter. Snapshot value to add to the jump window.

Return Values

See Return Values.

Remarks

The HrJSCollectDataPoint function provides a snapshot value to the jump window as an item of data to be included in the jump window statistic.

For more information on this function, see Jump Window Functions in the Gateway Programmer's Reference.

See Also

HrFileTimeToSeconds, HrJSOpen, HrJSGetValue, JSClose,


HrJSGetValue

The HrJSGetValue function calculates the jump window's current value.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrJSGetValue(
  HJSWINDOW hJSWindow,
  FILETIME * pftNow,
  DWORD * pdwWindowValue,
  DWORD * pdwFractionCompleteNum,
  DWORD * pdwFractionCompleteDen
);

Parameters

hJSWindow
Input parameter. Handle to the jump window.
pftNow
Input parameter. Points to the current time.
pdwWindowValue
Output parameter. Points to the calculated jump window statistic.
pdwFractionCompleteNum
Output parameter. Points to the numerator value of the fraction of the duration.
pdwFractionCompleteDen
Output parameter. Points to the denominator value of the fraction of the duration.

Return Values

See Return Values.

Remarks

HrJSGetValue calculates the current value for the jump window, calculated at the time of the window's most recent jump.

When the jump window starts operating, it is possible that a value is requested before the jump window has completed one duration. In this case, the current value is derived from an incomplete set of data collected over a fraction of the jump window's duration. Under these conditions, HrJSGetValue calculates and reports this fraction as two separate values: pdwFractionCompleteNum, the fraction numerator, and pdwFractionCompleteDen, the fraction denominator. For example, if the duration is an hour, and HrJSGetValue calculates a value after only 45 minutes, then the ratio of *pdwFractionCompleteNum / *pdwFractionCompleteDen equals 3/4.

This ratio can be used to convert an incomplete duration into a rate estimated by multiplying the returned jump window value by pdwFractionCompleteDen and dividing the result by pdwFractionCompleteNum. Before performing this calculation, test pdwFractionCompleteNum for equality to zero. For example, after it has existed for 45 minutes, a jump window with the duration of an hour, which tracks the number of messages, returns a value of 12. Therefore, the estimated rate is 4/3 * 12 = 16 messages/hour.

When HrJSGetValue is called for a jump window that has existed for longer than one duration, the ratio of pdwFractionCompleteNum / pdwFractionCompleteDen is always 1.

For more information on this function, see Jump Window Functions in the Gateway Programmer's Reference.

See Also

HrFileTimeToSeconds, HrJSOpen, HrJSCollectDataPoint, JSClose


HrJSOpen

The HrJSOpen function specifies a jump window's calculations and dimensions.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrJSOpen(
  JSWINDOWTYPE enType,
  FILETIME * pftNow,
  FILETIME * pftResolution,
  DWORD dwWindowDuration,
  HJSWINDOW * phJSWindow
);

Parameters

enType
Input parameter. The type of calculation performed by the jump window:
JSWINDOW_MIN
The minimum value for period.
JSWINDOW_MAX
The maximum value for period.
JSWINDOW_AVERAGE
The average value for period.
JSWINDOW_TOTAL_RATE
The total of all values in period. This result can also be interpreted as a rate.
pftNow
Input parameter. Points to the current time, when the window starts operating.
pftResolution
Input parameter. Points to the time interval between window jumps.
dwWindowDuration
Input parameter. Width of the window, expressed as a multiple of ftResolution, the jump window resolution.
phJSWindow
Output parameter. Points to the handle to the jump window.

Return Values

See Return Values.

Remarks

HrJSOpen defines a jump window, including the type of calculation the jump window performs, its duration (the time span covered by the jump window), and its resolution (the time interval between window jumps).

The resolution is defined as a time interval, while the duration is defined as a multiple of the resolution. For example, if the window spans an hour and jumps every minute, the duration is 60.

For more information on this function, see Jump Window Functions in the Gateway Programmer's Reference.

See Also

HrFileTimeToSeconds, HrJSCollectDataPoint, HrJSGetValue, JSClose


HrMailboxAgentExists

The HrMailboxAgentExists function checks whether a mailbox agent exists on a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrMailboxAgentExists(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszRDN
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server where the mailbox agent might exist.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the DN of the site where the mailbox agent might exist.
lpszRDN
Input parameter. Points to a null-terminated string containing the RDN of the site where the mailbox agent might exist.

Return Values

See Return Values.

See Also

HrInstallMailboxAgent, HrRemoveMailboxAgent


HrMailboxLogoff

The HrMailboxLogoff function logs off a server and mailbox.

Quick Info

Header file: | MBLOGON.H
Library: | MBLOGON.LIB

HRESULT HrMailboxLogoff(
  LPMDB *lppMailboxMDB
);

Parameters

lppMailboxMDB
Input/output parameter. Points to a MAPI IMsgStore interface containing the mailbox message store.

Return Values

See Return Values.

Remarks

The caller supplies the DNs of the server and mailbox.

For more information on this function, see Logging On to a Mailbox as a Privileged Service and Using the IExchangeManageStore Interface.

For information on the IMsgStore interface and obtaining distinguished names, see the MAPI Programmer's Reference.

See Also

HrMailboxLogon


HrMailboxLogon

The HrMailboxLogon function logs on a server and mailbox.

Quick Info

Header file: | MBLOGON.H
Library: | MBLOGON.LIB

HRESULT HrMailboxLogon(
  LPMAPISESSION lplhSession,
  LPMDB lpMDB,
  LPSTR lpszMsgStoreDN,
  LPSTR lpszMailboxDN,
  LPMDB * lppMailboxMDB
);

Parameters

lplhSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session handle.
lpMDB
Input parameter. Points to a MAPI IMsgStore interface containing message store.
lpszMstStoreDN
Input parameter. Points to the information store distinguished name (DN).
lpszMailboxDN
Input parameter. Points to the mailbox DN. If NULL, HrMailboxLogon logs onto the public information store.
lppMailboxMDB
Output parameter. Points to an IMsgStore interface containing the mailbox information store.

Return Values

See Return Values.

Remarks

This function is only intended for use by applications using the IExchangeManageStore::GetMailboxTable method to access other mailboxes in the system as a privileged service; for example, a voicemail application. See Logging On to a Mailbox as a Privileged Service. If this call is used, the account under which the application runs requires special permissions to function. Normal client applications should use the MAPILogonEx function to log on to a profile and gain access to an Microsoft Exchange-based mailbox.

Before calling the HrMailboxLogon function, perform the following steps:

  1. Create a profile that has administrator privileges.
  2. Log on to the profile with administrator privileges.
  3. Open the information store for that profile.

The server and mailbox names must be in the form of distinguished names. For example:

/O=Organization/OU=Site/CN=Servers/CN=ServerName/CN=NULL
/O=Organization/OU=Site/CN=Container/CN=MailboxName

For more information on this function, see Logging On to a Mailbox as a Privileged Service and Using the IExchangeManageStore Interface.

For information on the IMAPISession and IMsgStore interfaces and obtaining DNs, see the MAPI Programmer's Reference.

See Also

HrMailboxLogoff


HrMAPIAppendAddressList

The HrMAPIAppendAddressList function adds an address list entry to an address list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIAppendAddressList(
  ULONG cProps,
  LPSPropValue lpPropValues,
  LPADRLIST * lppAdrList
);

Parameters

cProps
Input parameter. Count of values in address list pointed to by lpPropValues.
lpPropValues
Input parameter. Points to a MAPI SPropValue structure containing the address list entry.
lppAdrList
Input/output parameter. Points to address list array.

Return Values

See Return Values.

Remarks

The lppAdrList parameter contains the original address array before the call; it contains the address array with the new entry after the call.

For information on the SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrMAPICreateAddressList, HrMAPICreateSizedAddressList, HrMAPISetAddressList


HrMAPIAppendEntryList

The HrMAPIAppendEntryList function adds an entry to an entry list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIAppendEntryList(
  ULONG cbeid,
  LPENTRYID lpeid,
  LPENTRYLIST FAR lpEntryList
);

Parameters

cbeid
Input parameter. Number of bytes in the entry identifier.
lpeid
Input parameter. Points to a MAPI ENTRYID structure containing the entry identifier.
lpEntryList
Output parameter. Points to the address variable of the entry list.

Return Values

See Return Values.

Remarks

For information on the ENTRYID structure, see the MAPI Programmer's Reference.

See Also

HrMAPICreateEntryList, HrMAPIDestroyEntryList


HrMAPIAppendSPropValues

The HrMAPIAppendSPropValues function adds an array of one or more MAPI SPropValue structures to the end of an existing array of SPropValue structures.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIAppendSPropValues(
  ULONG cHeadProps,
  LPSPropValue lpHeadProps,
  ULONG cTailProps,
  LPSPropValue lpTailProps,
  ULONG * lpcNewProps,
  LPSPropValue * lppNewProps
);

Parameters

cHeadProps
Input parameter. Count of property values pointed to by lpHeadProps.
lpHeadProps
Input parameter. Points to an SPropValue structure containing the existing set of property values.
cTailProps
Input parameter. Count of property values pointed to by lpTailProps.
lpTailProps
Input parameter. Points to an SPropValue structure containing the property values to append to lpHeadProps.
lpcNewProps
Output parameter. Points to the count of property values pointed to by lppNewProps.
lppNewProps
Output parameter. Points to an SPropValue structure containing the resulting set of property values.

Return Values

See Return Values.

Remarks

Use the MAPI IMAPIProp::GetProps method to get a list of properties.

For more information on this function, see the HrMAPIAppendSPropValues function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp::GetProps method and SPropValue structure, see the MAPI Programmer's Reference.


HrMAPICloseCachedProp

The HrMAPICloseCachedProp function copies the properties in a local cached object back to the original remote object, if the object was created as a write cache.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPICloseCachedProp(
  LPPROPDATA lpCachedObj,
  LPMAPIPROP lpOriginalObj,
  ULONG ulFlags,
  LPSPropProblemArray  FAR * lpp Problems
);

Parameters

lpCachedObj
Input parameter. Points to a MAPI IPropData interface containing the cached property object.
lpOriginalObj
Input parameter. Points to a MAPI IMAPIProp interface containing the original object.
ulFlags
Input parameter. Defined values that control the cache type:
EDK_CACHE_READ
EDK_CACHE_WRITE
lppProblems
Output parameter. Points to a MAPI SPropProblemArray structure containing information about problems setting properties on the original object.

Return Values

See Return Values.

Remarks

The calling application is responsible for releasing the local MAPI IMAPIProp object when it is finished using it. lppProblems may be set, even though the overall call is successful. This is because all of the SetProps have been deferred on the original object until this call. The user must evaluate the contents of the lppProblems buffer pointer based on which properties were set.

For more information on this function, see the HrMAPICloseCachedProp function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, SPropProblemArray structure, and SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrMAPIOpenCachedProp


HrMAPICopyMessage

The HrMAPICopyMessage function copies a message from one folder to another folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPICopyMessage(
  LPMAPIFOLDER lpSrcFolder,
  LPMAPIFOLDER lpDstFolder,
  ULONG cbeid,
  LPENTRY lpeid
);

Parameters

lpSrcFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the source folder.
lpDstFolder
Input parameter. Points to an IMAPIFolder interface containing the destination folder.
cbeid
Input parameter. Number of bytes in entry identifier.
lpeid
Input parameter. Points to entry identifier.

Return Values

See Return Values.

Remarks

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

HrMAPIDeleteMessage, HrMAPIMoveMessage


HrMAPICreateAddressList

The HrMAPICreateAddressList function creates an address list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPICreateAddressList(
  ULONG cProps,
  LPSPropValue lpPropValues,
  LPADRLIST * lppAdrList
);

Parameters

cProps
Input parameter. Count of values in address list entry.
lpPropValues
Input parameter. Points to a MAPI SPropValue structure containing the address list entry.
lppAdrList
Output parameter. Points to the address where the address list is stored.

Return Values

See Return Values.

Remarks

For information on the SPropValue structure, see the MAPI Programmer's Reference.

See Also

HrMAPIAppendAddressList, HrMAPICreateSizedAddressList, HrMAPISetAddressList


HrMAPICreateEntryList

The HrMAPICreateEntryList function creates an entry list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPICreateEntryList(
  ULONG cbeid,
  LPENTRYID lpeid,
  LPENTRYLIST FAR * lppEntryList
);

Parameters

cbeid
Input parameter. Number of bytes in the entry identifier.
lpeid
Input parameter. Points to the entry identifier.
lppEntryList
Output parameter. Points to address variable of the entry list.

Return Values

See Return Values.


HrMAPICreateSizedAddressList

The HrMAPICreateSizedAddressList function creates a sized address list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPICreateSizedAddressList(
  ULONG cEntries,
  LPADRLIST * lppAdrList
);

Parameters

cEntries
Input parameter. Count of entries in address list.
lppAdrList
Input/output parameter. Points to a MAPI ADRLIST structure containing the address where the address list is stored.

Return Values

See Return Values.

Remarks

For an example of how to use this function, see the HrExpandMessageAddressList function call in ADDRESS.C under the GWSAMPLE code sample in the Code Samples folder.

For information on the ADRLIST structure, see the MAPI Programmer's Reference.

See Also

HrMAPIAppendAddressList, HrMAPICreateAddressList, HrMAPISetAddressList


HrMAPIDeleteMessage

The HrMAPIDeleteMessage function deletes a message from a folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIDeleteMessage(
  LPMAPIFOLDER lpFolder,
  ULONG cbeid,
  LPENTRY lpeid
);

Parameters

lpFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the folder.
cbeid
Input parameter. Number of bytes in the entry identifier.
lpeid
Input parameter. Points to the entry identifier.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIDeleteMessage function in IMESSAGE.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

HrMAPICopyMessage, HrMAPIMoveMessage


HrMAPIDestroyEntryList

The HrMAPIDestroyEntryList function frees an entry list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIDestroyEntryList(
  LPENTRYLIST FAR * lppEntryList
);

Parameters

lppEntryList
Input/output parameter. Points to the address variable of the entry list.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIDestroyEntryList function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.


HrMAPIFindDefaultMsgStore

The HrMAPIFindDefaultMsgStore function retrieves the entry identifier of the default information store.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIFindDefaultMsgStore(
  LPMAPISESSION lplhSession,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lplhSession
Input parameter. Points to a MAPI IMAPISession interface containing the handle of the current session.
lpcbeid
Output parameter. Number of bytes in entry identifier.
lppeid
Output parameter. Entry identifier of default information store.

Return Values

See Return Values.

Remarks

For more information on this function, see Opening an Information Store.

For information on the IMAPISession interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindStore


HrMAPIFindFolder

The HrMAPIFindFolder function retrieves a folder by name.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB
Unicode: | Yes

HRESULT HrMAPIFindFolder(
  LPMAPIFOLDER lpFolder,
  LPTSTR lpszName,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the folder.
lpszName
Input parameter. Name of the folder to find.
lpcbeid
Output parameter. Points to the count of bytes in the entry identifier.
lppeid
Output parameter. Points to the address where the MAPI ENTRYID structure containing the entry identifier is stored.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIFindFolder function in IFOLDER.C under the EDKMAPI code sample in the Code Samples folder.

For information on the ENTRYID structure and IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindFolderEx, HrMAPIFindSubfolderEx, HrMAPIOpenFolderEx


HrMAPIFindFolderEx

The HrMAPIFindFolderEx function retrieves a folder in an information store using the hierarchical path name of the folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB
Unicode: | Yes

HRESULT HrMAPIFindFolderEx(
  LPMDB lpMdb,
  TCHAR chSep,
  LPTSTR lpszFolderPath,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the open information store.
chSep
Input parameter. Folder path separator character.
lpszFolderPath
Input parameter. Folder path.
lpcbeid
Output parameter. Points to count of bytes in the entry identifier.
lppeid
Output parameter. Points to the address where the MAPI ENTRYID structure containing the entry identifier is stored.

Return Values

See Return Values.

Remarks

To open the root folder, set the value of lpMdp to NULL.

For more information on this function, see Opening an Existing Private or Personal Folder.

For information on the ENTRYID structure and IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindFolder, HrMAPIFindSubfolderEx, HrMAPIOpenFolderEx


HrMAPIFindInbox

The HrMAPIFindInbox function retrieves the IPM inbox folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIFindInbox(
  LPMDB lpMdb,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the information store.
lpcbeid
Output parameter. Number of bytes in the entry identifier.
lppeid
Output parameter. Points to address of MAPI ENTRYID structure containing the entry identifier of IPM inbox.

Return Values

See Return Values.

Remarks

For more information on this function, see Opening the Inbox.

For information on the ENTRYID structure and IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindOutbox, HrMAPIFindIPMSubtree


HrMAPIFindIPMSubtree

The HrMAPIFindIPMSubtree function retrieves the IPM (interpersonal message) subtree folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIFindIPMSubtree(
  LPMDB lpMdb,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the information store.
lpcbeid
Output parameter. Number of bytes in the entry identifier
lppeid
Output parameter. Points to a MAPI ENTRYID structure containing the entry identifier of IPM subtree.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIFindIPMSubtree function in IFIND.C under the EDKMAPI code sample in the Code Samples folder. For an introduction on IPM and non-IPM folders, see About Public Folders.

For information on the ENTRYID structure and IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindInbox, HrMAPIFindOutbox


HrMAPIFindMsgByProp

The HrMAPIFindMsgByProp function retrieves the entry identifier of a message through a property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIFindMsgByProp(
  LPMAPIFOLDER lpFolder,
  LPSPropValue lpSPropValue,
  LPENTRYLIST * lppMsgList
);

Parameters

lpFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the folder.
lpSPropValue
Input parameter. Points to a MAPI SPropValue structure containing the property.
lppMsgList
Output parameter. List of matching messages.

Return Values

See Return Values.

Remarks

The HrMAPIFindMsgByProp function creates a list of messages in lppMsgList whose property, including value, match that specified by the property in lpSPropValue.

For more information on this function, see the HrMAPIFindMsgByProp function in IMESSAGE.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIFolder interface and SPropValue structure, see the MAPI Programmer's Reference.


HrMAPIFindOutbox

The HrMAPIFindOutbox function retrieves the IPM outbox folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIFindOutbox(
  LPMDB lpMdb,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing the message store.
lpcbeid
Output parameter. Number of bytes in entry identifier.
lppeid
Output parameter. Points to the address of a MAPI ENTRYID structure containing the entry identifier of IPM outbox.

Return Values

See Return Values.

Remarks

For information related to the HrMAPIFindOutbox function, see Opening the Inbox. For more information, see the HrMAPIFindOutbox function in IFIND.C under the EDKMAPI code sample in the Code Samples folder.

For information on the ENTRYID structure and IMsgStore interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindInbox, HrMAPIFindIPMSubtree


HrMAPIFindStore

The HrMAPIFindStore function retrieves a pointer to the entry identifier of an information store from the display name of the store.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB
Unicode: | Yes

HRESULT HrMAPIFindStore(
  LPMAPISESSION lpSession,
  LPCTSTR lpszStore,
  ULONG FAR * lpcbentryid,
  LPENTRYID FAR * lppentryid
);

Parameters

lpSession
Input parameter. Points to a MAPI IMAPISession interface containing the session.
lpszStore
Input parameter. Name of the information store (PR_DISPLAY_NAME) to find.
lpcbentryid
Output parameter. Number of bytes in the information store's entry identifier.
lppentryid
Output parameter. Points to a MAPI ENTRYID structure containing the information store entry identifier.

Return Values

See Return Values.

Remarks

For more information on this function, see Locating an Information Store.

For information on the ENTRYID structure and IMAPISession interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindDefaultMsgStore


HrMAPIFindSubfolderEx

The HrMAPIFindSubfolderEx function retrieves a subfolder in an information store using the hierarchical path name of the folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB
Unicode: | Yes

HRESULT HrMAPIFindSubfolderEx(
  LPMAPIFOLDER lpRootFolder,
  TCHAR chSep,
  LPCTSTR lpszName,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

lpRootFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the open root folder.
chSep
Input parameter. Folder path separator character.
lpszName
Input parameter. Folder path.
lpcbeid
Output parameter. The size, in bytes, of the entry identifier specified in the lppeid parameter.
lppeid
Output parameter. Points to an ENTRYID structure containing the entry identifier for the folder.

Return Values

See Return Values.

Remarks

Pass a NULL value for lpMdp to open the root folder.

For more information on this function, see the HrMAPIFindSubfolderEx function in IFOLDER.C under the EDKMAPI code sample in the Code Samples folder.

For information on the ENTRYID structure and IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindFolder, HrMAPIFindFolderEx, HrMAPIOpenSubfolderEx


HrMAPIGetFirstSRowSet

The HrMAPIGetFirstSRowSet function obtains the first MAPI SRowSet structure from an array of SRowSet structures.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetFirstSRowSet(
  LPMAPITABLE lpTable,
  ULONG cRows,
  LPSPropTagArray rgPropTags,
  LPSRowSet FAR * lppRows
);

Parameters

lpTable
Input parameter. Points to a MAPI IMAPITable interface containing the table address variable.
cRows
Input parameter. Count of number of rows in the SRowSet structure pointed to by lppRows.
rgPropTags
Input parameter. Array of property tags.
lppRows
Output parameter. Points to address variable for the SRowSet structure.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIGetFirstSRowSet function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

Note To release memory that you have allocated for a SRowSet structure, use the MAPI FreeProws function. If you use the MAPI MAPIFreeBuffer function, your application will leak memory.

For information on the FreeProws function, IMAPITable interface, MAPIFreeBuffer function, and SRowSet structure, see the MAPI Programmer's Reference.

See Also

HrMAPIGetNextSRowSet, HrMAPIGotoFirstSRow


HrMAPIGetNextSRowSet

The HrMAPIGetNextSRowSet function obtains the next MAPI SRowSet structure from an array of MAPI SRowSet structures.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetNextSRowSet(
  LPMAPITABLE lpTable,
  ULONG cRows,
  LPSPropTagArray rgPropTags,
  LPSRowSet FAR * lppRows
);

Parameters

lpTable
Input parameter. Points to a MAPI IMAPITable interface containing the table.
cRows
Input parameter. Count of number of rows in the MAPI SRowSet structure.
rgPropTags
Input parameter. Array of property tags.
lppRows
Output parameter. Points to address variable for the MAPI SRowSet structure.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIGetNextSRowSet function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

Note To release memory that you have allocated for a SRowSet structure, use the MAPI FreeProws function. If you use the MAPI MAPIFreeBuffer function, your application will leak memory.

For information on the FreeProws function, IMAPITable interface, MAPIFreeBuffer function, SRowSet structure, see the MAPI Programmer's Reference.

See Also

HrMAPIGetFirstSRowSet, HrMAPIGotoNextSRow


HrMAPIGetPropBinary

The HrMAPIGetPropBinary function obtains the binary value of a property from a property tag.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetPropBinary(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  ULONG *lpcbProp,
  LPVOID * lppvProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpcbProp
Output parameter. Number of bytes in property.
lppvProp
Output parameter. Points to property address variable.

Return Values

See Return Values.

Remarks

Use this function when the property type is PT_BINARY.

For more information on this function, see the HrMAPIGetPropBinary function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrMAPIGetPropBoolean, HrMAPIGetPropLong, HrMAPIGetPropString, HrMAPIGetPropSystime


HrMAPIGetPropBoolean

The HrMAPIGetPropBoolean function obtains the Boolean value of a property from a property tag.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetPropBoolean(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  BOOL *lpfProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpfProp
Output parameter. Points to property variable.

Return Values

See Return Values.

Remarks

Use this function when the property type is PT_BOOLEAN.

For more information on this function, see the HrMAPIGetPropBoolean function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIGetPropBinary, HrMAPIGetPropLong, HrMAPIGetPropString, HrMAPIGetPropSystime


HrMAPIGetPropLong

The HrMAPIGetPropLong function obtains the long value of a property from a property tag.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetPropLong(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  ULONG * lpulProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpulProp
Output parameter. Points to property variable.

Return Values

See Return Values.

Remarks

Use this function when the property type is PT_LONG.

For more information on this function, see the HrMAPIGetPropLong function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIGetPropBinary, HrMAPIGetPropBoolean, HrMAPIGetPropString, HrMAPIGetPropSystime


HrMAPIGetPropString

The HrMAPIGetPropString function obtains the string value of a property from a property tag.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetPropString(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  ULONG * lpcbProp,
  LPVOID * lppvProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpcbProp
Output parameter. Number of bytes in property.
lppvProp
Output parameter. Points to property address variable.

Return Values

See Return Values.

Remarks

Use this function when the property type is PT_STRING8.

For more information on this function, see the HrMAPIGetPropString function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIGetPropBinary, HrMAPIGetPropBoolean, HrMAPIGetPropLong, HrMAPIGetPropSystime


HrMAPIGetPropSystime

The HrMAPIGetPropSystime function obtains the system time value of a property from a property tag.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetPropSystime(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  LPFILETIME lpSystime
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpSystime
Output parameter. Points to a MAPI FILETIME structure containing the time.

Return Values

See Return Values.

Remarks

Use this function when the property type is PT_SYSTIME.

For more information on this function, see the HrMAPIGetPropSystime function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the FILETIME structure and IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIGetPropBinary, HrMAPIGetPropBoolean, HrMAPIGetPropString, HrMAPIGetPropLong


HrMAPIGetPropToFile

The HrMAPIGetPropToFile function saves a property in a file.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGetPropToFile(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  LPTSTR lpszFilename,
  ULONG * lpcbProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpszFilename
Input parameter. Points to destination file name.
lpcbProp
Output parameter. Points to the number of bytes in the property value. This parameter is only required for property types PT_BINARY and PT_STRING8. This parameter is ignored for other property types, so set it to NULL for other property types.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIGetPropToFile function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.


HrMAPIGotoFirstSRow

The HrMAPIGotoFirstSRow function retrieves a pointer to the first MAPI SRow structure in a MAPI SRowSet structure.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGotoFirstSRow(
  LPSRowSet FAR lpRows,
  ULONG * lpulRow,
  LPSRow * lppRow
);

Parameters

lpRows
Input parameter. Points to the SRowSet structure.
lpulRow
Output parameter. Index of the SRow structure in the SRowSet structure.
lppRow
Output parameter. Points to a SRow structure.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIGotoFirstSRow function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

Note To release memory that you have allocated for a SRowSet structure, use the MAPI FreeProws function. If you use the MAPI MAPIFreeBuffer function, your application will leak memory.

For information on the FreeProws function, MAPIFreeBuffer function, SRow structure, and SRowSet structure, see the MAPI Programmer's Reference.

See Also

HrMAPIGetFirstSRowSet, HrMAPIGotoNextSRow, HrMAPIGotoSRow


HrMAPIGotoNextSRow

The HrMAPIGotoNextSRow function retrieves a pointer to the next MAPI SRow structure in a MAPI SRowSet structure.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGotoNextSRow(
  LPSRowSet FAR lpRows,
  ULONG * lpulRow,
  LPSRow * lppRow
);

Parameters

lpRows
Input parameter. Points to the SRowSet structure.
lpulRow
Input/output parameter. Index of the SRow structure in the SRowSet structure.
lppRow
Output parameter. Points to the SRow structure.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIGotoNextSRow function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

Note To release memory that you have allocated for a SRowSet structure, use the MAPI FreeProws function. If you use the MAPI MAPIFreeBuffer function, your application will leak memory.

For information on the FreeProws function, MAPIFreeBuffer function, SRow structure, and SRowSet structure, see the MAPI Programmer's Reference.

See Also

HrMAPIGetNextSRowSet, HrMAPIGotoFirstSRow, HrMAPIGotoSRow


HrMAPIGotoSRow

The HrMAPIGotoSRow function retrieves a pointer to a MAPI SRow structure in a MAPI SRowSet structure.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIGotoSRow(
  LPSRowSet FAR lpRows,
  ULONG ulRow,
  LPSRow * lppRow
);

Parameters

lpRows
Input parameter. Points to the SRowSet structure.
ulRow
Input parameter. Index of the SRow structure in the SRowSet structure.
lppRow
Output parameter. Points to the SRow structure.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIGotoSRow function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

For information on the FreeProws function, MAPIFreeBuffer function, SRow structure, and SRowSet structure, see the MAPI Programmer's Reference.

Note To release memory that you have allocated for a MAPI SRowSet structure, use the MAPI FreeProws function. If you use the MAPI MAPIFreeBuffer function, your application will leak memory.

See Also

HrMAPIGetFirstSRowSet, HrMAPIGotoNextSRow


HrMAPIMoveMessage

The HrMAPIMoveMessage function transfers a message from one folder to another.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIMoveMessage(
  LPMAPIFOLDER lpSrcFolder,
  LPMAPIFOLDER lpDstFolder,
  ULONG cbeid,
  LPENTRYID lpeid
);

Parameters

lpSrcFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the source folder.
lpDstFolder
Input parameter. Points to an IMAPIFolder interface containing the destination folder.
cbeid
Input parameter. Number of bytes in the entry identifier.
lpeid
Input parameter. Points to the entry identifier.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIMoveMessage function in IMESSAGE.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

HrMAPICopyMessage, HrMAPIDeleteMessage, HrMAPIMoveOneProp


HrMAPIMoveOneProp

The HrMAPIMoveOneProp function transfers a property from one object to another object.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIMoveOneProp(
  LPMAPIPROP lpSrcObj,
  ULONG ulSrcPropTag,
  ULONG ulDstPropTag,
  BOOL IsMust,
  BOOL IsReplace,
  LPMAPIPROP lpDstObj
);

Parameters

lpSrcObj
Input parameter. Points to a MAPI IMAPIProp interface containing the source object.
ulSrcPropTag
Input parameter. Source property tag.
ulDstPropTag
Input parameter. Destination property tag.
IsMust
Input parameter. Set this parameter to TRUE if this is a required property.
IsReplace
Input parameter. Set this parameter to TRUE to replace an existing destination property.
lpDstObj
Input/output parameter. Points to a IMAPIProp interface containing the destination object.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIMoveOneProp function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIMoveMessage


HrMAPIOpenCachedProp

The HrMAPIOpenCachedProp function creates a new (local) MAPI IPropData object where the original object properties are cached.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIOpenCachedProp(
  LPMAPIPROP lpObj,
  LPSPropTagArray lpPropList,
  ULONG dwFlags,
  LPPROPDATA FAR * lppCachedObj
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the source object.
lpPropList
Input parameter. List of properties to cache.
dwFlags
Input parameter. Open for reading only or writing only.
lppCachedObj
Output parameter. Points to an IPropData interface containing the cached version of source object.

Return Values

See Return Values.

Remarks

The local cached version of the source object can be created for reading (for use with HrMAPIGetProp* calls) for for writing (for use with HrMAPISetProp* calls). The purpose of the HrMAPIOpenCachedProp function and HrMAPICloseCachedProp is to reduce the number of remote procedure calls made by the code which performs many HrMAPIGetProp* or HrMAPISetProp* calls on an object.

This function creates a cached object for reading only or writing only. It does not support an object for both reading and writing.

For information on the IMAPIProp and IPropData interfaces, see the MAPI Programmer's Reference.

See Also

HrMAPICloseCachedProp


HrMAPIOpenFolderEx

The HrMAPIOpenFolderEx function opens a folder in the information store from the hierarchical path name of the folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB
Unicode: | Yes

HRESULT HrMAPIOpenFolderEx(
  LPMDB lpMdb,
  TCHAR chSep,
  LPTSTR lpszFolderPath,
  LPMAPIFOLDER * lppFolder
);

Parameters

lpMdb
Input parameter. Points to a MAPI IMsgStore interface containing an open information store.
chSep
Input parameter. Folder path separator character.
lpszFolderPath
Input parameter. Folder path.
lppFolder
Output parameter. Points to a MAPI IMAPIFolder interface containing the opened folder.

Return Values

See Return Values.

Remarks

Set lpMdb to NULL to open the root folder.

For more information on this function, see Opening an Existing Private or Personal Folder.

For information on the IMAPIFolder and IMsgStore interfaces, see the MAPI Programmer's Reference.

See Also

HrMAPIFindFolder, HrMAPIFindFolderEx


HrMAPIOpenStreamOnProperty

The HrMAPIOpenStreamOnProperty function opens a stream on a property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIOpenStreamOnProperty(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  LPSTREAM * lppStream
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lppStream
Output parameter. Points to an open Win32 IStream interface containing the stream address variable.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIOpenStreamOnProperty function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.


HrMAPIOpenSubfolderEx

The HrMAPIOpenSubfolderEx function opens a subfolder in the store from the hierarchical path name of the folder.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB
Unicode: | Yes

HRESULT HrMAPIOpenSubfolderEx(
  LPMAPIFOLDER lpRootFolder,
  TCHAR chSep,
  LPTSTR lpszFolderPath,
  LPMAPIFOLDER * lppFolder
);

Parameters

lpRootFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing an open folder.
chSep
Input parameter. Folder path separator character.
lpszFolderPath
Input parameter. Folder path.
lppFolder
Output parameter. Points to an IMAPIFolder interface containing the opened folder.

Return Values

See Return Values.

Remarks

Set lpRootFolder to NULL to open the root folder.

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

HrMAPIFindSubfolderEx, HrMAPIOpenFolderEx


HrMAPIProfileExists

The HrMAPIProfileExists function checks for an existing MAPI profile on a gateway.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrMAPIProfileExists(
  LPPROFADMIN lpProfAdmin,
  LPSTR lpszProfileName)
);

Parameters

lpProfAdmin
Input parameter. Points to a MAPI IProfAdmin interface containing the profile object where the profile might be installed.
lpszProfileName
Input parameter. Points to a null-terminated string containing the name of the MAPI profile for the gateway that might be installed.

Return Values

See Return Values.

Remarks

For more information on this function, see Creating a MAPI Profile for a Server Application.

For information on the IProfAdmin interface, see the MAPI Programmer's Reference.

See Also

HrCreateGatewayProfile, HrRemoveProfile


HrMAPISetAddressList

The HrMAPISetAddressList function sets an address list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetAddressList(
  ULONG iEntry,
  ULONG cProps,
  LPSPropValue lpPropValues,
  LPADRLIST lpAdrList
);

Parameters

iEntry
Input parameter. Index of address list entry.
cProps
Input parameter. Count of values in address list entry.
lpPropValues
Input parameter. Points to a MAPI SPropValue structure containing the address list entry.
lpAdrList
Input/output parameter. Points to a MAPI ADRLIST structure containing the address where the address list is stored.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetAddressList function in IADDRESS.C under the EDKMAPI code sample in the Code Samples folder.

For information on the ADRLIST and SPropValue structures, see the MAPI Programmer's Reference.

See Also

HrMAPIAppendAddressList, HrMAPICreateAddressList, HrMAPICreateSizedAddressList


HrMAPISetPropBinary

The HrMAPISetPropBinary function sets a binary property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetPropBinary(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  ULONG cbProp,
  LPVOID lpvProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
cbProp
Input parameter. Number of bytes in property.
lpvProp
Input parameter. Points to property.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetPropBinary function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPISetPropLong, HrMAPISetPropString, HrMAPISetPropSystime


HrMAPISetPropBoolean

The HrMAPISetPropBoolean function sets a Boolean property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetPropBoolean(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  BOOL *fProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
fProp
Intput parameter. Property.

Return Values

See Return Values.

Remarks

For an example of using this function, see Sending a Message. For more information on this function, see the HrMAPISetPropBoolean function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIGetPropBinary, HrMAPIGetPropLong, HrMAPIGetPropString, HrMAPIGetPropSystime


HrMAPISetPropFromFile

The HrMAPISetPropFromFile function sets a property from a file where the property was saved by the HrMAPIGetPropToFile function.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetPropFromFile(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  LPTSTR lpszFilename,
  ULONG *lpcbProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpszFilename
Input parameter. Points to source file name.
lpcbProp
Output parameter. Points to the number of bytes in the property value. This parameter is only required for property types PT_BINARY and PT_STRING8. This parameter is ignored for other property types, so set it to NULL for other property types.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetPropFromFile function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPIGetPropToFile


HrMAPISetPropLong

The HrMAPISetPropLong function sets a long property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI LIB

HRESULT HrMAPISetPropLong(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  ULONG ulProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
ulProp
Input parameter. Property.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetPropLong function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPISetPropBinary, HrMAPISetPropString, HrMAPISetPropSystime


HrMAPISetPropString

The HrMAPISetPropString function sets a string property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetPropString(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  LPVOID lpvProp
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpvProp
Input parameter. Points to property.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetPropString function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPISetPropBinary, HrMAPISetPropLong, HrMAPISetPropSystime


HrMAPISetPropSystime

The HrMAPISetPropSystime function sets a system time property.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetPropSystime(
  LPMAPIPROP lpObj,
  ULONG ulPropTag,
  LPFILETIME lpSystime
);

Parameters

lpObj
Input parameter. Points to a MAPI IMAPIProp interface containing the object.
ulPropTag
Input parameter. Property tag.
lpSystime
Input parameter. Points to a MAPI FILETIME structure containing the time.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetPropSystime function in IPROP.C under the EDKMAPI code sample in the Code Samples folder.

For information on the FILETIME structure and IMAPIProp interface, see the MAPI Programmer's Reference.

See Also

HrMAPISetPropBinary, HrMAPISetPropLong, HrMAPISetPropString


HrMAPISetStreamSize

The HrMAPISetStreamSize function sets the size of a stream.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPISetStreamSize(
  LPSTREAM lpStream,
  ULONG cBytes
);

Parameters

lpStream
Input parameter. Points to an open Win32 IStream interface.
cBytes
Input parameter. Number of bytes in stream.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPISetStreamSize function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrMAPIWriteAttachmentToFile, HrMAPIWriteFileToStream, HrMAPIWriteMemoryToStream, HrMAPIWriteStreamToFile, HrMAPIWriteStreamToMemory


HrMAPIWriteAttachmentToFile

The HrMAPIWriteAttachmentToFile function saves a message attachment to a file.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIWriteAttachmentToFile(
  LPMESSAGE pMessage,
  ULONG iAttach,
  HANDLE hFile
);

Parameters

pMessage
Input parameter. Points to a MAPI IMessage interface containing the attachments.
iAttach
Input parameter. Attachment identifier.
hFile
Input parameter. Handle to file.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIWriteAttachmentToFile function in EDKMAPI.C under the EDKMAPI code sample in Code Samples folder.

For information on the IMessage interface, see the MAPI Programmer's Reference.

See Also

HrMAPISetStreamSize, HrMAPIWriteFileToStream, HrMAPIWriteMemoryToStream, HrMAPIWriteStreamToFile, HrMAPIWriteStreamToMemory


HrMAPIWriteFileToStream

The HrMAPIWriteFileToStream function writes the contents of a file to a stream.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIWriteFileToStream(
  HANDLE hFile,
  LPSTREAM lpStream
);

Parameters

hFile
Input parameter. Handle to file.
lpStream
Output parameter. Points to an open Win32 IStream interface.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIWriteFileToStream function in EDKMAPI.C under the EDKMAPI code sample in Code Samples folder.

See Also

HrMAPISetStreamSize, HrMAPIWriteAttachmentToFile, HrMAPIWriteMemoryToStream, HrMAPIWriteStreamToFile, HrMAPIWriteStreamToMemory


HrMAPIWriteMemoryToStream

The HrMAPIWriteMemoryToStream function saves a number of bytes from a block of memory to a stream.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIWriteMemoryToStream(
  LPSTREAM lpStream,
  ULONG cBytes,
  LPBYTE lpbBytes,
  ULONG * lpcBytesWritten
);

Parameters

lpStream
Input parameter. Points to an open Win32 IStream interface.
cBytes
Input parameter. Number of bytes in memory.
lpbBytes
Input parameter. Points to memory.
lpcBytesWritten
Output parameter. Number of bytes written from stream.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIWriteMemoryToStream function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrMAPISetStreamSize, HrMAPIWriteAttachmentToFile, HrMAPIWriteFileToStream, HrMAPIWriteStreamToFile, HrMAPIWriteStreamToMemory


HrMAPIWriteStreamToFile

The HrMAPIWriteStreamToFile function saves a stream to a file from the file handle.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIWriteStreamToFile(
  LPSTREAM lpStream,
  HANDLE hFile
);

Parameters

lpStream
Input parameter. Points to an open Win32 IStream interface.
hFile
Output parameter. Handle to file.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIWriteStreamToFile function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrMAPISetStreamSize, HrMAPIWriteAttachmentToFile, HrMAPIWriteFileToStream, HrMAPIWriteMemoryToStream, HrMAPIWriteStreamToMemory


HrMAPIWriteStreamToMemory

The HrMAPIWriteStreamToMemory function reads a number of bytes from a stream and saves it to a block of memory.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrMAPIWriteStreamToMemory(
  LPSTREAM lpStream,
  ULONG cBytes,
  LPBYTE lpbBytes,
  ULONG * lpcBytesRead
);

Parameters

lpStream
Input parameter. Points to an open Win32 IStream interface.
cBytes
Input parameter. Number of bytes in memory.
lpbBytes
Input parameter. Points to memory.
lpcBytesRead
Output parameter. Number of bytes read from stream.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrMAPIWriteStreamToMemory function in EDKMAPI.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrMAPISetStreamSize, HrMAPIWriteAttachmentToFile, HrMAPIWriteFileToStream, HrMAPIWriteMemoryToStream, HrMAPIWriteStreamToFile


HrMonCollectAssociationStats

The HrMonCollectAssociationStats function updates the statistic on the current number of gateway connections to the foreign system.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonCollectAssociationStats(
  BOOL fSetNewTotal,
  LONG cAssociations
);

Parameters

fSetNewTotal
Input parameter. Whether the total number of connections or disconnections is reset to cAssociations:
TRUE
The current number of connections or disconnections is reset to cAssociations.
FALSE
The current number of connections or disconnections is summed with cAssociations.
cAssociations
Input parameter. The number of connections or disconnections. Connections are indicated with a positive number; disconnections are indicated with a negative number.

Note The number of current connections can never be less than zero. If you attempt to set the cAssociations parameter to a value that makes the current number of connections is less than zero, HrMonCollectAssociationStats fails, returning E_INVALIDARG.

Return Values

See Return Values.

Remarks

HrMonCollectAssociationStats is typically called each time a new connection is made or an existing connection is broken.

For more information on this function, see Monitor Sampling Functions and the HrMonCollectAssociationStats function in MONITOR.C under the MONITOR code sample in Code Samples folder.

See Also

HrMonCollectMessageXferStats, HrMonCollectNDRStats, HrMonInit, HrMonUninit


HrMonCollectMessageXferStats

The HrMonCollectMessageXferStats function builds statistics on the number of messages traveling through the gateway.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonCollectMessageXferStats(
  DWORD cMessages,
  DWORD cBytes,
  DIRECTIONTYPE dir
);

Parameters

cMessages
Input parameter. Number of messages transferred.
cBytes
Input parameter. Number of bytes transferred.
dir
Input parameter. Direction of the transfer:
DIRECTIONTYPE_IN
The message was received from a foreign system.
DIRECTIONTYPE_OUT
The message was sent to a foreign system.

Return Values

See Return Values.

Remarks

HrMonCollectMessageXferStats builds cumulative statistics on the messages transferred through the gateway.

For more information on this function, see Monitor Sampling Functions and the HrMonCollectMessageXferStats function in MONITOR.C under the MONITOR code sample in the Code Samples folder.

See Also

HrMonCollectAssociationStats, HrMonCollectNDRStats, HrMonInit, HrMonUninit


HrMonCollectNDRStats

The HrMonCollectNDRStats function builds statistics on the number of nondelivery reports (NDRs) produced by the gateway.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonCollectNDRStats(
  DWORD cNDRs,
  DIRECTIONTYPE dir
);

Parameters

cNDRs
Input parameter. Number of NDRs to be added to the current NDR statistics.
dir
Input parameter. Direction the messages were going:

DIRECTIONTYPE_IN

The message was received from a foreign system.

DIRECTIONTYPE_OUT

The message was sent to a foreign system.

Return Values

See Return Values.

Remarks

HrMonCollectNDRStats builds cumulative statistics on the number of NDRs produced by the gateway in each direction. It is typically called each time an NDR is produced.

For more information on this function, see Monitor Sampling Functions and the HrMonCollectNDRStats function in MONITOR.C under the MONITOR code sample in Code Samples folder.

See Also

HrMonCollectAssociationStats, HrMonCollectMessageXferStats, HrMonInit, HrMonUninit


HrMonInit

The HrMonInit function initializes the collection of performance statistics for a gateway.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonInit(
  DWORD dwFlags,
  LPSTR lpszObjectClass,
  LPSTR lpszObjectName,
  DWORD dwObjectTitleOffset,
  DWORD dwObjectDetailLevel,
  LONG dwDefaultCounter,
  DWORD ccdNumberOfCounters,
  LPCOUNTERDEF lpcdCounters
);

Parameters

dwFlags
Input parameter. Reserved for future use; must be zero.
lpszObjectClass
Input parameter. Points to a null-terminated string containing the name of the class of the monitored object. If this parameter is NULL, HrMonInit obtains the object class name from the Parameters\Object Class value in the object's Windows NT registry key. If the Parameters\Object Class value is not present in the object's registry key, HrMonInit uses the lpszObjectName parameter as the object class name.
lpszObjectName
Input parameter. A null-terminated string containing the name of the monitored gateway.
dwObjectTitleOffset
Input parameter. The index of the gateway specified by lpszObjectName in the Windows NT Registry database, where the dwObjectTitleOffset value for the first gateway in the registry database is 0 (zero).
dwObjectDetailLevel
Input parameter. The complexity of the object, as defined in the Win32 WINPERF.H header file:
PERF_DETAIL_NOVICE
Information for beginning users.
PERF_DETAIL_ADVANCED
Information for advanced users.
PERF_DETAIL_EXPERT
Information for expert users.
PERF_DETAIL_WIZARD
Information for system designers.
dwDefaultCounter
Input parameter. The index number of the counter structure in the lpcdCounters array, where the dwDefaultCounter value for the first structure is 0 (zero). HrMonInit places the focus and the cursor on this counter when the object is displayed in the Windows NT performance monitor.
ccdNumberofCounters
Input parameter. The number of counters in lpcdCounters.
lpcdCounters
Input parameter. Points to an array of COUNTERDEF structures. Each COUNTERDEF structure holds information about one of the counters defined for this gateway.

Return Values

See Return Values.

Remarks

HrMonInit is typically called at gateway startup.

HrMonInit resets all of the performance counters in the COUNTERDEF structure pointed to by lpcdCounters.

For more information on this function, see Monitor Sampling Functions and the HrMonInit function in MONITOR.C under the MONITOR code sample in Code Samples folder.

See Also

HrMonCollectAssociationStats, HrMonCollectMessageXferStats, HrMonCollectNDRStats, HrMonUninit


HrMonLockCounters

The HrMonLockCounters function locks the counters against modification by another thread or process.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonLockCounters(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

Use HrMonLockCounters to gain exclusive access to the counters before modifying a user-defined counter.

When a user-defined counter is specified in a COUNTERDEF structure in the call to HrMonInit, a pointer to the actual user-defined counter is returned to the user. This user-defined counter is located in a section of memory that is shared between multiple processes. HrMonLockCounters and HrMonUnlockCounters synchronize access to these counters. For example:

_int64 *UserCounter1, *UserCounter2;
...
HrMonLockCounters();
*UserCounter1++;
*UserCounter2 += cBytes;
HrMonUnlockCounters();
...

After calling HrMonLockCounters you must always call HrMonUnlockCounters. Otherwise, the gateway and the Windows NT Performance Monitor can hang. To improve performance, don't put time-consuming processing between the calls to HrMonLockCounters and HrMonUnlockCounters.

For more information on this function, see Monitor Sampling Functions and the HrMonLockCounters function in MONITOR.C under the MONITOR code sample in Code Samples folder.

See Also

HrMonUnlockCounters


HrMonUninit

The HrMonUninit function closes down the monitoring of the gateway.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonUninit(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

HrMonUninit is typically called at gateway shutdown.

For more information on this function, see Monitor Sampling Functions and the HrMonUninit function in MONITOR.C under the MONITOR code sample in Code Samples folder.

See Also

HrMonInit


HrMonUnlockCounters

The HrMonUnlockCounters function releases the counters, which were locked by a call to the HrMonLockCounters function, to allow modification by another thread or process.

Quick Info

Header file: | MONITOR.H
Library: | MONITOR.LIB

HRESULT HrMonUnlockCounters(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

Call HrMonUnlockCounters when you are through accessing user-defined counters.

For more information on this function, see Monitor Sampling Functions and the HrMonUnlockCounters function in MONITOR.C under the MONITOR code sample in Code Samples folder.

See Also

HrMonLockCounters


HrNDRAddToFailedRecipList

The HrNDRAddToFailedRecipList function appends a recipient entry to the list of failed recipients.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrNDRAddToFailedRecipList(
  ULONG cFailedProps,
  LPSPropValue lpFailedProps,
  LPADRLIST *  lppAdrList
);

Parameters

cFailedProps
Input parameter. Count of failed properties in lpFailedProps.
lpFailedProps
Input parameter. Points to an array of MAPI SPropValue structures, which contain the failed properties.
lppAdrList
Input/output parameter. Points to an array of MAPI ADRLIST structures, which contain the addresses.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrNDRAddToFailedRecipList function in GWREPORT.C under the GWREPORT code sample in Code Samples folder.

For information on the ADRLIST and SPropValue structures, see the MAPI Programmer's Reference.

See Also

HrNDRGetFailedRecipList


HrNDRCreate

The HrNDRCreate function creates a nondelivery report.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrNDRCreate(
  LPADRBOOK lpAdrBook,
  LPMAPIFOLDER lpFolder,
  LPMESSAGE lpMessage,
  LPADRLIST lpAdrList,
  ULONG cProps,
  LPSPropValue lpProps,
  LPMESSAGE * lppReport
);

Parameters

lpAdrBook
Input parameter. Points to a MAPI IAddrBook interface containing the address book.
lpFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the folder where the message originated.
lpMessage
Input parameter. Points to a MAPI IMessage interface containing the original message.
lpAdrList
Input parameter. Points to an array of MAPI ADRLIST structures, which contain the addresses where the message was sent.
cProps
Input parameter. Count of properties in lpProps.
lpProps
Input parameter. Points to an array of MAPI SPropValue structures, which contain the NDR properties.
lppReport
Output parameter. Points to a MAPI IMessage interface containing the NDR report.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrNDRCreate function in GWREPORT.C under the GWREPORT code sample in Code Samples folder.

For information on the ADRLIST structure, IAddrBook interface, IMAPIFolder interface, IMessage interface, and SPropValue structure, see the MAPI Programmer's Reference.


HrNDRCreateFailedRecipList

The HrNDRCreateFailedRecipList function creates an empty list of failed recipients.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrNDRCreateFailedRecipList(
  LPADRLIST * lppAdrList
);

Parameters

lppAdrList
Output parameter. Points to a MAPI ADRLIST structure containing the empty address list.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrNDRCreateFailedRecipList function in GWREPORT.C under the GWREPORT code sample in Code Samples folder.

For information on the ADRLIST structure, see the MAPI Programmer's Reference.

See Also

HrNDRGetFailedRecipList


HrNDRGetFailedProps

The HrNDRGetFailedProps function obtains the NDR properties from the original message.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrNDRGetFailedProps(
  LPMESSAGE lpMessage,
  ULONG * lpcProps,
  LPSPropValue * lppProps
);

Parameters

lpMessage
Input parameter. Points to a MAPI IMessage interface containing the original message.
lpcProps
Output parameter. Count of properties in lppProps.
lppProps
Output parameter. Points to a MAPI SPropValue array, which contain the NDR properties.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrNDRGetFailedProps function in GWREPORT.C under the GWREPORT code sample in Code Samples folder.

For information on the IMessage interface and SPropValue structure, see the MAPI Programmer's Reference.


HrNDRGetFailedRecipList

Th HrNDRGetFailedRecipList function creates an entry for a failed recipient.

Quick Info

Header file: | GWREPORT.H
Library: | GWREPORT.LIB

HRESULT HrNDRGetFailedRecipList(
  LPADRENTRY lpAdrEntry,
  ULONG cExtraProps,
  LPSPropValue lpExtraProps,
  ULONG * lpcFailedProps,
  LPSPropValue * lppFailedProps
);

Parameters

lpAdrEntry
Input parameter. Points to a MAPI ADRENTRY structure containing the address entry.
cExtraProps
Input parameter. Count of extra properties in lpExtraProps.
lpExtraProps
Input parameter. Points to an array of MAPI SPropValue structures, which contain the extra properties.
lpcFailedProps
Output parameter. Count of failed properties in lppFailedProps.
lppFailedProps
Output parameter. Points to an array of SPropValue structures, which contain the failed properties.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrNDRGetFailedRecipList function in GWREPORT.C under the GWREPORT code sample in Code Samples folder.

For information on the ADRENTRY and SPropValue structures, see the MAPI Programmer's Reference.

See Also

HrNDRCreateFailedRecipList


HrOpenExchangePrivateStore

The HrOpenExchangePrivateStore function locates the primary user information store provider.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrOpenExchangePrivateStore(
  LPMAPISESSION phSession,
  LPMDB * lppMDB
);

Parameters

phSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session.
lppMDB
Output parameter. Points to a MAPI IMsgStore interface containing the information store.

Return Values

See Return Values.

Remarks

If there are two or more information store providers available, HrOpenExchangePrivateStore returns a pointer to the first one it encounters.

For more information on this function, see Opening a Private Information Store.

For information on the IMAPISession and IMsgStore interfaces, see the MAPI Programmer's Reference.


HrOpenExchangePublicFolders

The HrOpenExchangePublicFolders function opens the root of the public folder hierarchy in the public information store.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrOpenExchangePublicFolders(
  LPMDB lpPubStore,
  LPMAPIFOLDER * lppRootFolder
);

Parameters

lpPubStore
Input parameter. Points to a MAPI IMsgStore interface containing an open information store.
lppRootFolder
Output parameter. Points to a MAPI IMAPIFolder interface containing the root of the public folder in the public information store.

Return Values

See Return Values.

Remarks

For more information on this function, see Opening an Existing Public Folder.

For information on the IMAPIFolder and IMsgStore interfaces, see the MAPI Programmer's Reference.


HrOpenExchangePublicStore

The HrOpenExchangePublicStore function retrieves a pointer to the public information store provider.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrOpenExchangePublicStore(
  LPMAPISESSION lphSession,
  LPMDB * lppMDB
);

Parameters

lphSession
Input parameter. Points to a MAPI IMAPISession interface containing the open session handle.
lppMDB
Output parameter. Points to a MAPI IMsgStore interface containing the information store opened.

Return Values

See Return Values.

Remarks

For more information on this function, see Opening a Public Information Store.

For information on the IMAPISession and IMsgStore interfaces, see the MAPI Programmer's Reference.

See Also

FIsPublicStore


HrOpenFolderMetrics

The HrOpenFolderMetrics function prepares a folder for folder snapshot calculations.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

HRESULT HrOpenFolderMetrics(
  LPMAPIFOLDER lpFolder,
  HFLDMTRC * phFolderMetric
);

Parameters

lpFolder
Input parameter. Points to an IMAPIFolder interface containing the folder to be prepared.
phFolderMetric
Output parameter. Points to the handle to the calculations for the folder.

Return Values

See Return Values.

Remarks

HrOpenFolderMetrics is typically called at gateway startup.

For more information on this function, see Folder Snapshot Functions.

For information on the IMAPIFolder interface, see the MAPI Programmer's Reference.

See Also

CloseFolderMetrics, HrGetFolderMetrics


HrOpenSessionObject

The HrOpenSessionObject function retrieves a MAPI IMAPIProp interface for the current session object.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrOpenSessionObject(
  LPMAPISESSION lpSession,
  LPMAPIPROP * lppCurrentObject
);

Parameters

lpSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session.
lppCurrentObject
Output parameter. Points to a MAPI IMAPIProp interface containing the current object.

Return Values

See Return Values.

Remarks

For more information on this function, see Using the Configuration Functions.

For information on the IMAPIProp and IMAPISession interfaces, see the MAPI Programmer's Reference.


HrOpenSiteContainer

The HrOpenSiteContainer function retrieves a MAPI IMAPIProp interface for a site object.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrOpenSiteContainer(
  LPMAPISESSION lpSession,
  LPMAPIPROP * lppSite
);

Parameters

lpSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session.
IppSite
Output parameter. Points to a IMAPIProp interface containing the current site.

Return Values

See Return Values.

Remarks

For more information on this function, see Using the Configuration Functions.

For information on the IMAPIProp and IMAPISession interfaces, see the MAPI Programmer's Reference.


HrOpenSiteContainerAddressing

The HrOpenSiteContainerAddressing function retrieves a MAPI IMAPIProp interface for a site-addressing object.

Quick Info

Header file: | EDKCFG.H
Library: | EDKCFG.LIB

HRESULT HrOpenSiteContainerAddressing(
  LPMAPISESSION lpSession,
  LPMAPIPROP * lppSiteAddressing
);

Parameters

lpHeader
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session.
lppSiteAddressing
Output parameter. Points to a MAPI IMAPIProp interface containing the current site addressing object.

Return Values

See Return Values.

Remarks

For more information on this function, see Using the Configuration Functions.

For information on the IMAPIProp and IMAPISession interfaces, see the MAPI Programmer's Reference.


HrRemoveAddressTemplate

The HrRemoveAddressTemplate function deletes an address template from a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveAddressTemplate(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName,
  LPSTR lpszAddressType,
  LPSTR lpszLanguage
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server from which the address template is removed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site from which the address template is removed.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the address template.
lpszAddressType
Input parameter. Points to a null-terminated string containing the address type supported by the template.
lpszLanguage
Input parameter. Points to a null-terminated string containing the language supported by the template.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrRemoveAddressTemplate function in EXCHINST.C under the EXCHINST code sample in Code Samples folder.

See Also

HrAddressTemplateExists, HrInstallAddressTemplate


HrRemoveAddressType

The HrRemoveAddressType function deletes an address type from a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveAddressType(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName,
  LPSTR lpszMachineType
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server from which the address type is removed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site from which the address type is removed.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the address type.
lpszMachineType
Input parameter. Points to a null-terminated string containing the computer type, such as i386.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrRemoveAddressType function in EXCHINST.C under the EXCHINST code sample in Code Samples folder.

See Also

HrAddressTypeExists, HrGetAddressTypeVersion, HrInstallAddressType


HrRemoveAdminExtension

The HrRemoveAdminExtension function deletes an Administrator extension program from a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveAdminExtension(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName,
  LPSTR lpszMachineType
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the server from which the Administrator extension program is removed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site from which the Administrator extension program is removed.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the Administrator extension program.
lpszMachineType
Input parameter. Points to a null-terminated string containing the computer type, such as i386.

Return Values

See Return Values.

Remarks

For more information on this function, see Installing the Administrator Extension DLL.

See Also

HrAdminExtensionExists, HrGetAdminExtensionVersion, HrInstallAdminExtension


HrRemoveGateway

The HrRemoveGateway function deletes a gateway from a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveGateway(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszCommonName
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server from which the gateway is removed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site from which the gateway is removed.
lpszCommonName
Input parameter. Points to a null-terminated string containing the common name of the gateway.

Return Values

See Return Values.

Remarks

For more information on this function, see Removing a Gateway.

See Also

HrGatewayExists, HrInstallGateway, HrRemoveMailboxAgent, HrRemoveRegistry, HrRemoveService, HrRemoveServicePerfMon


HrRemoveGatewayProxy

The HrRemoveGatewayProxy function deletes a site proxy address from a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveGatewayProxy(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszProxy
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server from which the site proxy address is removed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name of the site from which the site proxy address is removed.
lpszProxy
Input parameter. Points to a null-terminated string containing the site proxy address that is removed.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrRemoveGatewayProxy function in EXCHINST.C under the EXCHINST code sample in Code Samples folder.

See Also

HrInstallGatewayProxy


HrRemoveMailboxAgent

The HrRemoveMailboxAgent function deletes a mailbox agent from a site.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveMailboxAgent(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszRDN
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the name of the server from which the mailbox agent is removed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name (DN) of the site from which the mailbox agent is removed.
lpszRDN
Input parameter. Points to a null-terminated string containing the relative distinguished name (RDN) of the mailbox agent.

Return Values

See Return Values.

Remarks

For more information on this function, see Removing a Server Application.

See Also

HrCreateMailboxAgentProfile, HrInstallMailboxAgent, HrMailboxAgentExists, HrRemoveGateway, HrRemoveProfile, HrRemoveRegistry, HrRemoveService, HrRemoveServicePerfMon


HrRemoveMessageConverter

The HrRemoveMessageConverter function deletes a message conversion DLL.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST LIB

HRESULT HrRemoveMessageConverter(
  LPCSTR lpszConverter
);

Parameters

lpszConverter
Input parameter. Points to a null-terminated string containing the name of the message converter DLL to remove.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrRemoveMessageConverter function in EXCHINST.C under the EXCHINST code sample in Code Samples folder.

See Also

HrInstallMessageConverter


HrRemoveProfile

The HrRemoveProfile function deletes a MAPI profile.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveProfile(
  LPSTR pszProfileName
);

Parameters

pszProfileName
Input parameter. Points to a null-terminated string containing the name of the MAPI profile to remove.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrRemoveProfile function in EXCHPROF.C under the EXCHINST code sample in Code Samples folder.

See Also

HrCreateGatewayProfile, HrMAPIProfileExists, HrRemoveMailboxAgent


HrRemoveRegistry

The HrRemoveRegistry function removes the Windows NT Registry entries for the service.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveRegistry(
  LPCSTR lpszServiceName
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service.

Return Values

See Return Values.

Remarks

For more information on this function, see Removing a Server Application.

See Also

HrRemoveGateway, HrRemoveMailboxAgent, HrRemoveService, HrRemoveServicePerfMon


HrRemoveService

The HrRemoveService function deletes a service of Windows NT Server.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveService(
  LPCSTR pszServiceName
);

Parameters

pszServiceName
Input parameter. Points to a null-terminated string containing the name of the service to remove.

Return Values

See Return Values.

Remarks

For more information on this function, see Removing a Server Application.

See Also

HrInstallService, HrRemoveGateway, HrRemoveMailboxAgent, HrRemoveRegistry, HrRemoveServicePerfMon


HrRemoveServicePerfMon

The HrRemoveServicePerfMon function deletes a Windows NT Performance Monitor.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrRemoveServicePerfMon(
  LPSTR lpszServiceName,
  LPSTR lpszClassName,
  BOOL * lpfUnloadCounters
);

Parameters

lpszServiceName
Input parameter. Points to a null-terminated string containing the name of the service that the Windows NT performance monitor was monitoring.
lpszClassName
Input parameter. Points to a null-terminated string containing the class of service that the Windows NT performance monitor was monitoring.
lpfUnloadCounters
Output parameter. Whether the performance counters were unloaded:
TRUE
The counters were unloaded.
FALSE
The counters were not unloaded.

Return Values

See Return Values.

Remarks

For more information on this function, see Removing a Server Application.

See Also

HrInstallServicePerfMon, HrRemoveGateway, HrRemoveMailboxAgent, HrRemoveRegistry, HrRemoveService


HrRestoreEnd

The HrRestoreEnd function cleans up after a restore operation has been performed.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

HRESULT HrRestoreEnd(
  HBC hbcRestoreContext
);

Parameters

hbcRestoreContext
Input parameter. Client-side context handle of the restore.

Return Values

See Return Values.

Remarks

The HrRestoreEnd function closes outstanding binding handles and does whatever is necessary to clean up after a restore attempt.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrRestorePrepare


HrRestoreGetDatabaseLocations

The HrRestoreGetDatabaseLocations function obtains the database locations for the server and service.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrRestoreGetDatabaseLocations(
  HBC hbcBackupContext,
  LPSTR * ppszDatabaseLocationList,
  LPDWORD pcbSize
);

Parameters

hbcBackupContext
Input parameter. The client-side context handle of the restore.
ppszDatabaseLocationList
Output parameter. The UNC paths of the database files.
List Element | Directory Context | IS Context
First | System Database | System Database
Second | Log Location | Log Location
Third | Directory Database | Private IS
Fourth | None | Public IS
pcbSize
Output parameter. The size of the list of database locations.

Return Values

See Return Values.

Remarks

For more information on this function, see Backing Up and Restoring Data.

See Also

HrRestorePrepare


HrRestorePrepare

The HrRestorePrepare function connects to a remote Microsoft Exchange Server database and prepares it for restore.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrRestorePrepare(
  LPTSTR szServerName,
  LPTSTR szServiceAnnotation,
  HBC * phbcRestoreContext
);

Parameters

szServerName
Input parameter. Name of the server to restore. Preceding backslashes are optional. An example of a server name is \\server1.

Note The server name cannot contain an underscore.

szServiceAnnotation
Input parameter. The database to restore. Possible choices are EDBBACK_MDB_DATABASE and EDBBACK_DIRECTORY_DATABASE.
phbcBackupContext
Output parameter. The client-side context handle of the restore.

Return Values

See Return Values.

Remarks

The HrRestorePrepare function requires that the caller is a member of the Administrators group on the server.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrRestoreEnd


HrRestoreRegister

The HrRestoreRegister function registers a restore operation, interlocking all subsequent restore operations and preventing the restore target from starting until HrRestoreRegisterComplete is called.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrRestoreRegister(
  HBC hbcRestoreContext,
  LPTSTR szCheckpointFilePath,
  LPTSTR szLogPath,
  EDB_RSTMAP rgrstmap[],
  C crstmap,
  LPTSTR szBackupLogPath,
  ULONG genLow,
  ULONG genHigh
);

Parameters

hbcRestoreContext
Input parameter. The client-side context handle of the restore.
szCheckpointFilePath
Input parameter. The path to the checkpoint file. Typically the same as the system database path. If this parameter is NULL, HrRestoreRegister uses the checkpoint file derived from the backup logs.
szLogPath
Input parameter. The path to the log files on the disk. If the path leads to an empty directory, new log files are generated there. This parameter cannot be NULL.
rgrstmap[]
Input parameter. This is an EDB_RSTMAP structure containing the old and new paths for each database. There should be one row (of two elements) for each database. For the directory there is a row for the system database and a row for the directory database. For the information store, if you are restoring both the private and public databases, there is a row for each of the system, private, and public databases. If you are restoring just the private or just the public databases, there is a row for the system and a row for the (private or public) database. The order of the rows does not matter. The crstmap parameter specifies the number of rows.
crstmap
Input parameter. A LONG specifying the number of rows in rgrstmap.
szBackupLogPath
Input parameter. The path to the directory where the log files are restored. This parameter can be the same as the szLogPath parameter. HrRestoreRegister also puts the patch file is put into this directory. This parameter cannot be NULL.
genLow
Input parameter. The lowest log file number that is restored. This is a hexadecimal number in the range from 0x00000 to 0xFFFFF.
genHigh
Input parameter. The highest log file number that is restored. This is a hex number in the range from 0x00000 to 0xFFFFF.

Return Values

See Return Values.

Remarks

For more information on this function, see Backing Up and Restoring Data.

See Also

HrRestoreRegisterComplete


HrRestoreRegisterComplete

The HrRestoreRegisterComplete function completes a restore operation, allowing subsequent restore operations.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB

HRESULT HrRestoreRegisterComplete(
  HBC hbcRestoreContext,
  HRESULT hrRestoreState
);

Parameters

hbcRestoreContext
Input parameter. The client-side context handle of the restore.
hrRestoreState
Output parameter. Whether the restored database can be restarted
hrNone
The service can restart.

Otherwise, the service can not restart.

Return Values

See Return Values.

Remarks

HrRestoreRegisterComplete allows the restore target to start if hrRestoreState is hrNone. Otherwise, HrRestoreRegisterComplete prevents the restore target from restarting.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrRestoreRegister


HrRestrictionToString

The HrRestrictionToString function produces a string from a MAPI SRestriction structure.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrRestrictionToString(
  LPSRestriction lpRestriction,
  LPSTR FAR * lppszString
);

Parameters

lpRestriction
Input parameter. Points to an SRestriction structure containing the restriction to convert.
lppszString
Output parameter. Points to the address of the string containing the converted restriction.

Return Values

See Return Values.

Remarks

The HrRestrictionToString function has a limited capability to convert an SRestriction structure to a string. See the conditional expression grammar used for the HrStringToRestriction function For more information on this function, see the HrRestrictionToString function in RULECLS.CPP under the RULECLS code sample in Code Samples folder.

For information on the SRestriction structure, see the MAPI Programmer's Reference.

See Also

HrStringToRestriction


HrRTFCompressedToText

The HrRTFCompressedToText function converts the body of a message from compressed RTF to its ANSI equivalent.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrRTFCompressedToText(
  LPMESSAGE lpMsg,
  LPSTREAM pText,
  ULONG * pcb
);

Parameters

lpMsg
Input parameter. Points to a MAPI IMessage interface containing the MAPI message.
pText
Input parameter. Points to an open Win32 IStream interface where the text is copied.
pcb
Output parameter. Number of bytes copied to stream.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrRTFCompressedToText function in EDKRTF.C under the EDKUTILS code sample in theCode Samples folder.

See Also

HrTextFromCompressedRTFStreamEx, HrTextToRTFCompressed, RTFSYNCINFO


HrSendProgManCommand

The HrSendProgManCommand function sends one or more commands to the Program Manager.

Quick Info

Header file: | EDKSETUP.H
Library: | EDKSETUP.LIB
Unicode: |

HRESULT HrSendProgManCommand(
  LPDWORD lpIdInst,
  LPSTR lpszCommand
);

Parameters

lpIdInst
Input parameter. Points to instance identifier.
lpszCommand
Input parameter. Points to command string.

Return Values

See Return Values.


HrServiceConfirmStop

The HrServiceConfirmStop function informs the server that the application has stopped.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceConfirmStop(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrServiceConfirmStop function in WINWRAP.C under the WINWRAP code sample in the Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

FIsService, FServiceReportStatus, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceGetArgv

The HrServiceGetArgv function obtains the command line arguments as an array of strings (argv[]).

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceGetArgv(
  DWORD * lpdwArgc,
  LPTSTR ** lppszArgv
);

Parameters

lpdwArgc
Output parameter. Points to the number of arguments in the argv[] array.
lppszArgv
Output parameter. Points to the array of argument string pointers.

Return Values

See Return Values.

Remarks

The HrServiceGetArgv function returns the number of arguments in the argv[] array and a pointer to this array. This function can be used by any thread to get the service argv[] after the service of Windows NT Server has been started.

For more information on this function, see the HrServiceGetArgv function in WINWRAP.C under the WINWRAP code sample in Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceGetName

The HrServiceGetName function obtains the name of a service of Windows NT Server.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceGetName(
  LPTSTR lpszName
);

Parameters

lpszName
Output parameter. Points to the buffer to receive the service name. This buffer must be at least one byte longer than MAX_SERVICE_NAME_LENGTH.

Return Values

See Return Values.

Remarks

The HrServiceGetName function can be used by any thread to get the name of the Windows NT Server service after it has been started.

For more information on this function, see the HrServiceGetName function in WINWRAP.C under the WINWRAP code sample in Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceProcessControl

The HrServiceProcessControl function checks for service control.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceProcessControl(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrServiceProcessControl function in WINWRAP.C under the WINWRAP code sample in the Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceShutdown

The HrServiceShutdown function is implemented by the server application developer to shut down a service of Windows NT Server.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceShutdown(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Remarks

The Microsoft Exchange Server Code Samples folder contains two implementations of the HrServiceShutdown function:

  • In SMBAGENT.C under the SMBAGENT code sample
  • In WINWRAP.C under the WINWRAP code sample

For more information on this function, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceStartup

The HrServiceStartup function is implemented by the server application developer to initialize a service of Windows NT Server.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceStartup(
  HINSTANCE hInstance,
  HINSTANCE hPrevInstance,
  HWND hwndMainWindow,
  LPSTR pszCmdLine
);

Parameters

hInstance
Input parameter. Handle of current instance of the service.
hPrevInstance
Input parameter. Handle of previous instance of the service.
hwndMainWindow
Input parameter. Handle to Main window.
pszCmdLine
Input parameter. Points to command line.

Return Values

See Return Values.

Remarks

The Microsoft Exchange Server Code Samples folder contains two implementations of the HrServiceStartup function:

  • In GWMAIN.C under the GWMAIN code sample.
  • In SMGAGENT.C under the SMBAGENT code sample.

For more information on this function, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceWaitForContinue

The HrServiceWaitForContinue function waits for service control after the service has been started.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceWaitForContinue(
  DWORD dwTimeout,
  EDK_SERVICE_CONTROL_T * pedksc
);

Parameters

dwTimeout
Input parameter. The timeout interval (in milliseconds) to wait for service control before returning.
pedksc
Output parameter. Points to where one of the following service control values is returned:
EDK_SC_NONE
No change.
EDK_SC_CONTINUE
Continue the service.
EDK_SC_STOP
Stop the service.

Return Values

See Return Values.

Remarks

HrServiceWaitForContinue can be used by any thread, after the service has started, to wait for one of the following service control values: EDK_SC_NONE, EDK_SC_CONTINUE, or EDK_SC_STOP.

For more information on this function, see the HrServiceWaitForContinue function in WINWRAP.C under the WINWRAP code sample in Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceWaitForControl

The HrServiceWaitForControl function waits for service control after the service has been started.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceWaitForControl(
  DWORD dwTimeout,
  EDK_SERVICE_CONTROL_T * pedksc
);

Parameters

dwTimeout
Input parameter. The timeout interval, in milliseconds, to wait for service control before returning.
pedksc
Output parameter. Points to where one of the following service control values is returned:
EDK_SC_NONE
No change.
EDK_SC_PAUSE
Pause the service.
EDK_SC_CONTINUE
Continue the service.
EDK_SC_STOP
Stop the service.

Return Values

See Return Values.

Remarks

HrServiceWaitForControl can be used by any thread, after the service has started, to wait for one of the following service control values: EDK_SC_NONE, EDK_SC_PAUSE, EDK_SC_CONTINUE, or EDK_SC_STOP.

For more information on this function, see the HrServiceWaitForControl function in WINWRAP.C under the WINWRAP code sample in Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, ServiceStop


HrServiceWaitForStop

The HrServiceWaitForStop function waits for service control after the service has been started.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HRESULT HrServiceWaitForStop(
  DWORD dwTimeout,
  EDK_SERVICE_CONTROL_T * pedksc
);

Parameters

dwTimeout
Input parameter. The timeout interval (in milliseconds) to wait for service control before returning.
pedksc
Output parameter. Points to where one of the following service control values is returned:
EDK_SC_NONE
No change.
EDK_SC_STOP
Stop the service.

Return Values

See Return Values.

Remarks

After the service has started, HrServiceWaitForStop can be used by any thread to wait for one of the following service control values: EDK_SC_NONE, or EDK_SC_STOP.

For more information on this function, see the HrServiceWaitForStop function in WINWRAP.C under the WINWRAP code sample in the Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HServiceCreateThread, ServiceMain, ServiceStop


HrSetCurrentBackupLog

The HrSetCurrentBackupLog function sets the last log number that was backed up.

Quick Info

Header file: | EDBBCLI.H
Library: | EDBBCLI.LIB
Unicode: | Yes

HRESULT HrSetCurrentBackupLog(
  LPTSTR szServerName,
  LPTSTR szBackupAnnotation,
  DWORD dwCurrentLog
);

Parameters

szServerName
Input parameter. The name of the server to backup. Preceding backslashes are optional. An example of a server name is \\server1.

Note The server name cannot contain an underscore.

szBackupAnnotation
Input parameter. The database to set log on. Possible choices are EDBBACK_MDB_DATABASE and EDBBACK_DIRECTORY_DATABASE.
dwCurrentLog
Input parameter. The last log number backed up. Set dwCurrentLog to BACKUP_DISABLE_INCREMENTAL to prevent incremental backups until a full backup is performed (see Preventing an Incremental Backup Until a Full Backup Is Performed).

Return Values

See Return Values.

Remarks

The HrSetCurrentBackupLog function does not normally need to be called. The backup functions automatically determine and set the last log number backed up. Use HrSetCurrentBackupLog to prevent another incremental backup from succeeding until a full backup is performed. For example, after running a defragmentation on the directory or information store in the Microsoft Exchange Server Administrator program, no further incremental backups are allowed until a full backup is performed.

For more information on this function, see Backing Up and Restoring Data.

See Also

HrRestoreRegister


HrSetGatewayBit

The HrSetGatewayBit function sets the gateway bit on a server.

Quick Info

Header file: | EXCHINST.H
Library: | EXCHINST.LIB

HRESULT HrSetGatewayBit(
  LPSTR lpszServer,
  LPSTR lpszSiteDN,
  LPSTR lpszServerName
);

Parameters

lpszServer
Input parameter. Points to a null-terminated string containing the server where the gateway is installed.
lpszSiteDN
Input parameter. Points to a null-terminated string containing the distinguished name (DN) of the site.
lpszServerName
Input parameter. Points to a null-terminated string containing the name of the server.

Return Values

See Return Values.

Remarks

For more information on this function, see Setting the Server Heuristics Attribute.

See Also

HrInstallGateway


HrStrAToStrA

The HrStrAToStrA function creates a copy of an ANSI string as an ANSI string using the MAPI MAPIAllocateBuffer function.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB
Unicode: | No (see Remarks)

HRESULT HrStrAToStrA(
  LPSTR lpszSource,
  LPSTR * lppszDest
);

Parameters

lpszSource
Input parameter. ANSI source string.
lppszDest
Output parameter. ANSI destination string.

Return Values

See Return Values.

Remarks

The HrStrAToStrA function is useful for creating macros involving TCHAR strings. You must release the destination string buffer with the MAPI MAPIFreeBuffer function before your routine exits.

When Unicode is undefined, the following macros are defined as this function:

HrStrToStr( LPTSTR lpszSource, LPTSTR * lppszDest )

HrStrAToStr( LPSTR lpszSource, LPTSTR * lppszDest )

HrStrToStrA( LPTSTR lpszSource, LPSTR * lppszDest )

For information about the MAPIAllocateBuffer and MAPIFreeBuffer functions, see the MAPI Programmer's Reference.

See Also

HrStrAToStrW, HrStrTokAll, HrStrWToStrA, HrStrWToStrW


HrStrAToStrW

The HrStrAToStrW function creates a copy of an ANSI string as a Unicode string using the MAPI MAPIAllocateBuffer function.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB
Unicode: | (see Remarks)

HRESULT HrStrAToStrW(
  LPSTR lpszSource,
  LPWSTR * lppwszDest
);

Parameters

lpszSource
Input parameter. Points to an ANSI source string.
lppwszDest
Output parameter. Points to a pointer to the Unicode destination string.

Return Values

See Return Values.

Remarks

The HrStrAToStrW function is useful for creating macros involving TCHAR strings. You must release the destination string buffer with the MAPI MAPIFreeBuffer function before your routine exits.

When Unicode is defined, the following macros are defined as this function:

HrStrAToStr( LPSTR lpszSource, LPTSTR * lppszDest )

When Unicode is undefined, the following macros are defined as this function:

HrStrAToStrW( LPSTR lpszSource, LPWSTR * lppwszDest )

For information about the MAPIAllocateBuffer and MAPIFreeBuffer functions, see the MAPI Programmer's Reference.

See Also

HrStrAToStrA, HrStrTokAll, HrStrWToStrA, HrStrWToStrW


HrStringToAction

The HrStringToAction function produces an ACTION structure from a string.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrStringToAction(
  LPMAPISESSION lpSession,
  LPMAPIFOLDER lpFolder,
  LPSTR lpszString,
  LPVOID lpObject,
  LPACTION lpAction
);

Parameters

lpSession
Input parameter. Points to a MAPI IMAPISession interface containing the MAPI session.
lpFolder
Input parameter. Points to a MAPI IMAPIFolder interface containing the folder. You must open this folder with MAPI_MODIFY access.
lpszString
Input parameter. Points to the string containing the action.
lpObject
Input parameter. Points to an existing buffer allocated by the MAPI MAPIAllocateBuffer function. You must release this buffer when you are finished with it with a call to the MAPI MAPIFreeBuffer function.
lpAction
Input/output parameter. Points to the ACTION structure that holds the action to which the string (lpszString) is converted.

Return Values

See Return Values.

Remarks

You must allocate the space for the lpAction parameter. The best method of allocating this space is to call the MAPI MAPIAllocateMore function with a reference to the parent object's ACTION structure.

For information about the IMAPIFolder and IMAPISession interfaces, and the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer functions, see the MAPI Programmer's Reference.

For more information on this function, see Creating a Rule.

See Also

HrActionToString


HrStringToRestriction

The HrStringToRestriction function creates a copy of a MAPI SRestriction structure from a restriction condition.

Quick Info

Header file: | RULECLS.H
Library: | RULECLS.LIB

HRESULT HrStringToRestriction(
  LPSTR lpszString,
  LPVOID lpObjec t,
  LPSRestriction FAR * lppRestriction
);

Parameters

lpszString
Input parameter. Condition string specifying restriction to be generated.
lpObject
Input parameter. Points to an existing MAPI buffer allocated by the MAPI MAPIAllocateBuffer function, or NULL if the returned structure is to be allocated by HrStringToRestriction.
lppRestriction
Output parameter. Points to the MAPI SRestriction structure containing the restriction.

Return Values

See Return Values.

If HrStringToRestriction fails, lppRestriction is NULL.

Remarks

The conditional expression grammar used for HrStringToRestriction is as follows:

lpszString parameter:

Condition ::= SimpleCondition | Condition "|" Condition | Condition "&" Condition | "(" Condition ")" | "!" Condition

"|" is the logical OR operator.

"&" is the logical AND operator.

"!" is the logical NOT operator.

Conditional expressions are evaluated from left to right with "|" and "&" having equal precedence. "!" is a unary operator that applies to the operand to its immediate right.

SimpleCondition ::= StringCondition | NumericCondition

StringCondition ::= StringTag "=" StringLiteral | StringTag "#" StringLiteral | StringTag "}" StringLiteral

"=" is the equality operator.

"#" is the inequality operator.

"}" is the contains operator (a "}" b means a contains b).

NumericCondition ::= NumericTag "=" NumericLiteral | NumericTag "#" NumericLiteral | NumericTag ">" NumericLiteral | NumericTag "<" NumericLiteral

The meaning of the NumericCondition operators should be evident.

StringTag ::= PR_xxxx for a property with a string (PT_STRING8) value | "[S" HexNumber "]"

NumericTag ::= PR_xxxx for a property with a numeric (PT_LONG) value | "[S" HexNumber "]"

NumericLiteral ::= DecimalNumber

StringLiteral ::= String enclosed in quotes ("xxx").

HexNumber ::= HexDigit...

DecimalNumber ::= DecimalDigit... | +DecimalDigit... | -DecimalDigit...

If you allocate space for the lpObect buffer using the MAPIAllocateBuffer function, you must free the buffer using the MAPI MAPIFreeBuffer function.

For more information on this function, see Creating a Rule.

For information about the MAPIAllocateBuffer and MAPIFreeBuffer functions and the SRestriction structure, see the MAPI Programmer's Reference.

See Also

HrRestrictionToString


HrStrstriW

The HrStrstriW function determines whether one string is a prefix of another.

Quick Info

Header file: | CONVREGH.H
Library: | CONVREGH.LIB
Unicode: | Exclusively

HRESULT HrStrstriW(
  LPCWSTR pszSubString,
  LPCWSTR pszString
);

Parameters

pszSubString
Input parameter. Points to the Unicode substring to be checked for within the string contained in pszString.
pszString
Input parameter. Points to the Unicode string that might contain the substring contained in pszSubString.

Return Values

See Return Values.

Remarks

The HrStrstriW function is case-insensitive, i.e., both the string and substring are converted to uppercase before the substring search is performed.

For more information on this function, see the HrStrstriW function in CONVREGH.CPP under the MESGXLAT code sample in the Code Samples folder.


HrStrTokAll

The HrStrTokAll function splits a string into an array of string components.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB
Unicode: | Yes

HRESULT HrStrTokAll(
  LPCTSTR lpsz,
  LPCTSTR lpszEOT,
  ULONG * lpcpsz,
  LPTSTR * * lpppsz
);

Parameters

lpsz
Input parameter. Points to a string from which tokens are parsed.
lpszEOT
Input parameter. Points to a string containing token separators.
lpcpsz
Output parameter. Points to a ULONG variable containing the number of tokens in lpppsz.
lpppsz
Output parameter. Points to an array of strings containing the separated tokens.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrStrTokAll function in EDKUTILS.C under the EDKUTILS code sample in the Code Samples folder.

See Also

HrStrAToStrA, HrStrAToStrW, HrStrWToStrA, HrStrWToStrW


HrStrWToStrA

The HrStrWToStrA function creates a copy of a Unicode string as an ANSI string using the MAPI MAPIAllocateBuffer function.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB
Unicode: | (see Remarks)

HRESULT HrStrWToStrA(
  LPWSTR lpwszSource,
  LPSTR * lppszDest
);

Parameters

lpwszSource
Input parameter. Points to the Unicode source string.
lppszDest
Output parameter. Points to a pointer to the ANSI destination string.

Return Values

See Return Values.

Remarks

The HrStrWToStrA function is useful for creating macros involving TCHAR strings. You must release the destination string buffer with the MAPI MAPIFreeBuffer function before your routine exits.

When Unicode is defined, the following macros are defined as this function:

HrStrToStrA( LPTSTR lpszSource, LPSTR * lppszDest )

When Unicode is undefined, the following macros are defined as this function:

HrStrWToStr( LPWSTR lpwszSource, LPTSTR * lppszDest )

For information about the MAPIAllocateBuffer and MAPIFreeBuffer functions, see the MAPI Programmer's Reference.

See Also

HrStrAToStrA, HrStrAToStrW, HrStrTokAll, HrStrWToStrW


HrStrWToStrW

The HrStrWToStrW function creates a copy of a Unicode string as a Unicode string using the MAPI MAPIAllocateBuffer function.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB
Unicode: | Yes (see Remarks)

HRESULT HrStrWToStrW(
  LPWSTR lpwszSource,
  LPWSTR * lppwszDest
);

Parameters

lpwszSource
Input parameter. Points to a Unicode source string.
lppwszDest
Output parameter. Points to a pointer to the Unicode destination string.

Return Values

See Return Values.

Remarks

The HrStrWToStrW function is useful for creating macros involving TCHAR strings. You must release the destination string buffer with the MAPI MAPIFreeBuffer function before your routine exits.

When Unicode is defined, the following macros are defined as this function:

HrStrToStr( LPTSTR lpszSource, LPTSTR * lppszDest )

HrStrToStrW( LPTSTR lpszSource, LPWSTR * lppwszDest )

HrStrWToStr( LPWSTR lpwszSource, LPTSTR * lppszDest )

For information about the MAPIAllocateBuffer and MAPIFreeBuffer functions, see the MAPI Programmer's Reference.

See Also

HrStrAToStrA, HrStrAToStrW, HrStrTokAll, HrStrWToStrA


HrTextFromCompressedRTFStreamEx

The HrTextFromCompressedRTFStreamEx function converts RTF-compressed text to ANSI text.

Quick Info

Header file: | RTFLIB.H
Library: | RTFLIB.LIB

HRESULT HrTextFromCompressedRTFStreamEx(
  LPSTREAM pstmCompressed,
  LPSTREAM FAR * ppstmText,
  RTFSYNCINFO FAR * psi,
  ULONG cpid,
  ULONG cAttach,
  ULONG FAR * rgAttachPos
);

Parameters

pstmCompressed
Input parameter. Points to the compressed RTF stream.
ppstmText
Output parameter. Points to the address where the ANSI text is stored.
psi
Output parameter. Points to an RTFSYNCINFO structure containing the operations that must be done to synchronize the text.
cpid
Input parameter. The code page for the text stream. It can be any code page including UNICODE. If cpid is zero (0), HrTextFromCompressedRTFStreamEx uses the current system code page. If the requested code page is not supported, HrTextFromCompressedRTFStreamEx can return S_FALSE during a read or copy operation.
cAttach
Input parameter. The number of attachments in the array where rgAttachPos points.
rgAttachPos
Input/output parameter. An array containing the current rendering position for each attachment in the message. The number of elements in the array must match cAttach. The caller must fill in this array with the current attachment positions to guarantee proper handling of position 0xFFFFFFFF attachments. The values in rgAttachPos are updated while the stream is processed and are only accurate when the stream has been exhausted. Attachments with initial position 0xFFFFFFFF are not updated. If there are more attachments than RTF attachment tags, remaining attachments are updated to position 0xFFFFFFFF. If there are fewer attachments than RTF tags, the extra RTF tags are ignored.

Return Values

See Return Values.

Remarks

For information about the RTFSync function, see the MAPI Programmer's Reference.

See Also

HrRTFCompressedToText, HrTextToRTFCompressed, RTFSYNCINFO


HrTextToRTFCompressed

The HrTextToRTFCompressed function converts ANSI text to RTF compressed text.

Quick Info

Header file: | EDKUTILS.H
Library: | EDKUTILS.LIB

HRESULT HrTextToRTFCompressed(
  ULONG cchText,
  LPSTREAM lpText,
  ULONG cAttachments,
  ULONG * rgiRendering,
  LPMESSAGE lpMsg
);

Parameters

cchText
Input parameter. Number of characters of text.
lpText
Input parameter. Points to the plain text stream.
cAttachments
Input parameter. Number of message attachments.
rgiRendering
Input parameter. Rendering positions of the attachments.

Note The rendering positions must fall on a space in the text stream. If not, HrTextToRTFCompressed returns E_FAIL.

lpMsg
Input parameter. Points to an IMessage interface containing the MAPI message that receives the converted text.

Return Values

See Return Values.

Remarks

For more information on this function, see Saving ANSI Text as a Message Property in RTF.

See Also

HrRTFCompressedToText, HrTextFromCompressedRTFStreamEx, RTFSYNCINFO


HrTraceAppendEntryList

The HrTraceAppendEntryList function adds a trace entry to an existing trace information list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceAppendEntryList(
  LONG lAction,
  FILETIME ftArrivalTime,
  FILETIME ftDeferredTime,
  LPSTR lpszADMDName,
  LPSTR lpszCountryName,
  LPSTR lpszPRMDId,
  LPSTR lpszAttADMDName,
  LPSTR lpszAttCountryName,
  LPSTR lpszAttPRMDId,
  LPTRACEINFO * lppTraceInfo
);

Parameters

lAction
Input parameter. The routing action the tracing site took.
ftArrivalTime
Input parameter. The time at which the message entered the tracing site.
ftDeferredTime
Input parameter. The time at which the tracing site released the message.
lpszADMDName
Input parameter. ADMD name.
lpszCountryName
Input parameter. Country name.
lpszPRMDId
Input parameter. PRMD identifier.
lpszAttADMDName
Input parameter. Attempted ADMD name.
lpszAttCountryName
Input parameter. Attempted country name.
lpszAttPRMDId
Input parameter. Attempted PRMD identifier.
lppTraceInfo
Input/output parameter. Points to a TRACEINFO structure containing trace information.

Return Values

See Return Values.

Remarks

You should ensure that ftArrivalTime is less than ftDeferredTime.

For more information on this function, see the HrTraceAppendEntryList function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrTraceAppendEntryList, HrTraceCreateEntryList, HrTraceGetEntryList, HrTraceGetEntryListSize, HrTraceSetEntryList


HrTraceCopyEntry

The HrTraceCopyEntry function saves trace entry information in a trace entry structure.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceCopyEntry(
  LONG lAction,
  FILETIME ftArrivalTime,
  FILETIME ftDeferredTime,
  LPSTR lpszADMDName,
  LPSTR lpszCountryName,
  LPSTR lpszPRMDId,
  LPSTR lpszAttADMDName,
  LPSTR lpszAttCountryName,
  LPSTR lpszAttPRMDId,
  LPTRACEENTRY lpTraceEntry
);

Parameters

lAction
Input parameter. The routing action the tracing site took.
ftArrivalTime
Input parameter. The time at which the communique entered the tracing site.
ftDeferredTime
Input parameter. The time at which the tracing site released the message.
lpszADMDName
Input parameter. ADMD name.
lpszCountryName
Input parameter. Country name.
lpszPRMDId
Input parameter. PRMD identifier.
lpszAttADMDName
Input parameter. Attempted ADMD name.
lpszAttCountryName
Input parameter. Attempted Country name.
lpszAttPRMDId
Input parameter. Attempted PRMD identifier.
lpTraceEntry
Output parameter. Points to a TRACEENTRY structure containing trace entry information.

Return Values

See Return Values.

Remarks

You should ensure that ftArrivalTime is less than ftDeferredTime.

For more information on this function, see the HrTraceCopyEntry function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrTraceGetEntryList, HrTraceGotoEntry, HrTraceGotoFirstEntry, HrTraceGotoNextEntry, HrTraceOpenEntry


HrTraceCreateEntryList

The HrTraceCreateEntryList function creates a trace information list.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceCreateEntryList(
  LONG lAction,
  FILETIME ftArrivalTime,
  FILETIME ftDeferredTime,
  LPSTR lpszADMDName,
  LPSTR lpszCountryName,
  LPSTR lpszPRMDId,
  LPSTR lpszAttADMDName,
  LPSTR lpszAttCountryName,
  LPSTR lpszAttPRMDId,
  LPTRACEINFO lppTraceInfo
);

Parameters

lAction
Input parameter. The routing action the tracing site took.
ftArrivalTime
Input parameter. The time at which the message entered the tracing site.
ftDeferredTime
Input parameter. The time at which the tracing site released the message.
lpszADMDName
Input parameter. ADMD name.
lpszCountryName
Input parameter. Country name.
lpszPRMDId
Input parameter. PRMD identifier.
lpszAttADMDName
Input parameter. Attempted ADMD name.
lpszAttCountryName
Input parameter. Attempted country name.
lpszAttPRMDId
Input parameter. Attempted PRMD identifier.
lppTraceInfo
Output parameter. Points to a TRACEINFO structure containing trace information.

Return Values

See Return Values.

Remarks

It is important that ftArrivalTime is less than ftDeferredTime.

For more information on this function, see Gateway Trace Information.

See Also

HrTraceAppendEntryList, HrTraceGetEntryList, HrTraceSetEntryList


HrTraceGetEntryList

The HrTraceGetEntryList function obtains the trace information for a message.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceGetEntryList(
  LPMESSAGE lpMessage,
  LPTRACEINFO * lppTraceInfo
);

Parameters

lpMessage
Input parameter. Points a MAPI IMessage interface containing the message.
lppTraceInfo
Output parameter. Points to a TRACEINFO structure containing trace information.

Return Values

See Return Values.

Remarks

For more information on this function, see Gateway Trace Information.

For information about the IMessage interface, see the MAPI Programmer's Reference.

See Also

HrTraceAppendEntryList, HrTraceCreateEntryList, HrTraceGetEntryListSize, HrTraceSetEntryList


HrTraceGetEntryListSize

The HrTraceGetEntryListSize function obtains the size, in bytes, of the trace information.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceGetEntryListSize(
  LPTRACEINFO lpTraceInfo,
  ULONG * lpcbTraceInfo
);

Parameters

lpTraceInfo
Input parameter. Points to a TRACEINFO structure containing trace information.
lpcbTraceInfo
Output parameter. Number of bytes in trace information.

Return Values

See Return Values.

Remarks

For more information on this function, see Gateway Trace Information.

See Also

HrTraceAppendEntryList, HrTraceCreateEntryList, HrTraceGetEntryList, HrTraceSetEntryList


HrTraceGotoEntry

The HrTraceGotoEntry function retrieves a pointer to a TRACEENTRY structure in a TRACEINFO structure.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceGotoEntry(
  LPTRACEINFO lpTraceInfo,
  ULONG ulIndex,
  LPTRACEENTRY *lppTraceEntry
);

Parameters

lpTraceInfo
Input parameter. Points to a TRACEINFO structure containing trace information.
ulIndex
Input parameter. Index of the TRACEINFO structure where lpTraceInfo points within the TRACEENTRY structure where lppTraceEntry points.
lppTraceEntry
Output parameter. Points to a TRACEENTRY structure containing the trace entry information.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrTraceGotoEntry function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrTraceCopyEntry, HrTraceGotoFirstEntry, HrTraceGotoNextEntry, HrTraceOpenEntry,


HrTraceGotoFirstEntry

The HrTraceGotoFirstEntry function obtains a pointer to the first trace entry.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceGotoFirstEntry(
  LPTRACEINFO lpTraceInfo,
  ULONG FAR *lpulIndex,
  LPTRACEENTRY *lppTraceEntry
);

Parameters

lpTraceInfo
Input parameter. Points to TRACEINFO structure containing trace information.
lpulIndex
Output parameter. Index of the TRACEENTRY structure pointed to by lppTraceEntry in the TRACEINFO structure pointed to by lpTraceInfo.
lppTraceEntry
Output parameter. Points to a TRACEENTRY structure containing the trace entry.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrTraceGotoFirstEntry function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrTraceCopyEntry, HrTraceGotoEntry, HrTraceGotoNextEntry, HrTraceOpenEntry


HrTraceGotoNextEntry

The HrTraceGotoNextEntry function retrieves a pointer to the next trace entry.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceGotoNextEntry(
  LPTRACEINFO lpTraceInfo,
  ULONG *lpulIndex,
  LPTRACEENTRY *lppTraceEntry
);

Parameters

lpTraceInfo
Input parameter. Points to a TRACEINFO structure containing trace information.
lpulIndex
Intput parameter. Index of the trace entry pointed to by lppTraceEntry in the trace information pointed to by lpTraceInfo.
lppTraceEntry
Output parameter. Points to a TRACEENTRY containing the trace entry.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrTraceGotoNextEntry function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrTraceCopyEntry, HrTraceGotoEntry, HrTraceGotoFirstEntry, HrTraceOpenEntry


HrTraceOpenEntry

The HrTraceOpenEntry function retrieves a pointer to a trace entry.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceOpenEntry(
  LPTRACEENTRY lpTraceEntry,
  LONG *plAction,
  FILETIME *pftArrivalTime,
  FILETIME *pftDeferredTime,
  LPSTR *lppszADMDName,
  LPSTR *lppszCountryName,
  LPSTR *lppszPRMDId,
  LPSTR *lppszAttADMDName,
  LPSTR *lppszAttCountryName,
  LPSTR *lppszAttPRMDId
);

Parameters

lpTraceEntry
Input parameter. Points to a TRACEENTRY structure containing the trace entry.
plAction
Output parameter. Routing action taken by the tracing site.
pftArrivalTime
Output parameter. Time at which the communique entered the tracing site.
pftDeferredTime
Output parameter. Time at which the tracing site released the message.
lppszADMDName
Output parameter. ADMD Name.
lppszCountryName
Output parameter. Country Name.
lppszPRMDId
Output parameter. PRMD Identifier.
lppszAttADMDName
Output parameter. Attempted ADMD Name.
lppszAttCountryName
Output parameter. Attempted Country Name.
lppszAttPRMDId
Output parameter. Attempted PRMD Identifier.

Return Values

See Return Values.

Remarks

You should ensure that pftArrivalTime is less than pftDeferredTime.

For more information on this function, see the HrTraceOpenEntry function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

See Also

HrTraceCopyEntry, HrTraceGotoEntry, HrTraceGotoFirstEntry, HrTraceGotoNextEntry


HrTraceSetEntryList

The HrTraceSetEntryList function specifies the trace information that is recorded for a message.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceSetEntryList(
  LPMESSAGE lpMessage,
  LPTRACEINFO lpTraceInfo
);

Parameters

lpMessage
Input parameter. Points to a MAPI IMessage interface containing the message.
lpTraceInfo
Input parameter. Points to trace information.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrTraceSetEntryList function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

For information about the IMessage interface, see the MAPI Programmer's Reference.

See Also

HrTraceAppendEntryList, HrTraceCreateEntryList, HrTraceGetEntryList, HrTraceGetEntryListSize


HrTraceSetInfo

The HrTraceSetInfo function specifies the trace information that is saved for a message.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceSetInfo(
  LONG lAction,
  FILETIME *lpftArrivalTime,
  FILETIME *lpftDeferredTime,
  LPTSTR *lpszCountry,
  LPTSTR *lpszADMD,
  LPTSTR *lpszPRMD,
  LPMESSAGE *lpMessage
);

Parameters

lAction
Input parameter. Points to action.
lpftArrivalTime
Input parameter. Points to arrival time.
lpftDeferredTime
Input parameter. Points to deferred time.
lpszCountry
Input parameter. Points to country.
lpszADMD
Input parameter. Points to ADMD.
lpszPRMD
Input parameter. Points to PRMD.
lpMessage
Input/output parameter. Points to a MAPI IMessage interface containing the message.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrTraceSetInfo function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

For information about the IMessage interface, see the MAPI Programmer's Reference.

See Also

HrTraceUpdateInfo


HrTraceUpdateInfo

The HrTraceUpdateInfo function updates the trace information on a message.

Quick Info

Header file: | EDKMAPI.H
Library: | EDKMAPI.LIB

HRESULT HrTraceUpdateInfo(
  LONG lAction,
  FILETIME *lpftArrivalTime,
  FILETIME *lpftDeferredTime,
  LPTSTR lpszCountry,
  LPTSTR lpszADMD,
  LPTSTR lpszPRMD,
  LPMESSAGE lpMessage
);

Parameters

lAction
Input parameter. Points to action.
lpftArrivalTime
Input parameter. Points to arrival time.
lpftDeferredTime
Input parameter. Points to deferred time.
lpszCountry
Input parameter. Points to country.
lpszADMD
Input parameter. Points to ADMD.
lpszPRMD
Input parameter. Points to PRMD.
lpMessage
Input/output parameter. Points to a MAPI IMessage interface containing the message.

Return Values

See Return Values.

Remarks

For more information on this function, see the HrTraceUpdateInfo function in ITRACE.C under the EDKMAPI code sample in the Code Samples folder.

For information about the IMessage interface, see the MAPI Programmer's Reference.

See Also

HrTraceSetInfo


HrTrackInitLog

The HrTrackInitLog function opens the gateway event tracking module.

Quick Info

Header file: | EDKTRACK.H
Library: | EDKTRACK.LIB

HRESULT HrTrackInitLog(
  LPSTR lpszComputer,
  PVOID * ppvSession
);

Parameters

lpszComputer
Input parameter. Name of the remote computer.
ppvSession
Output parameter. Points to gateway tracking session.

Return Values

See Return Values.

Remarks

For more information on this function, see Using Tracking Functions.

See Also

HrTrackUninitLog, HrTrackWriteLog


HrTrackUninitLog

The HrTrackUninitLog function closes the gateway event tracking module.

Quick Info

Header file: | EDKTRACK.H
Library: | EDKTRACK.LIB

HRESULT HrTrackUninitLog(
  PVOID * ppvSession
);

Parameters

ppvSession
Input/output parameter. Points to gateway tracking session.

Return Values

See Return Values.

Remarks

For more information on this function, see Using Tracking Functions.

See Also

HrTrackInitLog, HrTrackWriteLog


HrTrackWriteLog

The HrTrackWriteLog function logs a gateway tracking event.

Quick Info

Header file: | EDKTRACK.H
Library: | EDKTRACK.LIB
Unicode: | Yes

HRESULT HrTrackWriteLog(
  PVOID pvSession,
  UINT nEventType,
  SYSTEMTIME stEvent,
  LPTSTR lpszGatewayName,
  LPTSTR lpszPartner,
  LPTSTR lpszMTSID,
  LPTSTR lpszRemoteID,
  LPTSTR lpszOriginator,
  INT nPriority,
  INT nLength,
  INT nSeconds,
  INT nCost,
  INT cRecipients,
  LPTSTR * lppszRecipients
);

Parameters

pvSession
Input parameter. Gateway tracking session.
nEventType
Input parameter. Gateway tracking event type.
stEvent
Input parameter. System time at which the event took place. Not necessarily when the transfer happened.
lpszGatewayName
Input parameter. Distinguished name (DN) of the gateway.
lpszPartner
Input parameter. Name of a remote system. A DN is preferable, but any name unique within the gateway class is acceptable.
lpszMTSID
Input parameter. MTSID of the message. This can be left blank in the case of a message submission.
lpszRemoteID
Input parameter. Identifier of the message in the foreign system. This parameter is not required.
lpszOriginator
Input parameter. DN or string for the originator of the message. Queries function better if this is input as a DN.
nPriority
Input parameter. Message priority. (Optional information. Use if available.)
nLength
Input parameter. Message length. (Optional information. Use if available.)
nSeconds
Input parameter. Seconds to process this message. (Optional information. Use if available.)
nCost
Input parameter. Cost of processing this message. (Optional information. Use if available.)
cRecipients
Input parameter. The number of recipients in lppszRecipients.
lppszRecipients
Input parameter. The recipients of the message (preferably a series of DNs).

Return Values

See Return Values.

Remarks

For more information on this function, see Using Tracking Functions.

See the description of EDKTRACK.LIB in TRACK: Tracking and Auditing Messages , for a listing of events that can be tracked.

See Also

HrTrackInitLog, HrTrackUninitLog


HServiceCreateThread

The HServiceCreateThread function creates a wrapped thread.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

HANDLE HServiceCreateThread(
  LPLONG lplStartThreads,
  LPLONG lplStopThreads,
  LPSECURITY_ATTRIBUTES lpThreadAttributes,
  DWORD dwStackSize,
  LPTHREAD_START_ROUTINE lpStartAddress,
  LPVOID lpParameter,
  DWORD dwCreationFlags,
  LPDWORD lpThreadId
);

Parameters

lplStartThreads
Input parameter. Number of running threads.
lplStopThreads
Input parameter. Number of stopped threads.
lpThreadAttributes
Input parameter. Thread attributes.
dwStackSize
Input parameter. Stack size.
lpStartAddress
Input parameter. Start address.
lpParameter
Input parameter. Parameter.
dwCreationFlags
Input parameter. Creation flags.
lpThreadId
Output parameter. Thread identifier.

Return Values

Returns handle to the created thread.

Remarks

For more information on this function, see the HServiceCreateThread function in WINWRAP.C under the WINWRAP code sample in the Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, ServiceMain, ServiceStop


InitProgressProc

The file-based batch processing functions of the directory access functions invoke a progress callback function based on the InitProgressProc prototype to initialize a user-defined progress display.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

BOOL (* InitProgressProc)(
  LPVOID lpvAppDefined,
  INT nMac
);

Parameters

lpvAppDefined
Points to an application-defined parameter supplied in the CALLBACKPROGRESS structure member of the *_PARMS structure argument to the batch function.
nMac
Input parameter. The number of items to process, and the number of times to call the UpdateProgressProc function. If 0 (zero), which usually only occurs in the BatchExport or NWExport function, there are an unknown number of items to process.

Return Values

Return FALSE if the user cancels the operation; otherwise, return TRUE.

Remarks

You should allocate any memory or resources you need and display your dialog box or custom control in InitProgressProc.

If nMac is 0, the display shows only that n items have been processed, as opposed to showing the progress as a portion of the total processing to be performed.

If nMac is 50, for example, and if the application displays a progress bar that is 500 pixels across, the display width could be broken into increments of 10 pixels, to have the display updated each time the UpdateProgressProc function is called.

For more information on this function, see Using Directory Access Functions.

See Also

BatchExport, BatchImport, BEXPORT_PARMS, BIMPORT_PARMS, CALLBACKPROGRESS, EndProgressProc, NTExport, NTEXPORT_PARMS, NWExport, NWEXPORT_PARMS, ResetProgressProc, UpdateProgressProc


InitSheetProc

The InitSheetProc (mandatory Administrator extension DLL) function is called by the Microsoft Exchange Server Administrator program to determine which property pages the Administrator extension DLL supports.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL (* InitSheetProc)(
  ADMIN_ObjectInfo * poi,
  ULONG fFlags,
  ADMIN_SheetInfo ** ppsi,
  UINT * pcsi,
  VOID ** ppvExtensionData
);

Parameters

poi
Input parameter. Points to an ADMIN_ObjectInfo structure containing information about the object whose properties are being displayed.
fFlags
Output parameter. One defined value is available:
fxfReadOnly
The property pages are read-only and cannot be changed.
ppsi
Output parameter. Points to an array of ADMIN_SheetInfo structures, which contain property sheet information.
pcsi
Output parameter. Points to the number of ADMIN_SheetInfo structures in ppsi.
ppvExtensionData
Output parameter. Points to a block of memory.

Return Values

This function must return a value as defined in Return Values.

Remarks

The InitSheetProc function is called once by the Administrator program, after it calls ADMIN_Initialize. This function is where the majority of any initialization should be done.

For more information on this function, see Using Administrator Extension Functions (Called by Administrator Program).

See Also

ADMIN_Initialize, ADMIN_ObjectInfo, ADMIN_SheetInfo, DeinitSheetProc, ShowPageProc, StartPageProc


InstallExtensionProc

The InstallExtensionProc function (optional Administrator extension DLL function) is normally called by the Microsoft Exchange Server Administrator program to install the Administrator extension DLL. However, this function is not supported by the Administrator program because installation tasks are performed by the directory functions.


JSClose

The JSClose function closes a jump window.

Quick Info

Header file: | STATS.H
Library: | STATS.LIB

VOID JSClose(
  HJSWINDOW hJSWindow
);

Parameters

hJSWindow
Input parameter. Handle to the jump window.

Return Values

None.

Remarks

JSClose closes the jump window.

For more information on this function, see Jump Window Functions.

See Also

HrJSCollectDataPoint, HrJSGetValue, HrJSOpen, HrFileTimeToSeconds


NTExport

The NTExport function exports user information from a Windows NT Server domain controller in a form that can later be imported into the Microsoft Exchange Server directory.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

DWORD NTExport(
  LPNTEXPORT_PARMS pNTExportParms
);

Parameters

pNTExportParms
Input parameter. Points to a NTEXPORT_PARMS structure.

Return Values

The return value indicates the number of errors encountered and logged in the Windows NT application event log. See the event log for more information on the nature of the error itself.

If an error is generated during the initialization part of this function's activities, the error indicates failure; after initialization, this return value does not indicate success or failure of the function. The user interface and the logging of errors and warnings into the application event log are controlled through import parameters.

Remarks

The NTExport function can only be used on a Windows NT Server computer.

For more information on this function, see Using Directory Access Functions.

See Also

NTEXPORT_PARMS


NWExport

The NWExport function exports user information from a Novell NetWare server in a form that can later be imported into the Microsoft Exchange Server directory.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

DWORD NWExport(
  LPNWEXPORT_PARMS  pNWExportParms
);

Parameters

pNWExportParms
Input parameter. Points to a NWEXPORT_PARMS structure.

Return Values

The return value indicates the number of errors encountered and logged in the Windows NT Server application event log. See the event log for more information on the nature of the error itself.

If an error is generated during the initialization part of this function's activities, the error indicates failure; after initialization, this return value does not indicate success or failure of the function. The user interface and the logging of errors and warnings into the application event log are controlled through import parameters.

Remarks

The NWExport function can be used only on a Windows NT Server computer.

For more information on this function, see Using Directory Access Functions.

See Also

NWEXPORT_PARMS


PADMIN_AddService

The PADMIN_AddService Administrator extension function adds a service to the list of services monitored by the server monitor program.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL (* PADMIN_AddService)(
  HWND hwnd,
  LPWSTR wszServiceName
);

Parameters

hwnd
Input parameter. Handle to the current service dialog window.
wszServiceName
Input parameter. The service that the user wants to add.

Return Values

See Return Values.

Remarks

You define the address of the PADMIN_AddService function in the ADMIN_Initialize function.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_RemoveService


PADMIN_FreeDialogResource

The PADMIN_FreeDialogResource Administrator extension function frees the allocated dialog resources.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID (* PADMIN_FreeDialogResource)(
  BYTE ** ppbDialog
);

Parameters

ppbDialog
Input parameter. Points to the address of the dialog resource to release.

Return Values

None.

Remarks

Use the PADMIN_FreeDialogResource function to free the dialog resources loaded by PADMIN_LoadDialogResource.

The value of ppbDialog is NULL when this function returns successfully.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_LoadDialogResource


PADMIN_FreeNameList

The PADMIN_FreeNameList Administrator extension function frees the routing table name list.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID PADMIN_FreeNameList(
  INT cstr,
  LPWSTR * psz
);

Parameters

cstr
Input parameter. Number of addresses in psz.
psz
Input parameter. The routing table name list.

Return Values

None.

Remarks

Use PADMIN_FreeNameList to free the routing table name list for the gateway that was created with PADMIN_GetNameList.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_GetNameList, PADMIN_SetNameList


PADMIN_GetNameList

The PADMIN_GetNameList Administrator extension function obtains the routing table name list for this gateway.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL PADMIN_GetNameList(
  INT * lpcNameList,
  LPWSTR ** lppwszNameList
);

Parameters

lpcNameList
Output parameter. Points to the number of strings in lppwszNameList.
lppwszNameList
Output parameter. Points to an array of Unicode strings containing the routing table addresses.

Return Values

See Return Values.

Remarks

You must release the routing table with a call to PADMIN_FreeNameList before you exit your program.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_FreeNameList, PADMIN_SetNameList


PADMIN_GetObjectData

The PADMIN_GetObjectData Administrator extension function obtains the directory object's extension data.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

RC PADMIN_GetObjectData(
  HWNDPARENT hwndParent,
  LPWSTR wszBlobName,
  BYTE * pb,
  UINT cb
);

Parameters

hwndParent
Input parameter. Handle of the current property sheet window.
wszBlobName
Input parameter. A Unicode string containing the name of the directory object.
pb
Output parameter. Points to the buffer that receives the directory object's extension data.
cb
Input parameter. The size, in bytes, of pb. You get this value with a call to the PADMIN_GetObjectDataSize function.

Return Values

See Return Values.

Remarks

Use PADMIN_GetObjectData in the Administrator extension DLL to obtain a directory object's extension data. The Administrator extension DLL must have already obtained the size of the directory object's extension data area using PADMIN_GetObjectDataSize, and allocated enough memory to receive the directory object's extension data.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_GetObjectDataSize, PADMIN_SetObjectData


PADMIN_GetObjectDataSize

The PADMIN_GetObjectDataSize Administrator extension function determines how much memory to allocate for the directory object's extension data.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

RC PADMIN_GetObjectDataSize(
  HWNDPARENT hwndParent,
  LPWSTR wszBlobName,
  UINT * pcb
);

Parameters

hwndParent
Input parameter. Handle to the current property sheet window.
wszBlobName
Input parameter. A Unicode string containing the name of the directory object.
pcb
Output parameter. The size, in bytes, of the extension data.

Return Values

See Return Values.

Remarks

Use PADMIN_GetObjectDataSize in the Administrator extension DLL to obtain the size of the directory object's extension data area. The Administrator extension DLL must allocate enough memory to hold the extension data before obtaining the extension data with a call to the PADMIN_GetObjectData function.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_GetObjectData, PADMIN_SetObjectData


PADMIN_InfoHasChanged

The PADMIN_InfoHasChanged Administrator extension function notifies the Microsoft Exchange Server Administrator program that some information has been altered on a property sheet.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID PADMIN_InfoHasChanged(
  HWNDPARENT hwndParent
);

Parameters

hwndParent
Input parameter. Handle to the current property sheet window.

Return Values

None.

Remarks

Use PADMIN_InfoHasChanged in your Administrator extension DLL to have the Microsoft Exchange Server Administrator program enable the Apply button after the user has changed some data in the property sheet.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_GetObjectData, PADMIN_SetObjectData


PADMIN_LoadDialogResource

The PADMIN_LoadDialogResource Administrator extension function loads a dialog resource of the appropriate language and modifies the resource to handle the font that the Microsoft Exchange Server Administrator program is using.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL (* PADMIN_LoadDialogResource)(
  HINSTANCE hinst,
  UINT iddDialog,
  LANGID langid,
  BYTE ** ppbDialog
);

Parameters

hinst
Input parameter. Handle to the current instance of the service.
iddDialog
Input parameter. The identifier of the dialog to be loaded.
langid
Input parameter. The language identifiers (primary and secondary) as defined in WINNT.H.
ppbDialog
Output value. Points to the address of the buffer where the dialog resources are loaded.

Return Values

See Return Values.

Remarks

You must free the dialog resources with a call to PADMIN_FreeDialogResource before your program exits.

You can start the dialog returned in ppbDialog with a call to the Win32 function DialogBoxIndirectParam.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

PADMIN_FreeDialogResource


PADMIN_RemoveService

The PADMIN_RemoveService Administrator extension function removes a service from the list of monitored services.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL (* PADMIN_RemoveService)(
  HWND hwnd,
  LPWSTR wszServiceName
);

Parameters

hwnd
Input parameter. Handle of the current property sheet window.
wszServiceName
Input parameter. A Unicode string containing the name of the service.

Return Values

See Return Values.

Remarks

Use PADMIN_RemoveService to remove a service from the list of services that the server monitor program is monitoring. The service was one previously added by a call to PADMIN_AddService.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_AddService


PADMIN_SetIcon

The PADMIN_SetIcon Administrator extension function retrieves a standard icon to use in an extension data property sheet.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID PADMIN_SetIcon(
  HWND hwnd,
  INT id
);

Parameters

hwnd
Input parameter. Handle to the current property sheet window.
id
Input parameter. Resource identifier of the icon.

Return Values

None.

Remarks

Use PADMIN_SetIcon to get the standard icon for the class of object that this extension DLL is being called for and place it on the property sheet where the control identified by id is placed. Typically, the icon is in the top left corner of the property sheet, but can be placed anywhere by modifying the RC file.

You should call PADMIN_SetIcon during the processing of the WM_Init_Dialog message.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_SetNameList, PADMIN_SetObjectData, PADMIN_SetTitle


PADMIN_SetNameList

The PADMIN_SetNameList Administrator extension function saves the routing table name list for this gateway.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL PADMIN_SetNameList(
  HWND hwnd,
  INT cstr,
  LPWSTR * psz
);

Parameters

hwnd
Input parameter. Handle of the current property sheet window.
cstr
Input parameter. The number of routing table names.
psz
Input parameter. Points to an array of Unicode strings containing the routing table names.

Return Values

See Return Values.

Remarks

Use PADMIN_SetNameList to save any changes to the routing table names.

If PADMIN_SetNameList fails to save the changes (the return value is FALSE), the Administrator extension DLL need not display an error message to the user because the Microsoft Exchange Server Administrator program will have already done so.

You should release psz with a call to the PADMIN_FreeNameList function.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_FreeNameList, PADMIN_GetNameList


PADMIN_SetObjectData

The PADMIN_SetObjectData Administrator extension function saves extension data to the directory object's extension data attribute.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

RC (* PADMIN_SetObjectData)(
  HWND hwnd,
  BYTE * pb,
  UINT cb,
  BOOL fNew
);

Parameters

hwnd
Input parameter. Handle to the current property sheet window.
pb
Input parameter. Points to the buffer holding the extension data object.
cb
Input parameter. The size, in bytes, of pb.
fNew
Input parameter. Specifies whether the extension data object is new (TRUE) or already exists (FALSE).

Return Values

The return value depends on the value of fNew and whether pB is unique, where unique means that no other extension data for the object has the same name.

fNew Value (Is Object New?) | Is pB Object Unique | Return Code
TRUE | Unique | RC_SUCCESS
FALSE | Unique | RC_NOTFOUND
TRUE | Not Unique | RC_CONTENTION
FALSE | Not Unique | RC_SUCCESS

Remarks

Use PADMIN_SetObjectData to save extension data in response to a call to CommitDataProc.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_GetObjectData, PADMIN_GetObjectDataSize


PADMIN_SetTitle

The PADMIN_SetTitle Administrator extension function retrieves a standard title to use in an extension data property sheet.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

VOID PADMIN_SetTitle(
  HWND hwndParent,
  INT id
);

Parameters

hwndParent
Input parameter. Handle to the current dialog window.
id
Input parameter. Resource identifier of the property sheet.

Return Values

None.

Remarks

Use PADMIN_SetTitle to get the standard title for the class of object that this extension DLL is being called for and place it on the property sheet where the control identified by id is placed. Typically the title is in the top right corner of the property sheet, but can be placed anywhere by modifying the RC file.

You should call PADMIN_SetTitle during the processing of the WM_Init_Dialog message.

For more information on this function, see Using Administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_Initialize, PADMIN_SetIcon, PADMIN_SetNameList


PCONVDLLCONV

The PCONVDLLCONV function converts an address.

Quick Info

Header file: | CONVSTRC.H
Library: | CONVSTRC.LIB
Unicode: | Yes

HRESULT (* PCONVDLLCONV)(
  LPCWSTR pszOptions,
  LPCWSTR pszClass,
  PVOID pContent,
  PVOID pContentOut,
  PEDKCNVENV pEnv,
  EDKCNVRES * pcr
);

Parameters

pszOptions
Input parameter. Points to a Unicode string containing a list of options.
pszClass
Input parameter. Points to a Unicode string containing the name of the class.
pContent
Input parameter. Points to the object to convert.
pContentOut
Input parameter. Points to the converted object.
pEnv
Input parameter. Points to an EDKCNVENV structure containing information on the environment.
pcr
Output parameter. Points to the results of the conversion:
GCR_OK
The conversion completed successfully.
GCR_CANNOT_CONVERT
The conversion could not be performed, possibly due to the wrong format.
GCR_CANNOT_LOAD
The conversion routine could not load.
GCR_NO_CANDIDATE
There was nothing to convert.
GCR_CONVERSION_FAILED
The conversion failed for unknown reasons.

Return Values

See Return Values.

See Also

CONVDLLVECT, PCONVDLLENTRYFN, PCONVDLLQUERY


PCONVDLLENTRYFN

The PCONVDLLENTRYFN function is the user-supplied entry point to the conversion.

Quick Info

Header file: | CONVSTRC.H
Library: | CONVSTRC.LIB

HRESULT (* PCONVDLLENTRYFN)(
  DWORD, dwVersion,
  PCONVDLLVECT FAR * pConvVect
);

Parameters

dwVersion
Input parameter. The version number.
pConvVect
Output parameter. Points to a CONVDLLVECT structure containing information on the conversion entry point.

Return Values

See Return Values.

Remarks

For an example of using this function, see the CEDKConvDll::HrEDKLoad method in CONVDLL.CPP under the MESGXLAT code sample in the Code Samples folder.

See Also

PCONVDLLCONV, PCONVDLLQUERY


PCONVDLLQUERY

The PCONVDLLQUERY function determines whether an address was converted.

Quick Info

Header file: | CONVSTRC.H
Library: | CONVSTRC.LIB

HRESULT (* PCONVDLLQUERY)(
  LPCWSTR pszOptions,
  LPCWSTR pszClass,
  PVOID pContent,
  PEDKCNVENV pEnv,
  BOOL * pfAmCandidate
);

Parameters

pszOptions
Input parameter. Points to a Unicode string containing a list of options.
pszClass
Input parameter. Points to a Unicode string containing the name of the class.
pContent
Input parameter. Points to the object to convert.
pEnv
Input parameter. Points to an EDKCNVENV structure containing information on the environment.
pfAmCandidate
Output parameter. Points to whether the conversion completed successfully:
TRUE
The conversion completed successfully.
FALSE
The conversion did not complete successfully.

Return Values

See Return Values.

See Also

CONVDLLVECT, PCONVDLLCONV, PCONVDLLENTRYFN


RcGenerateProxy

The RcGenerateProxy function returns a proxy address as a Unicode string.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

RC RcGenerateProxy(
  HANDLE hProxySession,
  PRECIPIENTINFO pRecipientInfo,
  INT nRetries,
  LPWSTR * ppszProxyAddr
);

Parameters

hProxySession
Input parameter. Handle to the proxy address generation session as returned by RcInitProxies.
pRecipientInfo
Input parameter. The recipient specific details for this recipient.
nRetries
Input parameter. The number of times this function has previously been called with this value for pRecipientInfo.
ppszProxyAddr
Output parameter. The foreign format (proxy) address that is generated. This is a Unicode string of the form "TYPE:VALUE."

Return Values

See Return Values. If RcGenerateProxy returns RC_ERROR, the following can be possible causes:

  • The value of the nRetries parameter is too high. RcGenerateProxy cannot generate any more unique proxy addresses.
  • The site-specific information is incomplete.
  • The per-recipient information is incomplete.

Remarks

You must call RcInitProxies to set up the proxy generation DLL before you call RcGenerateProxy.

RcGenerateProxy uses the pRecipientInfo and nRetries parameters, and the site's proxy information to generate a site-unique recipient proxy address in the addressing format of the foreign address-type.

When you call this function with the same pRecipientInfo parameter but a different nRetries parameter value, RcGenerateProxy returns a different proxy address. Note that the maximum supported value for the nRetries parameter is implementation specific, and can be 0 (zero).

RcGenerateProxy allocates the memory for the ppszProxyAddr parameter. Your program must free this memory by calling the FreeProxy function.

For more information on this function, see Proxy Generation DLL Entry Points.

See Also

CloseProxies, RcInitProxies, RcValidateProxy


RcInitProxies

The RcInitProxies function invokes the proxy generation DLL to perform any initialization required before calling the RcGenerateProxy function with individual recipient objects.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

RC RcInitProxies(
  LPWSTR pszDomainProxy,
  LPWSTR pszServer,
  HANDLE * phProxySession
);

Parameters

pszDomainProxy
Input parameter. A Unicode string containing the site proxy address for this address-type. Cannot be NULL.
pszServer
Input parameter. A Unicode string containing the name of the server where the proxy generation DLL is being used.
phProxySession
Output parameter. Handle to a proxy address generation session.

Return Values

See Return Values.

If RcInitProxies returns RC_IMPLEMENTATION, proxy addresses are not implemented for this address type. In this case, no proxy addresses are stored and the RcGenerateProxy and CloseProxies entry points to this DLL are undefined. However, users do not see an error because pszSiteProxy == NULL is a supported configuration.

Remarks

The RcInitProxies function is only used to make the site specific information accessible to the RcGenerateProxy and RcValidateProxy functions.

The pszDomainProxy parameter is generally used as part of the recipient proxy address.

RcInitProxies allocates the memory for the phProxySession parameter. Your program must free this memory by calling the FreeProxy function.

Both pszDomainProxy and pszServer are guaranteed to stay valid until after CloseProxies is called, so the DLL need only keep a copy of these pointers rather than copy the data. Or, the DLL can copy the data with the same result, as the information these structures point to will not change until after CloseProxies is called.

For more information on this function, see Proxy Generation DLL Entry Points.

See Also

CloseProxies, RcGenerateProxy, RcValidateProxy


RcUpdateProxy

The RcUpdateProxy function updates the site information in a proxy address.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

RC RcUpdateProxy(
  HANDLE hProxySession,
  PRECIPIENTINFO pRecipientInfo,
  LPWSTR pwstrOldSiteProxy,
  LPWSTR pwstrNewSiteProxy,
  LPWSTR pwstrProxy,
  VOID * pUnused
);

Parameters

hProxySession
Input parameter. Handle to the proxy address generation session as returned by RcInitProxies.
pRecipientInfo
Input parameter. Points to a RECIPIENTINFO structure containing details for this recipient.
pwstrOldSiteProxy
Input parameter. A Unicode string containing the old site proxy address.
pwstrNewSiteProxy
Input parameter. A Unicode string containing the new site proxy address.
pwstrProxy
Input/output parameter. A Unicode string containing the proxy address to update.
pUnused
Input parameter. Unused, set this to NULL.

Return Values

See Return Values.

Remarks

RcUpdateProxy compares the site information in pwstrProxy to pwstrOldSiteProxy. If they match, RcUpdateProxy replaces the site information in pwstrProxy with pwstrNewSiteProxy. All input parameters have the address type as a prefix.

For more information on this function, see Proxy Generation DLL Entry Points.

See Also

RcInitProxies, RcValidateProxy, RECIPIENTINFO


RcValidateProxy

The RcValidateProxy function determines whether a Unicode string represents a valid proxy address.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

RC RcValidateProxy(
  HANDLE hProxySession,
  LPWSTR pszProxyAddr,
  BOOL * pisValid
);

Parameters

hProxySession
Input parameter. Handle to the proxy address generation session previously returned by RcInitProxies.
pszProxyAddr
Input parameter. A Unicode string containing the proxy address, including the address type prefix, to validate.
pisValid
Output parameter:
TRUE
The address is valid, or the return code is RC_IMPLEMENTATION.
FALSE
The address is not valid.
Undefined
The return code is RC_ERROR or RC_MEMORY.

Return Values

See Return Values. This function can also return the following:

RC_IMPLEMENTATION
Proxy address validation is not implemented. The caller should assume the entered proxy address is valid and let the gateway or foreign system advise otherwise if neccesary.

Remarks

Use RcValidateProxy to determine whether a manually generated proxy address is valid.

For more information on this function, see Proxy Generation DLL Entry Points.

See Also

RcUpdateProxy, RcValidateSiteProxy


RcValidateSiteProxy

The RcValidateSiteProxy function determines whether a Unicode string represents a valid site proxy address.

Quick Info

Header file: | PROXYGEN.H
Library: | PROXYGEN.LIB

RC RcValidateSiteProxy(
  HANDLE hProxySession,
  LPWSTR pszProxyAddr,
  BOOL * pisValid
);

Parameters

hProxySession
Input parameter. Handle to the proxy address generation session previously returned by RcInitProxies.
pszProxyAddr
Input parameter. A Unicode string containing the site proxy address, including the address type prefix, to validate.
pisValid
Output parameter:
TRUE
The site address is valid, or the return code is RC_IMPLEMENTATION.
FALSE
The site address is not valid.
Undefined
The return code is RC_ERROR or RC_MEMORY.

Return Values

See Return Values. This function can also return the following:

RC_IMPLEMENTATION
Site proxy address validation is not implemented. The caller should assume the entered site proxy address is valid and let the gateway or foreign system advise otherwise if neccesary.

Remarks

For more information on this function, see Proxy Generation DLL Entry Points.

See Also

RcInitProxies, RcUpdateProxy, RcValidateProxy


ResetProgressProc

The file-based batch processing functions of the directory functions invoke a callback function based on the ResetProgressProc prototype to reset the user-defined progress display when a new stage of the batch operation has started.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB

BOOL (* ResetProgressProc)(
  LPVOID lpvAppDefined,
  INT nMac
);

Parameters

lpvAppdefined
Points to an application-defined parameter supplied in the CALLBACKPROGRESS structure member of the *_PARMS structure argument to the batch function.
nMac
Input parameter. The number of items to process, and the number of times to call the UpdateProgressProc function. If 0 (zero), which usually only occurs in the BatchExport or NWExport function, there are an unknown number of items to process.

Return Values

Return FALSE if the user cancels the operation; otherwise, return TRUE.

Remarks

If nMac is 0, the display shows only that n items have been processed, as opposed to showing the progress as a portion of the total processing to be performed.

For example, if nMac is 50, and the application displays a progress bar that is 500 pixels across, the display width could be broken into increments of 10 pixels, to have the display updated each time the UpdateProgressProc function is called.

For more information on this function, see Using Directory Access Functions.

See Also

BatchExport, BatchImport, BEXPORT_PARMS, BIMPORT_PARMS, CALLBACKPROGRESS, InitProgressProc, NTExport, NTEXPORT_PARMS, NWExport, NWEXPORT_PARMS, ResetProgressProc, UpdateProgressProc


SAD_EcGetProxies

The SAD_EcGetProxies function obtains all of the proxy addresses for a recipient that a server supports.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

RPC_EC SAD EcGetProxies(
  LPWSTR wszServer,
  PPROXYINFO pProxyInfo,
  PPROXYLIST pProxyList
);

Parameters

wszServer
Input parameter. The server that supports various proxy address types.
pProxyInfo
Input parameter. Points to a PROXYINFO structure containing a list of known proxy addresses (pProxyInfo->pPNVerifyProxy) for a recipient.
pProxyList
Output parameter. Points to a PROXYLIST structure containing lists of both supported (pProxyList->ppPNProxy) and unsupported (pProxyList->ppPNFailedProxyType) proxy address types.

Return Values

See Return Values.

Remarks

You must call the SAD_FreeProxyListNode function to release the memory that SAD_EcGetProxies allocates for the PROXYNODE structures in the pProxyList parameter.

See Also

PROXYINFO, PROXYLIST, SAD_EcGetProxiesBI


SAD_EcGetProxiesBI

The SAD_EcGetProxiesBI function obtains all of the proxy addresses for a recipient that the server supports.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

RPC_EC SAD_EcGetProxiesBI(
  PRPCBINDINFO pBI,
  PPROXYINFO pProxyInfo,
  PPROXYLIST pProxyList
);

Parameters

pBI
Input parameter. Points to a RPCBINDINFO structure containing the binding to the server as returned in SAD_ScBind.
pProxyInfo
Input parameter. Points to a PROXYINFO structure containing a list of known proxy addresses (pProxyInfo->pPNVerifyProxy) for a recipient.
pProxyList
Output parameter. Points to a PROXYLIST structure containing lists of both supported (pProxyList->ppPNProxy) and unsupported (pProxyList->ppPNFailedProxyType) proxy address types.

Return Values

See Return Values.

Remarks

Your program must first call SAD_ScBind to establish a binding to a server before it can call SAD_EcGetProxiesBI.

You must call the SAD_FreeProxyListNode function to release the memory that SAD_EcGetProxiesBI allocates for the PROXYNODE structures in the pProxyList parameter.

See Also

PROXYINFO, PROXYLIST, SAD_EcGetProxies, SAD_ScBind, SAD_Unbind

See Also

SAD_ScGetBackupListNodeW ›


SAD_FreeProxyListNode

The SAD_FreeProxyListNode function frees memory allocated for a PROXYNODE structure.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

VOID SAD_FreeProxyListNode(
  PPROXYNODE pnode
);

Parameters

pnode
Input parameter. Points to a PROXYNODE structure.

Return Values

None.

Remarks

The memory for the pnode parameter was allocated by either the SAD_EcGetProxies or SAD_EcGetProxiesBI function.

See Also

SAD_EcGetProxies, SAD_EcGetProxiesBI


SAD_ScBind

The SAD_ScBind function creates a binding to a server for the nonbulk system attendant functions.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB
Unicode: | Yes

RPC_SC SAD_ScBind(
  PRPCBINDINFO pBI,
  LPTSTR szServer
);

Parameters

pBI
Output parameter. Points to a RPCBINDINFO structure containing the binding information.
szServer
The server where the client is bound.

Return Values

See Return Values.

Remarks

Use the SAD_ScBind function to get the RPCBINDINFO structure pointer for the nonbulk system attendant functions.

See Also

RPCBINDINFO, SAD_Unbind


SAD_ScBulkCreateMultiProxy

The SAD_ScBulkCreateMultiProxy function builds the lists of proxy addresses for the specified proxy address types on the server.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

RPC_SC SAD_ScBulkCreateMultiProxy(
  LPTSTR szServer,
  INT cszHeader,
  LPTSTR rgszHeader[],
  DWORD dwOptions
);

Parameters

szServer
Input parameter. The server where the proxy addresses are created.
cszHeader
Input parameter. The number of proxy address types in rgszHeader[].
rgszHeader[]
Input parameter. A list of proxy address types from which the proxy addresses are created.
dwOptions
Input parameter. How the proxy address type lists are generated:
BPTAdd
The generated proxy addresses are added to the appropriate proxy address list.
BPTRemove
The generated proxy addresses are removed from the appropriate proxy address list, if they exist in the list.
BPTUpdate
The generated proxy addresses are updated in the appropriate proxy address list, if they exist in the list.

Return Values

See Return Values.

Remarks

The SAD_ScBulkCreateMultiProxy function is typically called by a gateway setup program to generate the new recipient proxy addresses for that gateway's address types.

See Also

SAD_ScBulkCreateProxy


SAD_ScBulkCreateProxy

The SAD_ScBulkCreateProxy function builds the list of proxy addresses for the specified proxy address type on the server.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB
Unicode: | Yes

RPC_SC SAD_ScBulkCreateProxy(
  LPTSTR szServer,
  LPTSTR szHeader,
  DWORD dwOptions
);

Parameters

szServer
Input parameter. The server where the proxy addresses are created.
szHeader
Input parameter. The proxy address type.
dwOptions
Input parameter. How the proxy address type list is generated:
BPTAdd
The generated proxy addresses are added to the proxy address list.
BPTRemove
The generated proxy addresses are removed from the proxy address list, if they exist in the list.
BPTUpdate
The generated proxy addresses are updated in the proxy address list, if they exist in the list.

Return Values

See Return Values.

Remarks

The SAD_ScBulkCreateProxy function is typically called by a gateway setup program to generate the new recipient proxy addresses for that gateway's address type.

For more information on this function, see Generating Recipient Proxy Addresses.

See Also

SAD_ScBulkCreateMultiProxy


SAD_ScBulkProxyHalt

The SAD_ScBulkProxyHalt function stops or concludes a bulk operation.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB
Unicode: | Yes

RPC_SC SAD_ScBulkProxyHalt(
  LPTSTR szServer,
  RPC_BOOL fWaitForShutdown
);

Parameters

szServer
Input parameter. The server where the bulk operation is running.
fWaitForShutdown
Input parameter. Whether SAD_ScBulkProxyHalt waits for the bulk operation to conclude before interrupting it:
TRUE
Wait for the bulk operation to conclude before interrupting it.
FALSE
Interrupt it now (as soon as it has completed its work on the current address).

Return Values

See Return Values.

Remarks

The SAD_ScBulkProxyHalt function never leaves the proxy addresses in an indeterminate state. If you reinvoke the bulk operation on the same list, the bulk-add operations update the already processed proxy addresses; the bulk-update operations generate a message that the old proxy addresses do not exist.

See Also

SAD_ScBulkCreateMultiProxy, SAD_ScBulkCreateProxy, SAD_ScBulkUpdateMultiProxy, SAD_ScGetBulkProxyStatus


SAD_ScBulkUpdateMultiProxy

The SAD_ScBulkUpdateMultiProxy function converts any proxy addresses on the server from one of the old site proxy addresses to one of the new site proxy addresses.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

RPC_SC SAD_ScBulkUpdateMultiProxy(
  LPWSTR wszServer,
  INT cwszSiteAddress,
  LPWSTR rgwszOldSiteAddress[],
  LPWSTR rgwszNewSiteAddress[],
  RPC_BOOL fSaveSiteAddress
);

Parameters

wszServer
Input parameter. A Unicode string containing the name of the server where the proxy addresses are updated.
cwszSiteAddress
Input parameter. The number of address sites to convert (the number of elements in the rgwszOldSiteAddress and rgwszNewSiteAddress array parameters).
rgwszOldSiteAddress[]
Input parameter. An array of Unicode strings containing the names of the old address sites.
rgwszNewSiteAddress[]
Input parameter. An array of Unicode strings containing the names of the new address sites.
fSaveSiteAddress
Input parameter. Whether to save the new proxy addresses, making them permanent:
TRUE
Permanently save the new proxy addresses.
FALSE
Do not permanently save the new proxy addresses.

Return Values

See Return Values.

Remarks

If a proxy address contains rgwszOldSiteAddress[n], that site portion of the address is converted to rgwszNewSiteAddress[n], as expected. If either rgwszOldSiteAddress[] or rgwszNewSiteAddress[] does not have cwszSiteAddress entries, SAD_ScBulkUpdateMultiProxy returns SC_BPSiteAddressMismatch.

See Also

SAD_ScBulkProxyHalt


SAD_ScGetBulkProxyStatus

The SAD_ScGetBulkProxyStatus function obtains the status of a bulk operation.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

RPC_SC SAD_ScGetBulkProxyStatus(
  LPTSTR szServer,
  RPC_SYSTEMTIME * pstTimeStart,
  DWORD * pdwTimeStart,
  DWORD * pdwTimeCur,
  INT * piRecipients,
  INT * pcRecipients
);

Parameters

szServer
Input parameter. The server where the bulk operation is running.
pstTimeStart
Output parameter. Points to an RPC_SYSTEMTIME structure containing the system time (day and year) when the bulk operation began. RPC_SYSTEMTIME is defined as follows:
        typedef struct  __MIDL_TriggerPrivateRPC_0001
            {
            short rgwSystemTime[ 8 ];
            }    RPC_SYSTEMTIME;
pdwTimeStart
Output parameter. The absolute time, in time_t format, when the bulk operation began.
pdwTimeCur
Output parameter. The absolute current time, in time_t format.
piRecipients
Output parameter. The index into the list of recipients where the bulk operation is working.
pcRecipients
Output parameter. The total number of recipients on which the bulk operation is working.

Return Values

See Return Values.

Remarks

The SAD_ScGetBulkProxyStatus function gets the status of whatever bulk operation is running. These bulk operations are SAD_ScBulkCreateProxy, SAD_ScBulkCreateMultiProxy, and SAD_ScBulkUpdateMultiProxy.

You can determine how long, in seconds, the bulk operation has been running by subtracting the value of pdwTimeStart from the value of pdwTimeCur.

You can tell how far along the bulk operation is in converting a list of recipients by comparing piRecipients, which gives you where the bulk operation is in the list, with pcRecipients , which tells you how many recipients are in the list.

You can use SAD_ScBulkProxyHalt to interrupt a bulk operation.

For more information on this function, see Generating Recipient Proxy Addresses.

See Also

SAD_ScBulkCreateMultiProxy, SAD_ScBulkCreateProxy, SAD_ScBulkProxyHalt, SAD_ScBulkUpdateMultiProxy


SAD_ScIsProxyUnique

The SAD_ScIsProxyUnique function determines whether a proxy address is unique to the server.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB
Unicode: | Yes

RPC_SC SAD_ScIsProxyUnique(
  LPTSTR szServer,
  LPTSTR szProxy,
  RPC_BOOL * pfUnique,
  LPTSTR * pszExisting
);

Parameters

szServer
Input parameter. The server.
szProxy
Input parameter. The proxy address that might be unique.
pfUnique
Output parameter. Whether the proxy address is unique:
TRUE
The proxy address is unique on this server.
FALSE
The proxy address is not unique on this server.
pszExisting
Output parameter. The DN of the recipient where the proxy address maps, if pfUnique is TRUE; otherwise, NULL.

Return Values

See Return Values.

See Also

SAD_EcGetProxies


SAD_ScRunRID

The SAD_ScRunRID function instructs the server to recalculate the routing table.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB
Unicode: | Yes

RPC_SC SAD_ScRunRID(
  LPTSTR szServer
);

Parameters

szServer
Input parameter. The server where the routing table is recalculated.

Return Values

See Return Values.

Remarks

Use the SAD_ScRunRID function when you change how messages are routed, such as when you add a SMTP server and you must recalculate the routing table.

For more information on this function, see Rebuilding the Gateway Address Routing Table.

See Also

SAD_ScRunRID


SAD_ScRunRIDEx

The SAD_ScRunRIDEx function instructs the server to recalculate the routing table.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB
Unicode: | Yes

RPC_SC SAD_ScRunRIDEx(
  LPTSTR szServer,
  RPC_BOOL fProxySpace,
  RPC_BOOL fGwart
);

Parameters

szServer
Input parameter. The server containing the routing table to recalculate.
FProxySpace
The proxy address type(s) to recalculate.
fGwart
Input parameter. The gateway address routing table.

Return Values

See Return Values.

Remarks

Use the SAD_ScRunRIDEx function when you change how messages are routed for a specific set of proxy addresses.

See Also

SAD_ScRunRID


SAD_ScSaveGatewayTrackingData

The SAD_ScSaveGatewayTrackingData function creates a record of an event for tracking messages through Microsoft Exchange Server.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

RPC_SC SAD_ScSaveGatewayTrackingData(
  PRPCBINDINFO pBI,
  RPC_GATEWAY_TRACK_INFORMATION * pgti,
  INT cszRecipients,
  LPWSTR rgwszRecipients[]
);

Parameters

pBI
Points to an RPCBINDINFO structure containing the binding from SAD_ScBind.
pgti
Points to an RPC_GATEWAY_TRACK_INFORMATION structure containing the tracking information.
cszRecipients
The number of recipients in rgwszRecipients.
rgwszRecipients
Points to an array of Unicode strings, which contain the names of the recipients for this event.

Return Values

See Return Values.

See Also

RPCBINDINFO, RPC_GATEWAY_TRACK_INFORMATION, SAD_ScBind


SAD_Unbind

The SAD_Unbind function releases the resources acquired through the SAD_ScBind function.

Quick Info

Header file: | SADAPI.H
Library: | SADAPI.LIB

VOID SAD_Unbind(
  PRPCBINDINFO pBI
);

Parameters

pBI
Points to an RPCBINDINFO structure containing the binding from SAD_ScBind.

Return Values

See Return Values.

See Also

RPCBINDINFO, SAD_ScBind


SaveDataProc

The SaveDataProc function saves the extension data to memory. Optional Administrator extension DLL function.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL SaveDataProc(
  VOID * pvExtensionData,
  HWNDPARENT hwndParent
);

Parameters

pvExtensionData
Input parameter. Points to the block of memory.
hwndParent
Input parameter. Specifies the handle of the current property sheet window.

Return Values

See Return Values.

Remarks

The Microsoft Exchange Server Administrator program calls the SaveDataProc function when the user changes a property page, clicks the OK button, or clicks the Apply button.

If the user clicks OK, the Administrator program calls SaveDataProc for each property page so the DLL can validate and save into memory the data managed by the property sheet dialog. The Administrator program then calls CommitDataProc, which should save the data in memory and place it in permanent storage.

See Also

ADMIN_Initialize, PADMIN_AddService


SchemaPreload

The SchemaPreload function initializes the attribute and class tables for import and export operations. Microsoft Exchange Server executes the SchemaPreload function in the background as a separate thread.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: | Yes

VOID SchemaPreload(
  DWORD dwFlags,
  LPTSTR pszDSA
);

Parameters

dwFlag
Accepts defined values that control the directory schema operations. Use the bitwise OR operator (|) to enable multiple operations:
DAPI_FORCE_SCHEMA_LOAD
Unloads a previously loaded schema and reads the schema again. The default action is to reuse the previously loaded schema if read from the same messaging domain.
DAPI_RAW_MODE
Imports and exports in raw mode, where import lines are taken literally. Attributes are neither inherited nor constructed, and aliases for attribute and class names are not recognized.
Flags That Control Event Filtering:
DAPI_EVENT_MIN
Logs start and stop messages. Provides no warning or error logging.
DAPI_EVENT_SOME
Logs Start, Stop, and Error messages.
DAPI_EVENT_ALL
Logs Start, Stop, Error, and Warning messages.
pszDSA
The name of the directory service agent where the schema is read.

Return Values

None.

Remarks

The SchemaPreload function is optional. It allows an image of the directory schema to be loaded by a separate Windows NT Server thread while the directory access process is being initialized. For example, your program can load the schema while a user is entering import or export parameters in a dialog.

Microsoft Exchange Server uses the schema that was loaded into the schema cache for all subsequent directory access operations, until one of the following events occurs:

  • DAPI.DLL is unloaded from memory.
  • SchemaPreload is called with the DAPI_FORCE_SCHEMA_LOAD flag, which flushes current schema values in the cache and reloads a new copy of the schema.
  • A directory access or export operation is specified with a different messaging site.

For more information on this function, see Using Directory Access Functions.

See Also

BatchExport, BatchImport, DAPIRead, DAPIWrite


ServiceMain

The ServiceMain function is implemented by the server application developer to perform processing while a service of Windows NT Server runs.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

VOID ServiceMain(
  HANDLE hShutdownEvent
);

Parameters

hShutdownEvent
Input parameter. Handle to a Shutdown event.

Return Values

None.

Remarks

ServiceMain executes in its own thread.

For more information on this function, see Using WINWRAP Functions.

For more information on the WINWRAP library, see Mandatory Entry Points and Variables and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceStop


ServiceStop

The ServiceStop function stops the service.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

VOID ServiceStop(
  VOID
);

Parameters

None.

Return Values

None.

Remarks

ServiceStop can be used by any thread.

For more information on this function, see the ServiceStop function in WINWRAP.C under the WINWRAP code sample in the Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

fIsService, FServiceReportStatus, HrServiceConfirmStop, HrServiceGetArgv, HrServiceGetName, HrServiceProcessControl, HrServiceShutdown, HrServiceStartup, HrServiceWaitForContinue, HrServiceWaitForControl, HrServiceWaitForStop, HServiceCreateThread, ServiceMain, SetServiceExitCode


SetServiceExitCode

The SetServiceExitCode function sets the service exit code.

Quick Info

Header file: | WINWRAP.H
Library: | WINWRAP.LIB

VOID SetServiceExitCode(
  DWORD dwWin32ExitCode,
  DWORD dwServiceSpecificExitCode
);

Parameters

dwWin32ExitCode
Input parameter. Win32 exit code.
dwServiceSpecificExitCode
Input parameter. Service-specific exit code

Return Values

See Return Values.

Remarks

The dwWin32ExitCode parameter specifies a Win32 error code that the service uses to report an error that occurs when starting or stopping. To return an error code specific to the service, the service must set this value to ERROR_SERVICE_SPECIFIC_ERROR to indicate that the dwServiceSpecificExitCode member contains the error code. The service should set this value to NO_ERROR when it is running and on normal termination.

The dwServiceSpecificExitCode parameter specifies a service specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the dwWin32ExitCode argument is set to ERROR_SERVICE_SPECIFIC_ERROR.

For more information on this function, see the SetServiceExitCode function in WINWRAP.C under the WINWRAP code sample in the Code Samples folder.

For more information on the WINWRAP library, see Using WINWRAP Functions, Mandatory Entry Points and Variables, and Events Signalled.

See Also

ServiceStop


ShowPageProc

ShowPageProc (optional Administrator extension DLL function) is called by the Microsoft Exchange Server Administrator program to identify whether it can display one of the standard property pages for this object.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

BOOL ShowPageProc(
  UINT iddAdminPage
);

Parameters

iddAdminPage
Input parameter. Dialog identifier of a standard property page. The dialog identifiers are defined in ADMINEXT.H.

Return Values

See Return Values.

Remarks

The Administrator program calls ShowPageProc for each standard property page, passing the dialog identifier of the page.

If this function is not provided by the Administrator extension DLL, the Administrator program displays all of the standard property pages.

For more information on this function, see Inhibiting Standard Property Pages.

See Also

ADMIN_Initialize, StartPageProc


StartPageProc

StartPageProc (optional Administrator extension DLL function) is called by the Microsoft Exchange Server Administrator program to determine which property page to display when it opens an object's property sheet.

Quick Info

Header file: | ADMINEXT.H
Library: | ADMINEXT.LIB

INT StartPageProc(
  VOID
);

Return Values

-1
Display the first standard property page.
i
Display property page [i], from the array of property pages returned by InitSheetProc.

Remarks

The Administrator program calls StartPageProc to determine which property page to display when the property sheet opens.

If the StartPageProc function is not supplied, the Administrator program decides which property page to display first.

For more information on this function, see Using Administrator Extension Functions (Called by Administrator Program).

See Also

ADMIN_Initialize, InitSheetProc, ShowPageProc


UpdateProgressProc

The file-based batch processing functions of the directory functions invoke a callback function based on the UpdateProgressProc prototype that is called after the processing of each batch item.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: |

BOOL (* UpdateProgressProc)(
  LPVOID lpvAppDefined
);

Parameters

lpvAppDefined
Points to an application-defined parameter.

Return Values

Return FALSE if the user cancels the operation; return TRUE otherwise.

Remarks

Directory access functions can sometimes take a lot of time to execute because they are performing actions on dozens or thousands of items. During this execution time, the calling application can display the progress of the operation in a number of ways. The default progress display is a modeless dialog box that can be overridden by the calling application. The application can use the CALLBACKPROGRESS structure and the functions based on the definitions InitProgressProc, UpdateProgressProc, and EndProgressProc to display its own progress indicator.

The NTExport function is called for each Windows NT user processed, the BatchExport function is called for each object read from the directory, and the BatchImport function is called for each line processed in the import file.

For more information on this function, see Using Directory Access Functions.

See Also

CALLBACKPROGRESS, EndProgressProc, InitProgressProc, ResetProgressProc, UpdateProgressTextProc


UpdateProgressTextProc

The file-based batch processing functions of the directory functions invoke a callback function based on the UpdateProgressTextProc prototype after processing each batch item.

Quick Info

Header file: | DAPI.H
Library: | DAPI.LIB
Unicode: |

BOOL (* UpdateProgressTextProc)(
  LPVOID lpvAppDefined,
  LPTSTR pszText
);

Parameters

lpvAppDefined
Points to an application-defined parameter.
pszText
Input parameter. Text describing progress.

Return Values

Return FALSE if the user cancels the operation; return TRUE otherwise.

Remarks

The UpdateProgressTextProc function is similar to UpdateProgressProc, except that the callback function is passed a string describing the object being processed. The string can be used to update the progress display.

For more information on this function, see Using Directory Access Functions.

See Also

CALLBACKPROGRESS, EndProgressProc, InitProgressProc, ResetProgressProc, UpdateProgressProc


Structures

The following table lists the primary Microsoft Exchange Server structures and the header files where they are found:

Structure | Header File
ACTION | EDKMDB.H
ACTIONS | EDKMDB.H
ADMIN_AdministratorConnections | ADMINEXT.H
ADMIN_AdministratorFunction | ADMINEXT.H
ADMIN_ExtensionFunction | ADMINEXT.H
ADMIN_ObjectInfo | ADMINEXT.H
ADMIN_SheetInfo | ADMINEXT.H
ADVISENOTIFY | EDKCFG.H
ADVISEOBJ | EDKCFG.H
ATT_VALUE | DAPI.H
BEXPORT_PARMS | DAPI.H
BIMPORT_PARMS | DAPI.H
CALLBACKPROGRESS | DAPI.H
CONVDLLVECT | CONVSTRC.H
COUNTERDEF | MONITOR.H
DAPI_ENTRY | DAPI.H
DAPI_EVENT | DAPI.H
DAPI_PARMS | DAPI.H
EDB_RSTMAP | EDBBCLI.H
EDKCNVENV | CONVSTRC.H
EDKEVENTCOUNT | EDKEVENT.H
ERROR_CALLBACK | DAPI.H
EXPORT_CALLBACK | DAPI.H
INTTRACEENTRY | EDKMDB.H
INTTRACEINFO | EDKMDB.H
NAME_INFO | DAPI.H
NTEXPORT_PARMS | DAPI.H
NWEXPORT_PARMS | DAPI.H
PROXYINFO | RPCPUB.H
PROXYLIST | RPCPUB.H
PROXYNODE | RPCPUB.H
READSTATE | EDKMDB.H
RECIPIENTINFO | PROXYINF.H
ROWENTRY | EDKMDB.H
ROWLIST | EDKMDB.H
RPC_GATEWAY_TRACK_INFORMATION | RPCPUB.H
RPCBINDINFO | SADAPI.H
RTFSYNCINFO | RTFLIB.H
SInitPropValue | EXADMIN.H
SITE_INFO | DAPI.H
TRACEENTRY | EDKMDB.H
TRACEINFO | EDKMDB.H


ACTION

The ACTION structure contains one or more actions that are executed when a rule on a public folder is triggered.

Quick Info

Header file: EDKMDB.H

typedef struct
{
  ACTTYPE          cttype;
  ULONG            ulActionFlavor;
  LPSRestriction   lpRes;
  LPSPropTagArray  lpPropTagArray;
  ULONG            ulFlags;
  ULONG            dwAlignPad;

  union
  {
    struct
    {
      ULONG      cbStoreEntryId;
      LPENTRYID  lpStoreEntryId;
      ULONG      cbFldEntryId;
      LPENTRYID  lpFldEntryId;
    }  actMoveCopy;

    struct
    {
      ULONG      cbEntryId;
      LPENTRYID  lpEntryId;
      GUID       guidReplyTemplate;
    }  actReply;

    struct
    {
      ULONG    cbData;
      BYTE  *  pbData;
    }  actDeferAction;

    SCODE       scBounceCode;
    LPADRLIST   lpadrlist;
    SPropValue  propTag;
  };
}  ACTION, FAR * LPACTION;

Members

acttype
The type of action:
OP_MOVE
Moves the message.
OP_COPY
Copies the message.
OP_REPLY
Replies to the message.
OP_OOF_REPLY
Sends an Out of Office reply to the message.
OP_DEFER_ACTION
Doesn’t do anything right now.
OP_BOUNCE
Rejects the message back to the sender.
OP_FORWARD
Forwards the message to another recipient.
OP_DELEGATE
Assigns the message to another recipient.
OP_TAG
Adds a property to the message.
OP_DELETE
Deletes the message.
OP_MARK_AS_READ
Marks the message as read.
ulActionFlavor
For acttype OP_REPLY, you can set:
DO_NOT_SEND_TO_ORIGINATOR
Does not send a copy of the message to the originator. Default.
lpRes
Action restriction. This member is unused and must be set to NULL.
lpPropTagArray
Properties to tag the message. This member is unused and must be set to NULL.
ulFlags
User-defined flags.
dwAlignPad
Padding to align the structure on an 8-byte (64 bit) boundary.

The next four members specify where the message or the copy of the message ends up when acttype is OP_MOVE or OP_COPY, respectively:

cbStoreEntryId
The number of bytes in the store entry identifier where the lpStoreEntryId member points.
lpStoreEntryId
The entry identifier of the store where the message is copied or moved.
cbFldEntryId
The number of bytes in the folder entry identifier where the lpFldEntryId member points.
lpFldEntryId
The entry identifier of the folder where the message is copied or moved.

The next three members specify the reply when acttype is OP_REPLY or OP_OOF_REPLY:

cbEntryId
The number of bytes in the entry identifier where the lpEntryId member points.
lpEntryId
The entry identifier.
guidReplyTemplate
The template of the reply.

The next two members specify the deferment action when acttype is OP_DEFER_ACTION:

cbData
The number of bytes in the pbData member.
pbData
A buffer of data that is sent to the client process to interpret.
scBounceCode
An error code to set when acttype is OP_BOUNCE:
BOUNCE_MESSAGE_SIZE_TOO_LARGE
The message was refused because it was too large.
BOUNCE_FORMS_MISMATCH
The form was refused because it was developed on an incompatible DLL.
BOUNCE_ACCESS_DENIED
The message was denied for unknown reasons.
lpadrlist
Points to an array of ADRLIST structures, which contain the addresses when acttype is OP_FORWARD or OP_DELEGATE.
propTag
Points to an SPropValue structure, which contains properties when acttype is OP_TAG.

Remarks

The IExchangeFolderRules::HrGet and IExchangeFolderRules::HrInsert methods both contain a parameter that points to an ACTIONS structure, which contains an array of pointers to ACTION structures.

For additional information on this structure, see Working with Rules. For information on the ADRLIST and SPropValue structures, see the MAPI Programmer’s Reference

See Also

ACTIONS


ACTIONS

The ACTIONS structure contains all of the actions that can be executed on a public folder.

Quick Info

Header file: EDKMDB.H

typedef struct
  {
  ULONG     ulVersion;
  UINT      cActions;
  ACTION *  lpAction;
  }  ACTIONS;

Members

ulVersion
Set this to EDK_RULES_VERSION, which is defined in EDKMDB.H.
cActions
The number of ACTION structures pointed to by lpAction.
lpAction
An array of ACTION structures.

Remarks

For additional information on this structure, see Working with Rules.

See Also

ACTION


ADMIN_AdministratorConnections

The ADMIN_AdministratorConnections structure contains pointers that can be used by an Administrator extension DLL.

Quick Info

Header file: ADMINEXT.H

typedef struct
  {
  IMAPISession *  psesMapi;
  IAddrBook *     pab;
  IABContainer *  pabContainer;
  }  ADMIN_AdministratorConnections;

Members

psesMapi
Points to an IMAPISession interface, which is a MAPI session.
pab
Points to an IAddrBook interface, which is an address book.
pabContainer
Points to an IABContainer interface, which is an address book container.

Remarks

The ADMIN_AdministratorConnections structure is passed to the Administrator extension DLL when it is initialized with the ADMIN_Initialize function.

For additional information on this structure, see Initializing Connections with ADMIN_Initialize. For information on the IABContainer, IAddrBook, and IMAPISession interfaces, see the MAPI Programmer’s Reference

See Also

ADMIN_Initialize


ADMIN_AdministratorFunction

The ADMIN_AdministratorFunction structure contains pointers to functions within the Microsoft Exchange Server Administrator program that can be called by the Administrator extension DLL.

Quick Info

Header file: ADMINEXT.H

typedef struct
{
  PADMIN_GetObjectDataSize   pfnGetObjectDataSize;
  PADMIN_GetObjectData       pfnGetObjectData;
  PADMIN_SetObjectData       pfnSetObjectData;
  PADMIN_AddService          pfnAddService;
  PADMIN_RemoveService       pfnRemoveService;
  PADMIN_InfoHasChanged      pfnInfoHasChanged;
  PADMIN_SetIcon             pfnSetIcon;
  PADMIN_SetTitle            pfnSetTitle;
  PADMIN_GetNameList         pfnGetNameList;
  PADMIN_FreeNameList        pfnFreeNameList;
  PADMIN_SetNameList         pfnSetNameList;
  PADMIN_LoadDialogResource  pfnLoadDialogResource;
  PADMIN_FreeDialogResource  pfnFreeDialogResource;
}  ADMIN_AdministratorFunction;

Members

pfnGetObjectDataSize
Points to the function that retrieves the number of bytes returned by the function where pfnGetObjectData points. For additional information, see the PADMIN_GetObjectDataSize function prototype.
pfnGetObjectData
Points to the function that retrieves extension data defined by the Administrator extension DLL. For additional information, see the PADMIN_GetObjectData function prototype.
pfnSetObjectData
Points to the function that sets the extension data defined by the Administrator extension DLL. For additional information, see the PADMIN_SetObjectData function prototype.
pfnAddService
Points to the function that adds a service to the list of services monitored by Microsoft Exchange Server. For additional information, see the PADMIN_AddService function prototype.
pfnRemoveService
Points to the function that removes a service from the list of services monitored by Microsoft Exchange Server. For additional information, see the PADMIN_RemoveService function prototype.
pfnInfoHasChanged
Points to the function that indicates information has changed within a service’s property sheet. The Administrator extension DLL calls this function to indicate that data has changed on a property page. For additional information, see the PADMIN_InfoHasChanged function prototype.
pfnSetIcon
Points to the function that indicates where to display the service’s icon on the Administrator extension DLL’s property page. For additional information, see the PADMIN_SetIcon function prototype.
pfnSetTitle
Points to the function that indicates where to display the service’s title on the Administrator extension DLL’s property page. For additional information, see the PADMIN_SetTitle function prototype.
pfnGetNameList
Points to the function that returns the address list for a gateway object. For additional information, see the PADMIN_GetNameList function prototype.
pfnFreeNameList
Points to the function that frees resources used by the function where the pfnGetNameList member points. For additional information, see the PADMIN_FreeNameList function prototype.
pfnSetNameList
Points to the function that sets the name list for a gateway object. For additional information, see the PADMIN_SetNameList function prototype.
pfnLoadDialogResource
Points to the function that loads the dialog template from the Administrator extension DLL resource file and modifies it to the current font. For additional information, see the PADMIN_LoadDialogResource function prototype.
pfnFreeDialogResource
Points to a function that frees resources used by the function where the pfnLoadDialogResource member points. For additional information, see the PADMIN_FreeDialogResource function prototype.

Remarks

The ADMIN_AdministratorFunction structure is passed as a parameter to the Admin_Initialize function, which initiates handshaking between the Administrator program and the Administrator extension DLL.

For additional information on this structure, see Using administrator Extension Functions (Called by Extension DLL).

See Also

ADMIN_ExtensionFunction


ADMIN_ExtensionFunction

The ADMIN_ExtensionFunction structure contains pointers to functions within the Administrator extension DLL that can be called by the Microsoft Exchange Server Administrator program.

Quick Info

Header file: ADMINEXT.H

typedef struct
{
  int                        nAPIVersion;
  PADMIN_InstallExtension    pfnInstallExtension;
  PADMIN_DeinstallExtension  pfnDeinstallExtension;
  PADMIN_InitSheet           pfnInitSheet;
  PADMIN_ShowPage            pfnShowPage;
  PADMIN_StartPage           pfnStartPage;
  PADMIN_HasHelp             pfnHasHelp;
  PADMIN_DoHelp              pfnDoHelp;
  PADMIN_SaveData            pfnSaveData;
  PADMIN_CommitData          pfnCommitData;
  PADMIN_DeinitSheet         pfnDeinitSheet;
}  ADMIN_ExtensionFunction;

The pointers in this structure (except pfnInitSheet) can be NULL. If a pointer is NULL, no call is made.

Members

nAPIVersion
The version number of the API.
pfnInstallExtension
Points to a function that installs the gateway or mailbox agent. For additional information, see the InstallExtensionProc function prototype.
pfnDeinstallExtension
Points to a function that deinstalls the gateway or mailbox agent. For additional information, see the DeinstallExtensionProc function prototype.
pfnInitSheet
Points to a function that initializes the extension’s property page structures. For additional information, see the InitSheetProc function prototype.
pfnShowPage
Points to a function that indicates whether a property page should be displayed. For additional information, see the ShowPageProc function prototype.
pfnStartPage
Points to a function that returns the first property page of the property sheet the extension wants displayed. For additional information, see the StartPageProc function prototype.
pfnHasHelp
Points to a function that indicates whether the extension supports a Help file. For additional information, see the HasHelpProc function prototype.
pfnDoHelp
Points to a function that is called when the user requests Help information from within the extension’s property page. For additional information, see the DoHelpProc function prototype.
pfnSaveData
Points to a function that is called when data that has been changed within a property page is to be validated. For additional information, see the SaveDataProc function prototype.
pfnCommitData
Points to a function that is called when data that has been changed within a property page is to be committed to the Microsoft Exchange Server directory. For additional information, see the CommitDataProc function prototype.
pfnDeinitSheet
Points to a function that is called when the Administrator extension DLL is about to be closed. This enables the extension DLL to free its resources. For additional information, see the DeinitSheetProc function prototype.

Remarks

The ADMIN_ExtensionFunction structure is passed as a parameter to the Admin_Initialize function, which initiates handshaking between the Administrator program and the Administrator extension DLL.

For additional information on this structure, see Initializing Connections with ADMIN_Initialize.

See Also

ADMIN_AdministratorFunction


ADMIN_ObjectInfo

The ADMIN_ObjectInfo structure contains information about the environment of an Administrator extension DLL.

Quick Info

Header file: ADMINEXT.H

typedef struct
{
  LPWSTR  szComputerName;
  LPWSTR  szDistinguishedName;
  LPWSTR  szDNHomeMDB;
  LPWSTR  szDNHomeMTA;
  LCID    lcid
  UINT    uObjectID
  HFONT   hfontDialog;
}  ADMIN_ObjectInfo;

Members

szComputerName
Name of the server on which the gateway runs, when applicable.
szDistinguishedName
Distinguished name of the object administered.
szDNHomeMDB
Distinguished name of the home server running the Microsoft Exchange Server information store.
szDNHomeMTA
Distinguished name of the home server running the message transport agent.
lcid
An identifier that indicates where the Microsoft Exchange Server Administrator program is running. Valid values are defined in WINNT.H.
uObjectID
Object identifier code. Valid values are:
ObjID_UK
UnKnown
ObjID_DSFirst
First Directory Service DOC
ObjID_EP
Organization
ObjID_DM
Domain (Site)
ObjID_CT
Container
ObjID_SV
Server

Recipients

ObjID_MR
Mail Recipients
ObjID_MB
Mailbox
ObjID_DL
Distribution List
ObjID_RR
Remote Recipient
ObjID_PF
Public Folder
ObjID_MA
Mail Agent

Connections

ObjID_GW
Gateway
ObjID_MGW
Microsoft Mail Connector
ObjID_DXAREQ
Directory Transfer Agent requestor (was Remote DXA)
ObjID_DXASV
Directory Transfer Agent Site server
ObjID_DXACONN
Directory Transfer Agent Server Connection
ObjID_ISC
Site Connection
ObjID_LNKRAS
Dynamic RAS Connector
ObjID_LNKTCP
TCP (RFC1006) X.400 Connector
ObjID_LNKTP4
TP4 X.400 Connector
ObjID_LNKX25
X.25 X.400 Connector
ObjID_DRC
Directory Replication Connector

Server Objects

ObjID_MTA
MTA
ObjID_DSA
Directory Service Agent
ObjID_LDSA
Local Directory Service Agent
ObjID_MDB
Information Store
ObjID_PMDB
Public Information Store
ObjID_LDXA
Local Directory Transfer Agent
ObjID_SAA
System Attendant
ObjID_STKRAS
RAS MTA Transport Stack
ObjID_STKTCP
TCP (RFC1006) MTA Transport Stack
ObjID_STKTP4
TP4 MTA Transport Stack
ObjID_STKX25
X.25 MTA Transport Stack

Monitor Configurations

ObjID_MSV
Monitoring Server Configuration (DS)
ObjID_MLK
Monitoring Link Configuration (DS)

Templates

ObjID_ATP
Address Type
ObjID_ATL
Address Template
ObjID_DTL
Display Template

Schema Objects

ObjID_Schema
The Schema container (DMD)
ObjID_SchemaAttr
Schema Attribute
ObjID_SchemaObj
Schema Object
hfontDialog
A handle to the font being used by the Administrator program.

See Also

DeInstallExtensionProc, InitSheetProc


ADMIN_SheetInfo

The ADMIN_SheetInfo structure contains information about the property page for an Administrator extension DLL.

Quick Info

Header file: ADMINEXT.H

typedef struct
{
  HINSTANCE  hInstance;
  UINT       iddDialog;
  DLGPROC    lpfnDlgProc;
  UINT       idsName;
  LPARAM     lParam;
  LANGID     langid;
}  ADMIN_SheetInfo;

Members

hInstance
The instance handle of the DLL.
iddDialog
The resource identifier of the dialog in the DLL resource file.
lpfnDlgProc
Points to a function in the Administrator extension DLL that processes the messages for the dialog window. For additional information, see the PADMIN_LoadDialogResource function prototype.
idsName
The text that appears on the property page tab. Because this member is a resource identifier for a resource string, the administrator has the option of changing this resource string on the fly with a resource editor.
lParam
Up to 4 bytes (32 bits) of information that the Administrator program passes to the Administrator extension DLL dialog function defined in lpfnDlgProc when the WM_INITDIALOG message is received.
langid
The language identifier of the dialog to be loaded. See WINNT.H.

Remarks

For additional information on this structure, see Initializing Connections with ADMIN_Initialize.

See Also

InitSheetProc


ADVISENOTIFY

The ADVISENOTIFY structure contains binary extension data that is being monitored. Do not modify the data being monitored.


ADVISEOBJ

The ADVISEOBJ structure contains a MAPI session whose extension data is being monitored. Do not modify the data being monitored.


ATT_VALUE

The ATT_VALUE structure contains either an attribute name or one or more attribute values for directory access operations.

Quick Info

Header file: DAPI.H

typedef struct
{
  DAPI_DATA_TYPE       DapiType;
  DAPI_VALUE           Value;
  UINT                 size;
  struct _ATT_VALUE *  pNextValue;
}  ATT_VALUE, * PATT_VALUE;

Members

DapiType
How to evaluate the type of the DAPI_VALUE union. The valid values are:
DAPI_NO_VALUE
No property.
DAPI_STRING8
The property is of type PT_STRING8.
DAPI_UNICODE
The property is of type PT_UNICODE.
DAPI_BINARY
The property is of type PT_BINARY.
DAPI_INT
The property is of type PT_INT.
DAPI_BOOL
The property is of type PT_BOOLEAN.

For additional information on property types, see Microsoft Exchange Server Property Types.

Value
A DAPI_VALUE union containing either the name of the attribute or the value of the attribute. For exported attribute names, DapiType is either DAPI_STRING8 or DAPI_UNICODE.

The DAPI_VALUE union is defined as follows:

typedef union
{
   LPSTR    pszA;
   LPWSTR   pszW;
#ifdef UNICODE
   LPWSTR   pszValue;
#else
   LPSTR    pszValue;
#endif
   LPBYTE   lpBinary;
   INT      iValue;
   BOOL     bool;
} DAPI_VALUE, * PDAPI_VALUE;
pszA
The name of the attribute when DapiType is DAPI_STRING8.
pszW
The name of the attribute when DapiType is DAPI_UNICODE.
pszValue
The value of the attribute when DapiType is DAPI_UNICODE (when UNICODE is defined) or DAPI_STRING8 (when UNICODE is not defined).
lpBinary
The value of the attribute when DapiType is DAPI_BINARY.
iValue
The value of the attribute when DapiType is DAPI_INT.
bool
The value of the attribute when DapiType is DAPI_BOOL.
size
Either the length, in chars, of the string in Value, if DapiType is DAPI_STRING8 or DAPI_UNICODE; or the size, in bytes, of the attribute in Value, if DapiType is DAPI_BINARY, DAPI_INT, or DAPI_BOOL.
pNextValue
Points to the next ATT_VALUE structure; NULL if this is the last or only attribute name or value (see Remarks).

Remarks

For ATT_VALUE structures in BatchExport function callbacks, the data is valid only during the export callback. As soon as program control returns to the calling function (BatchExport), the values in all ATT_VALUE structures are no longer valid.

Each ATT_VALUE structure stores either the name of an attribute or the values for an attribute. If 15 attributes are exported in a given operation, 15 ATT_VALUE structures are created. If any of the attributes in the directory are valueless, their corresponding ATT_VALUE structures are empty. The only exception to this rule is when data is exported in the TEXT_LINE format. In this case, a single ATT_VALUE structure contains all attribute names, and another ATT_VALUE structure contains all attribute values in a single, delimited, text string.

Initial attributes (single-valued attributes and the first value of multivalued attributes) use an array of ATT_VALUE structures. Subsequent values of multivalued attributes are written to additional ATT_VALUE structures in a linked list. The pNextValue member points to the second (and subsequent) members of this linked list. In the case of a TEXT_LINE exporting multiple values for multivalued attributes, these attributes are stored in a single text string, delimited by the multivalued delimiter.

For additional information on this structure, see Interpreting Exported Data and Importing Multivalued Properties with DAPIWrite.

See Also

BatchExport, BEXPORT_PARMS, DAPI_ENTRY, DAPIRead, DAPIWrite


BEXPORT_PARMS

The BEXPORT_PARMS structure contains information for the BatchExport function.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  DWORD             dwDAPISignature;
  DWORD             dwFlags;
  HWND              hwndParent;
  LPTSTR            pszExportFile;
  UINT              uCodePage;
  LPTSTR            pszDSAName;
  LPTSTR            pszBasePoint;
  LPTSTR            pszContainer;
  TCHAR             chColSep;
  TCHAR             chQuote;
  TCHAR             chMVSep;
  TCHAR             cReserved;
  CALLBACKPROGRESS  ProgressCallBacks;
  ERROR_CALLBACK    ErrorCallback;
  EXPORT_CALLBACK   ExportCallback;
  PDAPI_ENTRY       pAttributes;
  LPTSTR            pszHomeServer;
  LPTSTR *          rgpszClasses;
  ULONG             ulUSNBase;
  LPVOID            pReserved;
}  BEXPORT_PARMS, *PBEXPORT_PARMS, *LPBEXPORT_PARMS;

Members

dwDAPISignature
Must be set to the defined value DAPI_SIGNATURE (see DAPI.H). Verifies that the parameter sequence used by the calling application is the same as that expected by the directory functions.
dwFlags
Defined values that control the directory export operation (see BatchExport). Use the bitwise OR operator (|) to enable multiple operations:
DAPI_EXPORT_MAILBOX
Exports mailbox recipient objects.
DAPI_EXPORT_CUSTOM
Exports remote address recipient objects.
DAPI_EXPORT_DIST_LIST
Exports distribution list objects.
DAPI_EXPORT_RECIPIENTS
Exports all recipient objects.
DAPI_EXPORT_ALL_CLASSES
Exports all object classes.
DAPI_EXPORT_HIDDEN
Exports any hidden objects. By default, if the Hide-From-Address-Book attribute is set, hidden objects are not exported.
DAPI_EXPORT_SUBTREE
Exports the directory object and any directory objects beneath it in the DIT.
DAPI_EXPORT_BASEPOINT_ONLY
Exports only the requested attributes from the object identified by pszBasePoint.
DAPI_EVENT_MIN
Logs start and stop messages; does not log warning or error messages.
DAPI_EVENT_SOME
Logs start, stop, and error messages; does not log warning messages.
DAPI_EVENT_ALL
Logs all messages (start, stop, error, and warning).
DAPI_FORCE_SCHEMA_LOAD
Unloads a previously loaded schema and reads the schema again. The default action is to reuse the previously loaded schema if it is read from the same messaging domain.
DAPI_RAW_MODE
Exports data in raw mode (export lines are taken literally). No properties are inherited or constructed. Aliases for property and class names are not recognized.
DAPI_SUPPRESS_PROGRESS
Suppresses the progress thermometer that normally appears during batch operations.
DAPI_SUPPRESS_COMPLETION
Suppresses the notification message window that normally appears following the completion of a batch operation.
DAPI_SUPPRESS_ARCHIVES
Suppresses the creation of an archive copy of any output files that normally are created during batch operations.
hwndParent
The window handle to use when displaying message boxes. Set this member to NULL to use the handle of the main window of the calling application.
pszExportFile
The fully qualified path of the file where the directory information tree objects are exported. BatchExport ignores this member if the ExportCallback member is specified.
uCodePage
The code-page specification (text format) for the export file:
DAPI_UNICODE_FILE
The export file is created in Unicode format.
0
If the export files exists, the data is exported in the format of the existing export file. Otherwise, the export file is created in ANSI format.
other
The export file is created in this ANSI code-page format. This ANSI code-page format must already be installed on the system.

If this member is DAPI_UNICODE_FILE (which specifies that the DIT object is in Unicode format), but the DIT object is in ANSI format, BatchExport fails and emits a diagnostic error message in the Windows NT Application event log.

BatchExport also fails and emits a diagnostic error message in the Windows NT Application event log if this member is a format other than DAPI_UNICODE_FILE or 0 (zero, which is autodetect) and either of the following conditions is true:

  • The format is not supported by the system.
  • The output file exists and is in Unicode format.
pszDSAName
The directory service agent to use when exporting objects. If this member is NULL, BatchExport attempts to find a directory service agent on the local computer. Otherwise, BatchExport broadcasts for a directory service agent to the servers on its network and uses the name that is returned as a result of the broadcast.

If this member is NULL, BatchExport searches for a DSA in the following order:

  1. If a DSA exists on the local computer, use it.
  2. Otherwise, broadcast for a DSA and use one of the DSAs that replies.

Use MAPI function calls to determine the DSA. See the MAPI Programmer’s Reference for more information.

pszBasePoint
The distinguished name of the messaging site or container that serves as the directory information tree basepoint for bulk operations. A distinguished name is the combination of an object’s path and name in the Xopen hierarchical naming structure.

If this member is NULL, the basepoint is the current site object where the DSA resides (as specified by the lpBexportParms->pszDSAName parameter member); if lpBexportParms->pszBasePoint is ““ (an empty string), the basepoint is the current organization object. The basepoint is the point in the DIT where BatchExport performs its bulk object creation or bulk object manipulation operations.

pszContainer
The distinguished name or relative distinguished name of the default container where objects are exported. If this member is NULL, BatchExport assumes that the container is below the level indicated by the pszBasePoint member. If this member is a relative distinguished name, BatchExport assumes that the container is relative to the level indicated by the pszBasePoint member. The container name in the import file can override this value.

If this member is NULL, BatchExport exports the contents of all containers below the point specified by the pszBasePoint member.

chColSep
The column separator that is used within the export file. Specify your preferred column separator, even if it is the same as the default.

If this member is NULL, BatchExport uses the default separator, which is defined as DEFAULT_DELIM (see DAPI.H).

The default column separator used by the directory functions is unrelated to the default column separator specified within the Administrator program.

chQuote
The character that is used to enclose strings within the export file. Do not use the ~, #, or = characters. Specify your preferred string enclosure separator, even if it is the same as the default.

If this member is NULL, BatchExport uses the default string enclosure character, which is defined as DEFAULT_QUOTE (see DAPI.H).

chMVSep
The value separator for multivalued properties within the export file. A separator character is required, for example, by the members of a distribution list. A percent sign inside a quoted string is interpreted as a literal character. Specify your preferred value separator, even if it is the same as the default.

If this member is NULL, BatchExport uses the default multivalue separator character, which is defined as DEFAULT_MV_SEP (see DAPI.H).

cReserved
Unused and reserved for future use.
ProgressCallBacks
A structure that contains pointers to functions that display the progress of the operation.

If this member is NULL, BatchExport displays a default modeless dialog to show progress.

ErrorCallback
A structure that contains a pointer to a function that is to be called on each error encountered.

If this member is NULL, BatchExport calls the default error handler, which displays an error dialog window and writes the error into the Windows NT Application event log.

ExportCallback
A structure that contains a pointer to a function that is to be called on each exported item.

If this member is NULL, BatchExport writes to the file specified by the pszExportFile parameter member.

pAttributes
Points to a DAPI_ENTRY structure containing the names of attributes to export.

If you specify export attributes in this member, the first attribute in pAttributes must be NM_OBJECT_CLASS; otherwise, BatchExport fails.

Normally, BatchExport does not export deleted objects. You can export directory objects that are deleted, but not purged, by including the NM_IS_DELETED attribute.

The pAttributes member is required if the ExportCallback member is specified; it is optional if the pszExportFile member is specified.

pszHomeServer
Only objects that reside on this server are exported. If this member is not NULL, only mailboxes are exported, as they are the only objects that reside on a server.

This member specifies that the mailboxes from only the specified server are exported. If pszHomeServer is NULL, BatchExport exports the mailboxes from all servers.

rgpszClasses
An array of pointers to zero-terminated strings specifying the object classes to export. The last entry must be NULL. The object classes can also be specified in dwFlags, but the values in this member take precedence over any class settings in dwFlags.

BatchExport queries the directory for objects of the specified classes in the order that you specify the classes in this member.

ulUSNBase
Update sequence number (USN). If this member is nonzero, only objects whose USN-Changed attribute is greater than this value are exported.

BatchExport exports only objects with USN-Changed greater than or equal to this member when EXPORT_USE_USN_BASE is set.

pReserved
Reserved. Must be zero.

Remarks

For additional information on this structure, see Exporting Objects.

See Also

BatchExport


BIMPORT_PARMS

The BIMPORT_PARMS structure contains information for the BatchImport function.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  DWORD             dwDAPISignature;
  DWORD             dwFlags;
  HWND              hwndParent;
  LPTSTR            pszImportFile;
  UINT              uCodePage;
  LPTSTR            pszDSAName;
  LPTSTR            pszBasePoint;
  LPTSTR            pszContainer;
  TCHAR             chColSep;
  TCHAR             chQuote;
  TCHAR             chMVSep;
  TCHAR             creserved;
  CALLBACKPROGRESS  ProgressCallBacks;
  ERROR_CALLBACK    ErrorCallback;
  LPTSTR            pszNTDomain;
  LPTSTR            pszCreateTemplate;
}  BIMPORT_PARMS, *PBIMPORT_PARMS, *LPBIMPORT_PARMS;

Members

dwDAPISignature
Verifies that the parameter sequence used by the calling application is the same as expected by the directory functions. The value should be set to DAPI_SIGNATURE, which is defined in DAPI.H.
dwFlags
Defined values that control the directory import operation (see BatchImport). Use the bitwise OR operator (|) to enable multiple operations:
DAPI_EVENT_MIN
Logs start and stop messages; does not log warning or error messages.
DAPI_EVENT_SOME
Logs start, stop, and error messages; does not log warning messages.
DAPI_EVENT_ALL
Logs all messages (start, stop, error, and warning).
DAPI_FORCE_SCHEMA_LOAD
Unloads a previously loaded schema and reads the schema again. The default action is to reuse the previously loaded schema if it is read from the same messaging domain.
DAPI_RAW_MODE
Imports data in raw mode (import lines are taken literally). No properties are inherited or constructed. Aliases for property and class names are not recognized.
DAPI_SUPPRESS_PROGRESS
Suppresses the progress thermometer that normally appears during batch operations.
DAPI_SUPPRESS_COMPLETION
Suppresses the notification window that normally appears following the completion of a batch operation.
DAPI_SUPPRESS_ARCHIVES
Suppresses the creation of an archive copy of any output files that normally are created during batch operations.
DAPI_OVERRIDE_CONTAINER
The container specified in the parameter block overrides the contents of the container column. The default behavior is for the value specifed in the Obj-Container column to override the value specified in the parameter block.
DAPI_IMPORT_NO_ERR_FILE
Does not create an error file.
DAPI_IMPORT_WRITE_THROUGH
Commits write operations immediately.
DAPI_RESTRICT_ACCESS
Applies the Windows NT Security Descriptor to created objects.
DAPI_MODIFY_REPLACE_PROPERTIES
Overwrites any existing properties when modifying.
DAPI_CREATE_NT_ACCOUNT
Creates Windows NT accounts as required.
DAPI_CREATE_RANDOM_PASSWORD
Generates a random password for newly created Windows NT accounts. This flag is ignored if DAPI_CREATE_NT_ACCOUNT is not set.
DAPI_DELETE_NT_ACCOUNT
Deletes ASSOC_NT_ACCOUNT when deleting a mailbox.
hwndParent
The window handle to use when displaying message boxes. Set this member to NULL to use the handle of the main window of the calling application.
pszImportFile
The fully qualified path of the import file.

BatchImport imports objects from the file specified by this member into the directory information tree (DIT).

uCodePage
The code-page specification (text format) for the import file:
DAPI_UNICODE_FILE
The import file is created in Unicode format.
0
If the import files exists, the data is imported in the format of the existing import file. Otherwise, the import file is created in ANSI format.
other
The import file is created in this ANSI codepage format. This ANSI codepage format must already be installed on the system.

If this member is DAPI_UNICODE_FILE (export the DIT object in Unicode format) and the DIT object is in ANSI format, BatchImport fails and emits a diagnostic error message in the Windows NT Application event log.

BatchImport also fails and emits a diagnostic error message in the Windows NT Application event log if the uCodePage member is a format other than DAPI_UNICODE_FILE or 0 (zero, which is autodetect) and either of the following conditions is true:

  • The format is not supported by the system
  • The output file exists and is in Unicode format.
pszDSAName
The directory service agent (DSA) to use when importing objects. If this member is NULL, BatchImport attempts to find a DSA on the local computer. Otherwise, BatchImport broadcasts for a DSA to the servers on its network and uses the name that is returned as a result of the broadcast.

If this member is NULL, BatchImport searches for a DSA in the following order:

  1. If a DSA exists on the local computer, use it.
  2. Otherwise, broadcast for a DSA and use one of the DSAs that replies.

Use MAPI function calls to determine the DSA. See the MAPI Programmer’s Reference for more information.

pszBasePoint
The distinguished name (DN) of the messaging site or container that serves as the directory information tree basepoint for bulk operations. A DN is the combination of an object’s path and name in the Xopen hierarchical naming structure.

If this member is NULL, the basepoint is the current site object where the DSA, as specified by the pszDSAName parameter member, resides; if pszBasePoint is ““ (an empty string), the basepoint is the current organization object. The basepoint is the point in the DIT where BatchImport performs its bulk object creation or bulk object manipulation operations.

pszContainer
The DN or relative distinguished name (RDN) of the default container where objects are imported. If this member is NULL, BatchImport assumes that the container is below the level indicated by the pszBasePoint member. If this member is an RDN, BatchImport assumes that the container is relative to the level indicated by the pszBasePoint member. The container name in the export file can override this value.

If this member is NULL, BatchImport exports the contents of all containers below the point specified by the pszBasePoint member.

chColSep
The column separator that is used within the export file. Specify your preferred column separator, even if it is the same as the default.

If this member is NULL, Batchimport uses the default separator, which is defined as DEFAULT_DELIM (see DAPI.H).

The default column separator used by the directory functions is unrelated to the default column separator specified within the Administrator program.

chQuote
The character that is used to enclose strings within the export file. Do not use the ~, #, or = characters. Specify your preferred string enclosure separator, even if it is the same as the default.

If this member is NULL, BatchImport uses the default string enclosure character, which is defined as DEFAULT_QUOTE (see DAPI.H).

chMVSep
The value separator for multivalued properties within the export file. A separator character is required, for example, by the members of a distribution list. A percent sign inside a quoted string is interpreted as a literal character. Specify your preferred value separator, even if it is the same as the default.

If this member is NULL, BatchImport uses the default multivalue separator character, which is defined as DEFAULT_MV_SEP (see DAPI.H).

creserved
Unused and reserved for future use.
ProgressCallBacks
A structure that contains pointers to functions that display the progress of the operation.

If this member is NULL, BatchImport displays a default modeless dialog to show progress.

ErrorCallback
A structure that contains a pointer to a function that is to be called on each error encountered.

If this member is NULL, BatchImport calls the default error handler, which displays an error dialog window and posts the error into the Windows NT Application event log.

pszNTDomain
Name of the primary Windows NT Server domain in which to create or find Windows NT accounts. If this parameter is NULL, the function uses the primary Windows NT Server domain name (the domain on which the executing process computer’s account is logged on).

If this member is NULL, BatchImport uses the primary Windows NT Server domain name (the domain where the executing process computer’s account is logged on).

pszCreateTemplate
A DN or RDN of the user object that serves as the template for creating new user objects. If this member is an RDN, BatchImport uses the pszBasePoint and pszContainer members to determine the path to the template. If this member is NULL, BatchImport does not use a template when creating new user objects.

BatchImport reads the properties associated with the default user’s mailbox and uses this information as a standard configuration that all imported user objects inherit. BatchImport caches this information and only updates those properties applicable to the given import object. Set this member to NULL if there is no default template object. See the Microsoft Exchange Server Administrator’s Guide for more information about formatting the template object.

Remarks

For additional information on this structure, see Importing and Manipulating Objects.

See Also

BatchImport


CALLBACKPROGRESS

The CALLBACKPROGRESS structure contains information that is used by the calling application to display a progress indicator.

Quick Info

Header file: DAPI.H

typedef struct
{
  DWORD                      dwFlags;
  LPVOID                     lpvAppDefined;
  PDAPI_FInitProgress        pfnInitProgress;
  PDAPI_FUpdateProgress      pfnUpdateProgress;
  PDAPI_FEndProgress         pfnEndProgress;
  PDAPI_FResetProgress       pfnResetProgress;
  PDAPI_FUpdateProgressText  pfnUpdateProgressText;
}  CALLBACKPROGRESS, *PCALLBACKPROGRESS;

Members

dwFlags
Defined values that control the callback operations. Use the bitwise OR operator (|) to enable multiple operations:
DAPI_CALLBACK_CHAIN
Calls the default callback routine after calling the caller-supplied callback routine, unless the caller-supplied callback routine returns FALSE, which indicates that the operation was canceled.
lpvAppDefined
Application-defined field, passed as a parameter to the callback.
pfnInitProgress
Points to the function based on the InitProgressProc function prototype.
pfnUpdateProgress
Points to a function that initializes the user-defined progress display. For additional information, see the UpdateProgressProc function prototype.
pfnEndProgress
Points to a function that dismisses the update dialog box or exits when a fatal condition in the processing has been encountered. For additional information, see the EndProgressProc function prototype.
pfnResetProgress
Points to a function that resets the user-defined progress display when a new stage of the batch operation has started. For additional information, see the ResetProgressProc function prototype.
pfnUpdateProgressText
Points to a function that displays text to the user about the batch operation. For additional information, see the UpdateProgressTextProc function prototype.

Remarks

Directory functions can sometimes take a lot of time to execute because they are performing actions on large numbers of items. During this execution time, the calling application can display the operation’s progress several ways. The default progress display is a modeless dialog box that the application can override by using the callback progress functionality. The application can also use the CALLBACKPROGRESS structure and display its own progress indicator by using functions based on the definitions of the EndProgressProc, InitProgressProc, ResetProgressProc, UpdateProgressProc, and UpdateProgressTextProc function prototypes.

For additional information on this structure, see Using Directory Access Functions.

See Also

EndProgressProc, InitProgressProc, ResetProgressProc, UpdateProgressProc, UpdateProgressTextProc


CONVDLLVECT

The CONVDLLVECT structure contains the entry points to a conversion.

Quick Info

Header file: CONVSTRC.H

typedef struct
{
  short          nVectorVersion;
  PCONVDLLQUERY  pfnCnvQueryCapability;
  PCONVDLLCONV   pfnCnvConvert;
}  CONVDLLVECT;

typedef CONVDLLVECT * PCONVDLLVECT;

Members

nVectorVersion
Set this to nDesiredConvDllVersion.
pfnCnvQueryCapability
Points to a function that determines whether the conversion can be performed. For additional information, see the PCONVDLLQUERY function prototype.
pfnCnvConvert
Points to a function that performs the conversion. For additional information, see the PCONVDLLCONV function prototype.

See Also

PCONVDLLCONV, PCONVDLLQUERY


COUNTERDEF

The COUNTERDEF structure contains descriptions of performance counters that are used by the HrMonInit function. A table of COUNTERs is created, and Microsoft Exchange Server guarantees that the counters are contiguous and in the same order as they are described in this table.

Quick Info

Header file: MONITOR.H

typedef struct  // cd
{
  DWORD         iCounterTitleOffset;
  COUNTERTYPE   ctStatistic;
  LPMAPIFOLDER  lpFolder;
  PERIODTYPE    perPeriod;
  DWORD         cMinutes;
  LPCOUNTER *   lppcntUserCounter;
  DWORD         dwUserCounterType;
  DWORD         dwDetailLevel
  DWORD         dwDefaultScale
}  COUNTERDEF, * LPCOUNTERDEF;

Members

iCounterTitleOffset
Index of counter name, offset from the first counter, where the value of iCounterTitleOffset for the first counter is 0 (zero).
ctStatistic
The type of statistic monitored by this counter:
COUNTERTYPE_MESSAGES_IN_FOLDER
Total number of messages in folder
COUNTERTYPE_BYTES_IN_FOLDER
Total number of bytes in folder
COUNTERTYPE_MESSAGES_ENTERING_FOLDER
Number of messages entering folder
COUNTERTYPE_BYTES_ENTERING_FOLDER
Number of bytes entering folder
COUNTERTYPE_MESSAGES_LEAVING_FOLDER
Number of messages leaving folder
COUNTERTYPE_MESSAGES_TRANSFERRED_IN
Number of messages transferred into Microsoft Exchange Server
COUNTERTYPE_BYTES_TRANSFERRED_IN
Number of bytes transferred into Microsoft Exchange Server
COUNTERTYPE_MESSAGES_TRANSFERRED_OUT
Number of messages transferred out of Microsoft Exchange Server
COUNTERTYPE_BYTES_TRANSFERRED_OUT
Number of bytes transferred out of Microsoft Exchange Server
COUNTERTYPE_NDRS_IN
Number of NDRs into Microsoft Exchange Server
COUNTERTYPE_NDRS_OUT
Number of NDRs out of Microsoft Exchange Server
COUNTERTYPE_ASSOCIATIONS
Total number of associations
COUNTERTYPE_USER_DEFINED
User-defined counter
lpFolder
Points to an IMapiFolder interface, which is the folder where the counter is from, if applicable.
perPeriod
Period over which the statistics are totalled, if applicable:
PERIODTYPE_NONE
Not a period statistic.
PERIODTYPE_CONTINUOUS
Most-recent performance monitor sampling period.
PERIODTYPE_LAST_N_MINUTES
The past N one-minute intervals, where cMinutes is the value for N.
PERIODTYPE_TOTAL
Everything since the gateway started.
cMinutes
The value for N when perPeriod is PERIODTYPE_LAST_N_MINUTES.
lppcntlUserCounter
Address to return a pointer to user-defined counter; otherwise NULL.
dwUserCounterType
Points to a COUNTER, which is a user-defined counter.
dwDetailLevel
Counter complexity as defined in WINPERF.H:
PERF_DETAIL_NOVICE
PERF_DETAIL_ADVANCED
PERF_DETAIL_EXPERT
PERF_DETAIL_WIZARD
dwDefaultScale
Default scale as defined in WINPERF.H.

Remarks

When an array of COUNTERDEF objects is used, standard counters must come before any user-defined counters in the array (counters whose ctStatistic member has the value COUNTERTYPE_USER_DEFINED). Otherwise, the Performance Monitor can display erroneous counter information.

For additional information on this structure, see Monitoring Performance with PERFTEST. For information on the IMapiFolder interface, see the MAPI Programmer’s Reference.

See Also

HrMonLockCounters, HrMonUnlockCounters


DAPI_ENTRY

The DAPI_ENTRY structure contains either an attribute name or the value of an attribute.

Quick Info

Header file: DAPI.H

typedef struct
{
  UINT        unAttributes;
  DAPI_EVAL   ulEvalTag;
  PATT_VALUE  rgEntryValues;
}  DAPI_ENTRY, * PDAPI_ENTRY;

Members

unAttributes
The number of attribute names or values in the structure.
ulEvalTag
The type of data pointed to by rgEntryValues:
TEXT_LINE
The data items are delimited by commas or other specified characters. The data line format is the same as if the data were written to an export file.
TEXT_VALUE_ARRAY
The items are in an array of structures where binary and nonbinary data is represented as strings. Binary values are exported as strings of hexadecimal digits.
VALUE_ARRAY
The items are in their native type, with a few minor exceptions. For example, any attributes whose native type is object (such as distinguished names or OR names) are represented as text. Also, date fields are represented as UTC strings of the date. Unsigned integer values are represented as integers.
rgEntryValues
This is a pointer to an array of attribute value structures (ATT_VALUE). If ulEvalTag has the value TEXT_LINE, there is a single value with a delimited line, or else there are unAttributes, each with one or more values in the list.

Remarks

For additional information on this structure, see Exporting Objects and Importing and Manipulating Objects.

See Also

ATT_VALUE, BatchExport, DAPI_FNExportEntry


DAPI_EVENT

The DAPI_EVENT structure contains information about errors that are encountered during the execution of a DAPI function.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct _DAPI_EVENT
{
  DWORD               dwDAPIError;
  LPSTR               rgpszSubst[DAPI_MAX_SUBST];
  UINT                unSubst;
  LPSTR               pszAttribute
  LPSTR               pszHoldLine;
  HINSTANCE           hinstDAPI
  struct _DAPI_EVENT  *pNextEvent
}  DAPI_EVENT, * PDAPI_EVENT;

Members

dwDapiError
Message identifier for the event log.
rgpszSubst[DAPI_MAX_SUBST]
Event message substitution array.
unSubst
The number of substitution strings in rgpscSubst[].
pszAttribute
The name of the attribute containing an error. Note: May be NULL on some errors.
pszHoldLine
Points to a buffer that contains a copy of the line containing the error.
hinstDAPI
Instance handle of DAPI.DLL.
pNextEvent
Points to the next event describing another error encountered. This member is NULL for the last error.

Remarks

The DAPI_EVENT structure is returned by the DAPIRead, DAPIStart, and DAPIWrite functions, and passed to error callback functions invoked by the BatchExport, BatchImport, NTExport, and NWExport functions.

Call the WIN32 FormatMessage function to obtain a localized string containing the substitution strings corresponding to the error code. You can then display this information to the user in a dialog box. The messages, which are also string resources, are located in the module DAPI.DLL.

For additional information on this structure, see Using Directory Access Functions. For an example of how to utilize the information that is returned in a DAPI_EVENT structure by a directory function, see the DAPIStart and DAPIWrite function calls in the DIRSYNC.C code sample.

See Also

BatchExport, BatchImport, DAPIRead, DAPIStart, DAPIWrite, NTExport, NWExport


DAPI_PARMS

The DAPI_PARMS structure contains a set of common parameters that are applied to directory calls during the directory session.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  DWORD        dwDAPISignature;
  DWORD        dwFlags;
  LPTSTR       pszDSAName;
  LPTSTR       pszBasePoint;
  LPTSTR       pszContainer;
  LPTSTR       pszNTDomain;
  LPTSTR       pszCreateTemplate;
  PDAPI_ENTRY  pAttributes;
}  DAPI_PARMS, *PDAPI_PARMS, *LPDAPI_PARMS;

Members

dwDAPISignature
Set this value to DAPI_SIGNATURE.
dwFlags
Defined values that control directory operations. Use the bitwise OR operator (|) to enable multiple operations. If you set one of this first group of flags in DAPIStart, you cannot change them in DAPIWrite:
DAPI_MODIFY_REPLACE_PROPERTIES
Overwrites any existing properties when modifying. If this flag is not specified, the imported file’s data is appended to any existing data associated with the property.
DAPI_CREATE_NT_ACCOUNT
Creates a Windows NT security account whenever a mailbox is created. The Windows NT security account password must be changed on the next logon (the first time the newly created account is used). If a Windows NT account for the user already exists, a warning is posted and the existing account is not changed, but an attempt is still made to create a mailbox. Windows NT account creation is only attempted when a mailbox object is being created in the directory.

This flag is ignored when importing custom recipients and distribution lists. The function sets the ASSOC-NT-ACCOUNT property (or attribute) to be that of the Windows NT user if the account creation occurred without error. If ASSOC-NT-ACCOUNT is specified in the import file, this value is used instead of the name of the newly created user. The account will be created in the Windows NT Security Domain specified in the pszNTDomain parameter, unless overridden in the Assoc-NT-Account property value, such as seattle\dougie.

This flag implies DAPI_RESTRICT_ACCESS.

DAPI_CREATE_RANDOM_PASSWORD
Generates random passwords for newly created Windows NT accounts. If this flag is specified, the function creates a password of random uppercase and lowercase characters of a length equal to the minimum required password length for the Windows NT Server domain. The account name and password will be written into the password file. A password of at least four characters is generated if the minimum password length is less then or equal to four.

If this flag is not set, the password is constructed using the account name and padded with Xs to meet the minimum required password length.

DAPI_DELETE_NT_ACCOUNT
When deleting a mailbox, the Windows NT Account named by the mailbox property Assoc-NT-Account will be deleted if this flag is set. If the account does not exist, a warning will be logged, but mailbox deletion will proceed.
DAPI_RESTRICT_ACCESS
Applies a Windows NT Server security descriptor to created objects.

Miscellaneous Flags

DAPI_FORCE_SCHEMA_LOAD
Unloads a previously loaded schema and read the schema again. The default action is to reuse the previously loaded schema if it is read from the same messaging site.
DAPI_RAW_MODE
Imports data in raw mode; which means import lines are taken literally. No properties are inherited or constructed. Aliases for property and class names are not recognized.
DAPI_OVERRIDE_CONTAINER
The container specified in the parameter block overrides the contents of the container column. By default, the value specified in the Obj-Container column overrides the container specified in the parameter block.

Flags for DAPIRead

You can also set these flags in DAPIStart. They remain in effect until you override them. If both flags are set, DAPI_READ_ALL_ATTRIBUTES takes precedence.

DAPI_READ_DEFINED_ATTRIBUTES
Returns all attributes that are set for the current object.
DAPI_READ_ALL_ATTRIBUTES
Returns all attributes that are defined for the class of the current object.

Flags that control event filtering:

DAPI_EVENT_MIN
Logs only start and stop messages, but not warning or error messages.
DAPI_EVENT_SOME
Logs start, stop, and error messages.
DAPI_EVENT_ALL
Logs start, stop, error, and warning messages.
pszDSAName
The computer name of the directory service agent from which to export objects. You can use MAPI function calls to determine this name. See the MAPI Programmer’s Reference for more information.

If NULL, the function attempts to find a directory service agent on the local computer and use its name. Otherwise, the function broadcasts for servers and uses the name that is returned as a result of the broadcast.

pszBasePoint
The distinguished name (DN) of the messaging site or DN of the container that serves as the basepoint in the directory information tree for bulk operations. The basepoint is the point in the directory information tree under which the calling application will perform bulk-object creation or manipulation operations. See BatchExport for an explanation of what occurs when this value is either NULL or an empty string (““).
pszContainer
The DN or relative distinguished name (RDN) of the default container where the bulk operation begins. If this member is NULL, the directory functions assume that the container is below the level indicated by the pszBasePoint member. If this member is an RDN, the directory functions assume that the container is relative to the level indicated by the pszBasePoint member. The container name in the import file can override this value.
pszNTDomain
The name of the primary Windows NT Server domain in which to create or find Windows NT accounts. If this parameter is NULL, the function uses the primary Windows NT Server domain name (the domain on which the executing process’s machine account is logged on). If Windows NT accounts are being created, it is best to specify an actual value for this parameter (that it not be NULL).
pszCreateTemplate
A DN (or RDN) of the user object that serves as the template for creating new user objects. If this member is an RDN, the directory functions use the pszBasePoint and pszContainer members to determine the path to the template. If this member is NULL, the directory functions do not use a template when creating new user objects.
pAttributes
Points to a DAPI_ENTRY structure containing the names of attributes used in the session’s DAPIRead and DAPIWrite function calls. If this member is NULL, DAPIRead and DAPIWrite use attributes passed as arguments.

Note In DAPIStart, the value of the pAttributes member takes precedence over any conflicting dwFlags member values.

Remarks

The DAPI_PARMS structure is a parameter to the DAPIStart function.

For an example of how to initialize the DAPI_PARMS structure, look at the code just before the DAPIStart function call in the DIRSYNC.C code sample.

See Also

BEXPORT_PARMS, BIMPORT_PARMS, DAPI_ENTRY, DAPIStart


EDB_RSTMAP

The EDB_RSTMAP structure contains information on the old and new database names, including the new location.

Quick Info

Header file: EDBBCLI.H

typedef struct
{
  LPTSTR  szDatabaseName;
  LPTSTR  szNewDatabaseName;
}  EDB_RSTMAP, * PEDB_RSTMAP;

Members

szDatabaseName
The name of the database when it was backed up.
szNewDatabaseName
The new name of the database, including its new location, when applicable.

Remarks

For an example of how to use this structure, see the RESTTEST.CPP code sample under the BACKTEST topic.

See Also

HrRestoreRegister


EDKCNVENV

The EDKCNVENV structure contains the environment of a conversion.

Quick Info

Header file: CONVSTRC.H

typedef struct
{
  INT        nVersionEDKCNVENV;
  LPCWSTR    pszConversionPoint;
  LHANDLE    lphSession;
  LPMDB      lpMDB;
  LPADRBOOK  lpAB;
  LPVOID     pGatewayDefined;
}  EDKCNVENV;

typedef EDKCNVENV * PEDKCNVENV;

Members

nVersionEDKCNVENV
Set this to nDesiredConvDllVersion.
pszConversionPoint
Points to a Unicode string to distinguish each conversion used within an application. For example:
SMTP.INBOUND.V1.0.0
Converts inbound SMTP messages for version 1.0 of a gateway.
SMTP.OUTBOUND.V1.0.0
Converts outbound SMTP messages for version 1.0 of a gateway.
lphSession
Points to the handle of the current MAPI logon session.
lpMDB
Points to an IMsgStore interface that is the message store.
lpAB
Points to an IAddrBook interface that is the address book.
pGatewayDefined
Points to an application-specific data structure. For example, a data structure containing a Boolean value indicating whether a TNEF encapsulation should be included on outgoing messages.

Remarks

For an example of how to initialize this structure, see the GWSAMPLE.C code sample. For information on the IAddrBook and IMsgStore interfaces, see the MAPI Programmer’s Reference

See Also

PCONVDLLCONV, PCONVDLLQUERY


EDKEVENTCOUNT

The EDKEVENTCOUNT structure contains a record of the number of events of each type — error, warning, and information — that has been logged.

Quick Info

Header file: EDKEVENT.H

typedef struct
{
  DWORD  cError;
  DWORD  cWarning;
  DWORD  cInformation;
}  EDKEVENTCOUNT, * LPEDKEVENTCOUNT;

Members

cError
The number of error events.
cWarning
The number of warning events.
cInformation
The number of information events.

Remarks

For an example of how to initialize this structure, see the HrEventGetCounts function call in the CFGCODE.C code sample.

See Also

HrEventGetCounts


ERROR_CALLBACK

The ERROR_CALLBACK structure contains information about a function that is invoked on error callback.

Quick Info

Header file: DAPI.H

typedef struct
{
  DWORD                  dwFlags;
  LPVOID                 lpvAppDefined;
  PDAPI_FNErrorCallback  pfnErrorCallback;
}  ERROR_CALLBACK, * PERROR_CALLBACK;

Members

dwFlags
Defined values that control the callback operations. Use the bitwise OR operator (|) to enable multiple operations:
DAPI_CALLBACK_CHAIN
Calls the default error handler after calling the caller-supplied error handler, unless the caller-supplied error handler returns FALSE, indicating cancel the operation.
lpvAppDefined
Application-defined field, which is passed back in the callback.
pfnErrorCallback
Points to a function that is called when an error is encountered. Set this member to NULL to call the default error handler. The default error handler posts the error to the Windows NT Application Event Log. For additional information, see the DAPI_FNErrorCallback function prototype.

See Also

BEXPORT_PARMS, BIMPORT_PARMS, NTEXPORT_PARMS, NWEXPORT_PARMS


EXPORT_CALLBACK

The EXPORT_CALLBACK structure contains information about a function that is invoked on export callback.

Quick Info

Header file: DAPI.H

typedef struct
{
  DWORD                dwFlags;
  DAPI_EVAL            ulEvalTag;
  LPVOID               lpvAppDefined;
  PDAPI_FNExportEntry  pfnExportEntry;
}  EXPORT_CALLBACK, * PEXPORT_CALLBACK;

Members

dwFlags
Reserved (set to zero).
ulEvalTag
The type of data pointed to by lpvAppDefined:
TEXT_LINE
The data items are delimited by commas or other specified characters. The data line format is the same as if the data were written to an export file.
TEXT_VALUE_ARRAY
The items are in an array of structures where binary and nonbinary data is represented as strings. Binary values are exported as strings of hexadecimal digits.
VALUE_ARRAY
The items are in their native type, with a few minor exceptions. For example, any attributes whose native type is object (such as distinguished names or OR names) are represented as text. Also, date fields are represented as UTC strings of the date. Unsigned integer values are represented as integers.
lpvAppDefined
Application-defined field, passed as a parameter to the callback.
pfnExportEntry
Points to a function that processes each exported entry. For additional information, see the DAPI_FNExportEntry function prototype.

Remarks

Information in the EXPORT_CALLBACK structure is used to control the export of data with a callback function. Its members specify, for example, the name of the callback function itself and the format in which data is to be exported. A function specified in the EXPORT_CALLBACK structure is called each time an object is exported by the BatchExport, NTExport, and NWExport functions.

For additional information on this structure, see Importing and Exporting with Directory Access Functions.

See Also

BEXPORT_PARMS, DAPI_FNErrorCallback, DAPI_FNExportEntry, NTEXPORT_PARMS, NWEXPORT_PARMS


INTTRACEENTRY

The INTTRACEENTRY structure describes an action that a message transfer agent (MTA) took on a message.

Quick Info

Header file: EDKMDB.H

typedef struct
  {
  LONG      lAction;
  FILETIME  ftArrivalTime;
  FILETIME  ftDeferredTime;
  char      rgchADMDName[MAX_ADMD_NAME_SIZ+ADMN_PAD];
  char      rgchCountryName[MAX_COUNTRY_NAME_SIZ+COUNTRY_PAD];
  char      rgchPRMDId[MAX_PRMD_NAME_SIZ+PRMD_PAD];
  char      rgchAttADMDName[MAX_ADMD_NAME_SIZ+ADMN_PAD];
  char      rgchAttCountryName[MAX_COUNTRY_NAME_SIZ+COUNTRY_PAD];
  char      rgchAttPRMDId[MAX_PRMD_NAME_SIZ+PRMD_PAD];
  char      rgchMTAName[MAX_MTA_NAME_SIZ+MTA_PAD];
  char      rgchAttMTAName[MAX_MTA_NAME_SIZ+MTA_PAD];
  }  INTTRACEENTRY, *PINTTRACEENTRY;

Members

lAction
The routing action taken by the tracing MTA.
ftArrivalTime
The time when the message entered the tracing MTA.
ftDeferredTime
The time when the tracing MTA released the message.
rgchADMDName[MAX_ADMD_NAME_SIZ+ADMN_PAD]
The name of the administration management domain (ADMD) associated with the messaging domain containing the MTA.
rgchCountryName[MAX_COUNTRY_NAME_SIZ+COUNTRY_PAD]
The name of the country associated with the ADMD. These values are either three-digit X.121 codes, or two-character ISO 3166 codes.
rgchPRMDId[MAX_PRMD_NAME_SIZ+PRMD_PAD]
The name of the tracing domain, if it is a PRMD.
rgchAttADMDName[MAX_ADMD_NAME_SIZ+ADMN_PAD]
The name of the ADMD asociated with rgchAttMTAName.
rgchAttCountryName[MAX_COUNTRY_NAME_SIZ+COUNTRY_PAD]
The name of the country associated with rgchAttADMDName.
rgchAttPRMDId[MAX_PRMD_NAME_SIZ+PRMD_PAD]
The name of the PRMD associated with rgchAttADMDName.
rgchMTAName[MAX_MTA_NAME_SIZ+MTA_PAD]
The name of the tracing MTA, as defined by the messaging domain of which the tracing MTA is a part.
rgchAttMTAName[MAX_MTA_NAME_SIZ+MTA_PAD]
The name of the MTA to which the tracing MTA attempted and failed to send the message. This and the other rgchAtt* members are set only when the lAction flag is MD_AC_REROUTED.

Remarks

This structure is derived from the X.400 Internal Trace Entry class.

For an example of how to use this structure, see the HrConvertReport function call in the CONVREPT.CPP code sample under the IPM_OUT topic.

See Also

INTTRACEINFO


INTTRACEINFO

The INTTRACEINFO structure contains a list of actions, described by INTTRACEENTRY structures, that an MTA took on a message.

Quick Info

Header file: EDKMDB.H

typedef struct
  {
  ULONG          cEntries;
  INTTRACEENTRY  rgIntTraceEntry[MAPI_DIM];
  }  INTTRACEINFO, *PINTTRACEINFO;

Members

cEntries
The number of trace entries in rgIntTraceEntry
rgIntTraceEntry[MAPI_DIM]
An array of internal trace entries

Remarks

For an example of how to initialize this structure, see the the HrInternalTraceAppendEntryList function in the ITRACE.C code sample under the EDKMAPI topic.

See Also

INTTRACEENTRY


NAME_INFO

The NAME_INFO structure contains the common name, distinguished name, and display name of objects described within the SITE_INFO structure. These include the server, the site, and the organization.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  LPTSTR  pszName;
  LPTSTR  pszDNString;
  LPTSTR  pszDisplayName;
}  NAME_INFO, *PNAME_INFO;

Members

pszName
Simple object name.
pszDNString
Distinguished name of the object.
pszDisplayName
Display name of the object.

Remarks

The NAME_INFO structure is a member of the SITE_INFO structure.

See Also

SITE_INFO


NTEXPORT_PARMS

The NTEXPORT_PARMS structure contains information for exporting Windows NT Server directories.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  DWORD              dwDAPISignature;
  DWORD              dwFlags;
  HWND               hwndParent;
  LPTSTR             pszExportFile;
  CALLBACKPROGRESS   ProgressCallBacks;
  ERROR_CALLBACK     ErrorCallback;
  EXPORT_CALLBACK    ExportCallback;
  LPTSTR             pszDCName;
  LPTSTR             pszNTDomain;
}  NTEXPORT_PARMS, *PNTEXPORT_PARMS, *LPNTEXPORT_PARMS;

Members

dwDAPISignature
Verifies that the parameter sequence used by the calling application is the same as that expected by the directory function. The value should be set to DAPI_SIGNATURE, which is defined in the DAPI.H header file.
dwFlags
Defined values that control the directory export operation (see NTExport). Use the bitwise OR operator (|) to enable multiple operations:
DAPI_EVENT_MIN
Suppresses warning or error logging but logs start and stop messages.
DAPI_EVENT_SOME
Logs start, stop, and error messages.
DAPI_EVENT_ALL
Logs start, stop, error, and warning messages.
DAPI_SUPPRESS_PROGRESS
Suppresses the progress status update. (The default is to display progress.)
DAPI_SUPPRESS_COMPLETION
Suppresses display of all messages.
hwndParent
The window handle to use when displaying message boxes. Set this member to NULL to use the handle of the main window of the calling application.
pszExportFile
Full pathname of the text file where the account information is exported.

If this file exists, an error is returned. NTExport ignores this member if ProgressCallBacks is not NULL.

ProgressCallBacks
A structure that contains pointers to functions that display the progress of the batch export operation.

If this member is NULL, NTExport assumes that the calling application does not supply its own progress updates and displays a default modeless dialog to display the operation’s progress.

ErrorCallback
A structure that points to a function to be called when an error is encountered during the batch export operation.

If this member is NULL, NTExport calls the default error handler, which displays an error dialog window and posts the error into the Windows NT Application event log.

ExportCallback
A structure that points to a function to be called when an account is exported.

If this member is NULL, NTExport writes the exported objects to the file specified by pszExportFile.

pszDCName
The name of the domain controller where the user information is obtained. Set this member to NULL to have NTExport poll the network for a domain controller and use the first domain controller that responds.

If this member is NULL, NTExport queries the domain for the name of an available domain controller.

pszNTDomain
The name of the Windows NT Server domain where the user information is obtained. Set this member to NULL to have NTExport use the primary Microsoft Windows NT Server domain name, which is the domain where the executing process computer’s account is logged on.

If this member is NULL, NTExport uses the primary Windows NT Server domain name (the domain on which the executing process’s computer account is logged on).

If pszDCName is specified, it overrides any value specified for pszNTDomain.

The following table describes the actions NTExport performs, depending on the values of pszNTDomain and pszDCName.
pszDCName | pszNTDomain | Action
NULL or "" | NULL or "" | Exports users from the current logon domain.
computer | ignored | Exports users from computer, which is either a domain controller (DC) or a server. If computer is a simple server, only the local users are extracted. If computer is either a primary DC (PDC) or a backup DC (BDC), the domain users are extracted.
\\computer | ignored | Exports users from computer, which is either a DC or a server. If computer is a simple server, only the local users are extracted. If computer is either a PDC or a BDC, the domain users are extracted.
NULL or "" | domain | Exports users whose PDC computer is identified by NetGetDCName. If that fails, get the PDC by calling NetGetAnyDCName.
NULL or "" | \\computer | Exports users from computer. The UNC name is assumed to specify a computer name.

Remarks

The NTEXPORT_PARMS structure is a parameter to the NTExport function.

For additional information on this structure, see Using Directory Access Functions.

See Also

NTExport


NWEXPORT_PARMS

The NWEXPORT_PARMS structure contains information for exporting Novell NetWare directories.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  DWORD             dwDAPISignature;
  DWORD             dwFlags;
  HWND              hwndParent;
  LPTSTR            pszExportFile;
  CALLBACKPROGRESS  ProgressCallBacks;
  ERROR_CALLBACK    ErrorCallback;
  EXPORT_CALLBACK   ExportCallback;
  LPTSTR            pszFileServer;
  LPTSTR            pszUserName;
  LPTSTR            pszPassword;
}  NWEXPORT_PARMS, *PNWEXPORT_PARMS, *LPNWEXPORT_PARMS;

Members

dwDAPISignature
Verifies that the parameter sequence used by the calling application is the same as that expected by the directory function. The value should be set to DAPI_SIGNATURE, which is defined in the DAPI.H header file.
dwFlags
Defined values that control the directory export operation (see NWExport). Use the bitwise OR operator (|) to enable multiple operations:
DAPI_YES_TO_ALL
Forces a Yes response on any user interface element that prompts the user for input.
DAPI_EVENT_MIN
Suppresses warning or error logging but logs start and stop messages.
DAPI_EVENT_SOME
Logs start, stop, and error messages.
DAPI_EVENT_ALL
Logs start, stop, error, and warning messages.
DAPI_SUPPRESS_PROGRESS
Suppresses the progress status update. (The default is to display progress.)
DAPI_SUPPRESS_COMPLETION
Suppresses display of all messages.
hwndParent
The window handle to use when displaying message boxes. Set this member to NULL to use the handle of the main window of the calling application.
pszExportFile
Full pathname of the text file where the account information is exported.

If this file exists, an error is returned. NWExport ignores this member if ProgressCallBacks is not NULL.

ProgressCallBacks
A structure that contains pointers to functions that display the progress of the batch export operation.

If this member is NULL, NWExport assumes that the calling application does not supply its own progress updates and displays a default modeless dialog to display the operation’s progress.

ErrorCallback
Function address of a function to be called on each error encountered. If not supplied and NULL is passed, the default error handler is called. The error will then be written into the Windows NT Application Event Log.

If this member is NULL, NWExport calls the default error handler, which displays an error dialog window and posts the error into the Windows NT Application event log.

ExportCallback
A structure that points to a function to be called when an error is encountered during the batch export operation.

If this member is NULL, NWExport writes the exported objects to the file specified by pszExportFile.

pszFileServer
The name of the Novell NetWare file server where the user information is obtained.

If this member is NULL, NWExport uses the default file server for the NetWare network.

pszUserName
The user name to supply to the Novell NetWare logon process when connecting to the NetWare server.
pszPassword
The password to supply to the Novell NetWare logon process when connecting to the NetWare server.

Remarks

The NWEXPORT_PARMS structure is a parameter to the NWExport function.

For additional information on this structure, see Using Directory Access Functions.

See Also

NWExport


PROXYINFO

The PROXYINFO structure contains proxy address information for a recipient.

Quick Info

Header file: RPCPUB.H

typedef struct _PROXYINFO
{
  RPC_BOOL               fContinueOnError;
  RPC_BOOL               fIgnoreOldSecondaries;
  RPC_SZ                 wszDN;
  RPC_SZ                 wszNickName;
  RPC_SZ                 wszCommonName;
  RPC_SZ                 wszDisplayName;
  RPC_SZ                 wszSurName;
  RPC_SZ                 wszGivenName;
  RPC_SZ                 wszInitials;
  RPC_SZ                 wszTargetAddress;
  PROXYNODE __RPC_FAR *  pPNVerifyProxy;
  PROXYNODE __RPC_FAR *  pPNExcludeProxy;
}  PROXYINFO;

typedef struct _PROXYINFO __RPC_FAR * PPROXYINFO;

Members

fContinueOnError
Whether to continue trying to generate a proxy address if not successful.
fIgnoreOldSecondaries
Whether to ignore secondary address. Do not generate a proxy address.
wszDN
The distinguished name of the recipient.
wszNickName
The nickname of the recipient.
wszCommonName
The common name of the recipient.
wszDisplayName
The name that is displayed for the recipient.
wszSurName
The last name of the recipient.
wszGivenName
The first name of the recipient.
wszInitials
The initials of the recipient.
wszTargetAddress
The address of the recipient when the recipient is a foreign recipient.
pPNVerifyProxy
The list of known proxy addresses of the recipient.
pPNExcludeProxy
The list of recipient proxy addresses to ignore.

See Also

SAD_EcGetProxies, SAD_EcGetProxiesBI


PROXYLIST

The PROXYLIST structure contains two linked lists of PROXYNODE structures. One is a list of valid proxy addresses; the other is a list of failed proxy address types.

Quick Info

Header file: RPCPUB.H

typedef struct _PROXYLIST
{
 PROXYNODE __RPC_FAR * __RPC_FAR *  ppPNProxy;
 PROXYNODE __RPC_FAR * __RPC_FAR *  ppPNFailedProxyType;
} PROXYLIST;

typedef struct _PROXYLIST __RPC_FAR *PPROXYLIST;

Members

ppPNProxy
Points to the head of a linked list of PROXYNODE structures containing valid proxy addresses.
ppPNFailedProxyType
Points to the head of a linked list of PROXYNODE structures containing proxy address types that are not valid or had an error.

See Also

PROXYNODE, SAD_EcGetProxies, SAD_EcGetProxiesBI


PROXYNODE

The PROXYNODE structure contains either a valid proxy address or an invalid proxy address type.

Quick Info

Header file: RPCPUB.H

typedef struct _PROXYNODE
{
  struct _PROXYNODE __RPC_FAR *  pnodeNext;
  RPC_SZ                         wszProxy;
  RPC_EC                         ec;
  RPC_SZ                         wszDN;
}  PROXYNODE;

typedef struct _PROXYNODE __RPC_FAR *  PPROXYNODE;

Members

pnodeNext
Points to a PROXYNODE structure containing either the next valid proxy address or the next proxy address type that is not valid.
wszProxy
When ec equals ecOK, a valid proxy address.
ec
An error code specifying the status of the information in this structure:
ecOK
No error. The proxy address in wszProxy is valid.
ecGeneralFailure
A failure occurred and proxy address generation has been halted.
ecSomeProxiesFailed
Some proxy addresses failed to be generated.
ecTargetNotValid
The supplied target address is not valid.
ecTargetNotUnique
The supplied target address is not unique.
ecProxyDLLNotImplemented
The proxy address type is not implemented yet.
ecProxyDLLOOM
The proxy generation DLL encountered a memory allocation error.
ecProxyDLLError
The proxy generation DLL encountered a general error.
ecProxyDLLProtocol
The proxy generation DLL encountered a protocol error.
ecProxyDLLSyntax
The proxy generation DLL encountered a syntax error.
ecProxyDLLEOF
The proxy generation DLL encountered an end of file.
ecProxyDLLSoftware
The proxy generation DLL encountered an error in software.
ecProxyDLLConfig
The proxy generation DLL encountered a configuration error.
ecProxyDLLContention
The proxy generation DLL encountered a contention error.
ecProxyDLLNotFound
The proxy generation DLL could not be found.
ecProxyDLLDiskSpace
The proxy generation DLL ran out of disk space.
ecProxyDLLException
The proxy generation DLL threw an exception.
ecProxyDLLDefault
The proxy generation DLL returned an unknown error.
ecProxyNotValid
The supplied proxy address is not valid.
ecProxyNotUnique
The supplied proxy address is either not unique or the DLL is unable to generate a unique proxy address. The value in wszDN is the distinguished name of the existing proxy address.
ecProxyDuplicate
A primary proxy address of the same type was also supplied.
wszDN
When ec is ecProxyNotUnique, the distinguished name of the object already owning the proxy address you requested to be validated. Otherwise, it is NULL.

See Also

PROXYINFO, PROXYLIST, SAD_EcGetProxies, SAD_EcGetProxiesBI, SAD_FreeProxyListNode


READSTATE

The READSTATE structure contains the read state of a message.

Quick Info

Header file: EDKMDB.H

typedef struct
{
  ULONG  cbSourceKey;
  BYTE *  pbSourceKey;
  ULONG  ulFlags;
}  READSTATE, * LPREADSTATE;

Members

cbSourceKey
The size (in bytes) of the key in the pbSourceKey member.
pbSourceKey
Points to a key of the PR_SOURCE_KEY property type.
ulFlags
Defined value that indicates whether the message has been read:
SYNC_READ
The message has been read.

Remarks

This structure is used in conjunction with the IExchangeImportContentsChanges::ImportPerUserReadStateChange method to identify the messages that either went from unread to read, or went from read to unread. If the value of the ulFlags member is equal to SYNC_READ, the message went from unread to read; if the value of the ulFlags member is not equal to SYNC_READ, the message went from read to unread.

See Also

IExchangeImportContentsChanges::ImportPerUserReadStateChange


RECIPIENTINFO

The RECIPIENTINFO structure contains the information associated with each user. This structure is filled by the calling code and passed to the proxy generation DLL for read-only use. Note that all of the strings in this structure are Unicode strings.

Quick Info

Header file: PROXYINF.H

typedef struct
{
  LPWSTR  pszCommonName;
  LPWSTR  pszFirstName;
  LPWSTR  pszLastName;
  LPWSTR  pszDisplayName;
  LPWSTR  pszInitials;
}  RECIPIENTINFO, * PRECIPIENTINFO;

Members

pszCommonName
The mailbox name of the recipient.
pszFirstName
The first name of the recipient.
pszLastName
The last name of the recipient.
pszDisplayName
The name of the recipient, as displayed.
pszInitials
The initials of the recipient.

Remarks

Use the RECIPIENTINFO structure with a site proxy address to generate a site-unique recipient proxy.

For additional information on this structure, see Creating a Proxy Address.

See Also

RcUpdateProxy


ROWENTRY

The ROWENTRY structure contains a row and the operation that is performed on that row in a table through the IExchangeModifyTable interface.

Quick Info

Header file: EDKMDB.H

typedef struct
{
  ULONG         ulRowFlags;
  ULONG         cValues;
  LPSPropValue  rgPropVals;
}  ROWENTRY, FAR * LPROWENTRY;

Members

ulRowFlags
The operation 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.

Remarks

For an example of how to use this structure, see the SROWLST.CPP code sample under the ACLCLS topic. For information on SPropValue structures, see the MAPI Programmer’s Reference.

See Also

IExchangeModifyTable, ROWLIST


ROWLIST

The ROWLIST structure contains an array of ROWENTRY structures representing rows and the operations that are performed on those rows in a table through the IExchangeModifyTable interface.

Quick Info

Header file: EDKMDB.H

typedef struct
{
  ULONG     cEntries;
  ROWENTRY  aEntries[MAPI_DIM];
}  ROWLIST, FAR * LPROWLIST;

Members

cEntries
The number of entries in the aEntries array.
aEntries[MAPI_DIM]
An array of ROWENTRY structures containing the rows and the operations that are performed on those rows in the table.

Remarks

For an example of how to use this structure, see the SROWLST.CPP code sample under the ACLCLS topic.

See Also

IExchangeModifyTable::ModifyTable, ROWENTRY


RPC_GATEWAY_TRACK_INFORMATION

The RPC_GATEWAY_TRACK_INFORMATION structure contains tracking information that a gateway produces as objects move through the mail system.

Quick Info

Header file: RPCPUB.H

typedef struct
{
  RPC_INT         nEventType;
  RPC_SYSTEMTIME  stEvent;
  RPC_SZ          szGatewayName;
  RPC_SZ          szPartner;
  RPC_SZ          szMTSID;
  RPC_SZ          szRemoteID;
  RPC_SZ          szOriginator;
  RPC_INT         nPriority;
  RPC_INT         nLength;
  RPC_INT         nSeconds;
  RPC_INT         nCost;
  RPC_SZ          szSubjectID;
  }  RPC_GATEWAY_TRACK_INFORMATION;

Members

nEventType
The type of event to track. Note: Other events are defined in the header file, but not tracked in this release.
tevtMessageBackboneTransferIn
Track messages that came in through a backbone.
tevtMessageBackboneTransferOut
Track messages that went out through a backbone.
tevtMessageGatewayTransferIn
Track messages that go to the outside world.
tevtMessageGatewayTransferOut
Track messages that come in from the outside world.
tevtReportGatewayGenerated
Track messages that generated a report.
tevtReportTransferIn
Track messages that come in from the outside world.
tevtReportTransferOut
Track messages that go to the outside world.
stEvent
The system time when the event occurred.
szGatewayName
The distinguished name of the gateway where the event occurred.
szPartner
The distinguished name of the server to or from which the message was transferred.
szMTSID
The Microsoft Exchange Server MTSID (message transfer system identifier) of the message or report.
szRemoteID
The gateway side identifier of the message or report.
szOriginator
The distinguished name (or possibly proxy address) of the message originator.
nPriority
The message priority:
PRIO_URGENT
PRIO_NORMAL
PRIO_NONURGENT
nLength
The size, in bytes, of the message.
nSeconds
The transfer duration, in seconds. This is typically used by a FAX gateway.
nCost
Informational member.
szSubjectID
The Microsoft Exchange Server identifier of the message for report-related events.

Remarks

For an example of how to use this structure, see the HrTrackWriteLogW function call in the EDKTRACK.C code sample.

See Also

SAD_ScSaveGatewayTrackingData


RPCBINDINFO

The RPCBINDINFO structure contains the binding information. Do not modify this binding information.


RTFSYNCINFO

The RTFSYNCINFO structure contains representations of the MAPI PR_RTF_SYNC_* properties.

Quick Info

Header file: RTFLIB.H

typedef struct _RTFSYNCINFO
  {
  LONG  lBodyCRC;
  LONG  lBodyCount;
  LONG  lPrefixCount;
  LONG  lTrailingCount;
  char  szBodyTag[cchBodyTagMax + 2];
  }  RTFSYNCINFO;

Members

lBodyCRC
See the MAPI property PR_RTF_SYNC_BODY_CRC.
lBodyCount
See the MAPI property PR_RTF_SYNC_BODY_COUNT.
lPrefixCount
See the MAPI property PR_RTF_SYNC_PREFIX_COUNT.
lTrailingCount
See the MAPI property PR_RTF_SYNC_TRAILING_COUNT.
szBodyTag[cchBodyTagMax + 2]
See the MAPI property PR_RTF_SYNC_BODY_TAG.

Remarks

For an example of how to use this structure, see the HrRTFCompressedToText function call in the EDKRTF.C code sample under the EDKUTILS topic. For information on PR_RTF_SYNC_* properties, see the MAPI Programmer’s Reference.

See Also

HrTextFromCompressedRTFStreamEx


SInitPropValue

The SInitPropValue structure contains a property tag and its value. Use this structure to initialize a property value array.

Quick Info

Header file: EXADMIN.H

typedef struct
{
  ULONG     ulPropTag;
  ULONG     dwAlignPad;
  LONGLONG  ll;
}  SInitPropValue, * LPSInitPropValue;

Members

ulPropTag
Property tag for the property. This tag consists of a code for the property type in the lower 16 bits and a code for the property identifier in the upper 16 bits.
dwAlignPad
Padding bytes to properly align the information indicated by ll.
ll
Property value expressed as a LONGLONG.

Remarks

Except for the ll member, this structure is identical to the SPropValue structure.

For an example of how to use this structure, see the HrProcessNew function call in the COMMANDS.C code sample under the SMBAGENT topic. For information on SPropValue, see the MAPI Programmer’s Reference.


SITE_INFO

The SITE_INFO structure contains information about a site.

Quick Info

Header file: | DAPI.H
Unicode: | Yes

typedef struct
{
  LPTSTR     pszCountry;
  NAME_INFO  objServer;
  NAME_INFO  objSite;
  NAME_INFO  objEnterprise;
}  SITE_INFO, *PSITE_INFO;

Members

pszCountry
Country code. Parsed from X400 value of Site-Proxy-Space attribute on Site-Addressing object.
objServer
Name information for server.
objSite
Name information for site containing server.
objEnterprise
Name information for organization containing server.

Remarks

The SITE_INFO structure is used as an argument to the DAPIGetSiteInfo function.

For additional information on this structure, see Using Directory Access Functions.

See Also

DAPIGetSiteInfo, NAME_INFO


TRACEENTRY

The TRACEENTRY structure describes an action that a messaging domain took on a message. This structure is derived from the X.400 External Trace Entry class.

Quick Info

Header file: EDKMDB.H

typedef struct
{
  LONG      lAction;
  FILETIME  ftArrivalTime;
  FILETIME  ftDeferredTime;
  CHAR      rgchADMDName[MAX_ADMD_NAME_SIZ + ADMN_PAD];
  CHAR      rgchCountryName[MAX_COUNTRY_NAME_SIZ + COUNTRY_PAD];
  CHAR      rgchPRMDId[MAX_PRMD_NAME_SIZ + PRMD_PAD];
  CHAR      rgchAttADMDName[MAX_ADMD_NAME_SIZ + ADMN_PAD];
  CHAR      rgchAttCountryName[MAX_COUNTRY_NAME_SIZ + COUNTRY_PAD];
  CHAR      rgchAttPRMDId[MAX_PRMD_NAME_SIZ + PRMN_PAD];
}  TRACEENTRY, FAR * LPTRACEENTRY;

Members

lAction
The routing action taken by the tracing domain.
ftArrivalTime
The time when the message entered the tracing domain.
ftDeferredTime
The time when the tracing domain released the message.
rgchADMDName[MAX_ADMD_NAME_SIZ + ADMN_PAD]
The name of the tracing domain if it is an administration management domain (ADMD), or the ADMD to which the tracing domain is attached if it is a private management domain (PRMD).
rgchCountryName[MAX_COUNTRY_NAME_SIZ + COUNTRY_PAD]
The name of the country associated with the ADMD. These values are either three-digit X.121 codes, or two-character ISO 3166 codes.
rgchPRMDId[MAX_PRMD_NAME_SIZ + PRMD_PAD]
The name of the tracing domain if it is a PRMD.
rgchAttADMDName[MAX_ADMD_NAME_SIZ + ADMN_PAD]
The name of the domain to which the tracing domain attempted but failed to send the message. This and the other rgchAtt* attributes are set only when the lAction flag is MD_AC_REROUTED.
rgchAttCountryName[MAX_COUNTRY_NAME_SIZ + COUNTRY_PAD]
The name of the country associated with rgchAttADMDName.
rgchAttPRMDId[MAX_PRMD_NAME_SIZ + PRMN_PAD]
The name of the private management domain associated with rgchAttADMDName.

Remarks

For additional information on this structure, see Gateway Trace Information in the Gateway Programmer's Reference Guide. For an example of how to use this structure, see the HrTraceOpenEntry function call in the ITRACE.C code sample under the EDKMAPI topic.

See Also

HrTraceGoToEntry, HrTraceGoToFirstEntry, HrTraceGotoNextEntry, HrTraceOpenEntry, TRACEINFO


TRACEINFO

The TRACEINFO structure contains an array of TRACEENTRY structures, including a count of their number.

Quick Info

Header file: EDKMDB.H

typedef struct
{
  ULONG       cEntries;
  TRACEENTRY  rgtraceentry[];
}  TRACEINFO, FAR * LPTRACEINFO;

Members

cEntries
The number of TRACEENTRY structures in rgtraceentry[].
rgtraceentry[]
An array of TRACEENTRY structures, each containing all of the information for one trace.

Remarks

For additional information on this structure, see Gateway Trace Information in the Gateway Programmer's Reference Guide. For an example of how to use this structure, see the HrTraceOpenEntry function call in the ITRACE.C code sample under the EDKMAPI topic.

See Also

HrTraceGoToEntry, HrTraceGoToFirstEntry, HrTraceGotoNextEntry, TRACEENTRY


Objects

You gain access to Microsoft Exchange Server through MAPI objects. Therefore, it’s important to understand how MAPI interfaces and properties are implemented by Microsoft Exchange Server MAPI providers.

In addition to supporting standard MAPI interfaces, Microsoft Exchange Server provides several interfaces of its own. These interfaces are generally accessed when a property (which can itself be opened as an object) is defined on an object and returns its own interface.

The two main categories of Microsoft Exchange Server objects are:

  • Directory objects
  • Information store objects

Note that the information provided in this section is not intended to take the place of the MAPI documentation. Rather, it explains how MAPI objects, interfaces, and properties are implemented by components of Microsoft Exchange Server. For complete information on MAPI objects, interfaces, and properties, see the MAPI Programmer’s Reference. For a discussion of Microsoft Exchange Server information stores, see About the Information Store and Information Store Operations.


Directory Objects

The Microsoft Exchange Server directory is exposed through a MAPI address book provider. Therefore, directory objects can be accessed through MAPI interfaces. This section provides reference information on accessing the most commonly used directory objects through MAPI. For an overview of this process, see Using MAPI with Directory Objects.

You can also use Microsoft Exchange Server directory access functions to manipulate directory objects. For reference information, see About the Directory Schema. For general information, see Using Directory Access Functions.

For general information on the Microsoft Exchange Server directory, see About the Directory. For information on using directory interfaces to manipulate directory objects and attributes, see Working with the Directory.


Add-In Object

The Add-In object represents a server application within the Microsoft Exchange Server directory. A server application uses its Add-In object as a place to store configuration information in the directory.

This object can also specify an Administrator extension DLL so that the server application can be configured and administrated using the Microsoft Exchange Server Administrator program. For more information on the Administrator program, see About Server Applications.

The Add-In object is very similar to a Mailbox-Agent object. The important difference is that no mailbox is associated with an Add-In object, which is intended to represent a server application that does not send or receive mail.

Add-In objects are stored in the Add-Ins container of the Microsoft Exchange Server directory. To associate an Administrator extension DLL with an Add-In object, the Add-In object's Extension-Name attribute must contain the name of an Admin-Extension object in the Add-Ins container of the directory. For more information on Administrator extension DLLs and the Add-Ins container, see Installing the Administrator Extension DLL.

Because Add-In objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access an Add-In object.

For more information on accessing Add-In objects through MAPI and through directory access functions, see Adding an Object to the Directory.


Add-In Object Properties

For class information about this object, see Add-In.

Property
PR_EMS_AB_ACTIVATION_SCHEDULE
PR_EMS_AB_ACTIVATION_STYLE
PR_EMS_AB_COMPUTER_NAME
PR_EMS_AB_OWNER
PR_MHS_COMMON_NAME
(MAPI property)


Addr-Type Object

The Addr-Type object specifies a type of foreign system for which the Microsoft Exchange Server can create a proxy address. You must have an address type for each type of foreign system where the server sends messages. There is a one-to-one relationship between address types and address templates.

For example, SMTP (Internet) business addresses take the form of user@domain.com, where user is the account name of the user and domain is the name of the host computer domain.

Because Addr-Type objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access an Addr-Type object.

To determine whether an address type already exists, call the HrAddressTypeExists function. To install an address type, call the HrInstallAddressType function. To remove an address type, call the HrRemoveAddressType function.


Addr-Type Object Properties

For class information about this object, see Addr-Type.

Property
PR_EMS_AB_FILE_VERSION
PR_EMS_AB_PROXY_GENERATOR_DLL
PR_MHS_COMMON_NAME
(MAPI property)


Address-Template Object

The Address-Template object provides the framework for a specific proxy address. You must have an address template for each type of foreign system where the server sends messages. There is a one-to-one relationship between address templates and address types.

For example, SMTP (Internet) business addresses take the form of user@domain.com, where user is the account name of the user and domain is the name of the host computer domain.

Because Address-Template objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access an Address-Template object.

To determine whether an address template already exists, call the HrAddressTemplateExists function. To install an address template, call the HrInstallAddressTemplate function. To remove an address template, call the HrRemoveAddressTemplate function.


Address-Template Object Properties

For class information about this object, see Address-Template.

Property
pr_ems_ab_address_syntax
pr_ems_ab_address_type
pr_ems_ab_per_msg_dialog_display_table
pr_ems_ab_per_recip_dialog_display_table


Admin-Extension Object

The Admin-Extension object represents an Administrator extension DLL within the directory. Administrator extension DLLs are used to create custom property pages for display by the Microsoft Exchange Server Administrator program. For more information on the Administrator program, see About Server Applications.

This object contains the executable code for translating a message between the format used by Microsoft Exchange Server and that used by a foreign system. Each address type that a server supports has a separate Admin-Extension object.

This object is stored in the Add-Ins container of the Microsoft Exchange Server directory. Because Administrator extension DLLs might be needed for several different hardware platforms, each platform can be represented by its own Admin-Extension object. An Administrator extension DLL can also be represented by an Add-In object. For more information on the Administrator extension DLL and the Add-Ins container, see Installing the Administrator Extension DLL.

Because Admin-Extension objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access an Admin-Extension object.

For more information on accessing Admin-Extension objects through MAPI and through the directory access functions, see Initializing Connections with ADMIN_Initialize.


Admin-Extension Object Properties

For class information about this object, see Admin-Extension.

Property
PR_EMS_AB_ADMIN_EXTENSION_DLL
PR_EMS_AB_FILE_VERSION
PR_MHS_COMMON_NAME
(MAPI property)


Distribution-List Object

The Distribution-List object represents a group of Mail-Recipient objects. Any object that inherits from a Mail-Recipient object can be contained within a Distribution-List object. These include Public-Folder, Mailbox, and Remote-Address objects. A Distribution-List object can also contain other Distribution-List objects.

Because Distribution-List objects appear to MAPI as messaging user objects, use the MAPI IDistList interface to access a Distribution-List object.


Distribution-List Object Properties

For class information about this object, see Distribution-List.

Property
pr_ems_ab_dl_member_rule
pr_ems_ab_hide_dl_membership
pr_ems_ab_member
pr_ems_ab_oof_reply_to_originator
pr_ems_ab_owner
pr_ems_ab_report_to_originator
pr_ems_ab_report_to_owner


Mail-Gateway Object

When messages are sent to recipients whose addresses fall into a designated address space handled by a gateway, the message transfer agent (MTA) routes the mail to the MTS-Out folder of a gateway handling that address space based upon information in the Gateway Address Routing Table (GWART). If a recipient’s address is not handled by any gateway, the message is undelivered. To a MAPI application, a Mail-Gateway object appears as a regular mailbox, where MTS-OUT is used instead of Inbox and MTS-IN is used instead of Outbox.

A Mail-Gateway object in the directory is not accessible via the MAPI address book. To open a MAPI object that points to a Mail-Gateway object in the directory, use HrCreateDirEntryId or HrCreateDirEntryIdEx.

See HrInstallGateway and related functions for more information about how to install a Mail-Gateway object.

For more information on accessing Mail-Gateway objects through MAPI and through directory access functions, see Using MAPI with Directory Objects.


Mail-Gateway Object Properties

For class information about this object, see Mail-Gateway.

Property
pr_ems_ab_activation_schedule
pr_ems_ab_activation_style
pr_ems_ab_admd
PR_EMS_AB_AUTH_ORIG_BL
PR_EMS_AB_CAN_PRESERVE_DNS
pr_ems_ab_computer_name
pr_ems_ab_connected_domains
pr_ems_ab_country_name
pr_ems_ab_deliv_cont_length
pr_ems_ab_deliv_eits
pr_ems_ab_deliv_ext_cont_types
pr_ems_ab_delivery_mechanism
pr_ems_ab_diagnostic_reg_key
pr_ems_ab_dl_mem_reject_perms_bl
pr_ems_ab_dl_mem_submit_perms_bl
pr_ems_ab_encapsulation_method
pr_ems_ab_export_containers
pr_ems_ab_export_custom_recipients
pr_ems_ab_home_mdb
PR_EMS_AB_HOME_MTA
PR_EMS_AB_IMPORT_CONTAINER
PR_EMS_AB_IMPORT_SENSITIVITY
pr_ems_ab_line_wrap
pr_ems_ab_mdb_backoff_interval
pr_ems_ab_mdb_msg_time_out_period
pr_ems_ab_mdb_storage_quota
pr_ems_ab_mdb_unread_limit
pr_ems_ab_prmd
pr_ems_ab_replication_sensitivity
pr_ems_ab_routing_list
pr_ems_ab_supported_application_context
pr_ems_ab_transfer_retry_interval
pr_ems_ab_transfer_timeout_non_urgent
pr_ems_ab_transfer_timeout_normal
pr_ems_ab_transfer_timeout_urgent
pr_ems_ab_translation_table_used
pr_ems_ab_unauth_orig_bl
PR_MHS_COMMON_NAME
(MAPI property)


Mail-Recipient Object

The Mail-Recipient object is an abstract object, which means you cannot create an instance of this object directly. It is inherited by other objects to which you can send mail, including the Distribution-List, Mailbox, Public-Folder, and Remote-Address objects.

Multiple Mail-Recipient objects can be represented by (or contained within) a single Distribution-List object.

Because Mail-Recipient objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access a Mail-Recipient object.

For more information on accessing Mail-Recipient objects through MAPI and through directory access functions, see Using MAPI with Directory Objects and Implementing Address Lookup Functions.


Mail-Recipient Object Properties

For class information about this object, see Mail-Recipient.

Property
pr_comment
(mapi property)
pr_display_name
(mapi property)
pr_ems_ab_alt_recipient
pr_ems_ab_auth_orig_bl
pr_ems_ab_autoreply
pr_ems_ab_autoreply_message
pr_ems_ab_autoreply_subject
pr_ems_ab_deliv_cont_length
pr_ems_ab_deliv_eits
pr_ems_ab_deliv_ext_cont_types
pr_ems_ab_deliver_and_redirect
pr_ems_ab_display_name_printable
pr_ems_ab_dl_mem_reject_perms_bl
pr_ems_ab_dl_mem_submit_perms_bl
pr_ems_ab_expiration_time
pr_ems_ab_extension_attribute_x
pr_ems_ab_hide_from_address_book
pr_ems_ab_home_mdb
pr_ems_ab_home_mta
pr_ems_ab_imported_from
pr_ems_ab_maintain_autoreply_history
pr_ems_ab_proxy_addresses
pr_ems_ab_replication_sensitivity
pr_ems_ab_security_protocol
pr_ems_ab_submission_cont_length
pr_ems_ab_telephone_number
pr_ems_ab_unauth_orig_bl
PR_MHS_COMMON_NAME
(MAPI property)
pr_nickname
(mapi property)
pr_send_rich_info
(mapi property)
pr_user_certficate
(mapi property)


Mailbox Object

The Mailbox object represents a Microsoft Exchange client that uses the Microsoft Exchange Server information store as its mail repository. A mailbox object inherits from a Mail-Recipient object, which means that it can also be contained within a Distribution-List object.

For example, a recipient who uses the POP3 protocol (Post Office protocol 3) to connect to Microsoft Exchange Server and retrieve mail must have a mailbox. Similarly, a recipient who uses a Microsoft Exchange client to connect to Microsoft Exchange Server and retrieve mail must also have a mailbox. However, LDAP and NNTP clients communicate directly with the Microsoft Exchange Server directory and are not necessarily represented by mailboxes.

Because Mailbox objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access a Mailbox object.

For more information on accessing Mailbox objects through MAPI and through directory access functions, see Using MAPI with Directory Objects and Storing and Accessing Configuration Information.


Mailbox Object Properties

For class information about this object, see Mailbox.

Property
PR_ASSISTANT
(MAPI property)
pr_assistant_telephone_number
(mapi property)
pr_business_telephone_number
(mapi property)
pr_business2_telephone_number
(mapi property)
PR_COMPANY_NAME
(MAPI property)
PR_COUNTRY
(MAPI property)
pr_department_name
(mapi property)
pr_ems_ab_assoc_nt_account
pr_ems_ab_business_roles
pr_ems_ab_delivery_mechanism
pr_ems_ab_international_isdn_number
pr_ems_ab_manager
pr_ems_ab_mdb_over_quota_limit
pr_ems_ab_mdb_storage_quota
pr_ems_ab_mdb_use_defaults
pr_ems_ab_public_delegates
pr_ems_ab_street_address
pr_ems_ab_teletex_terminal_identifier
pr_ems_ab_x121_address
pr_given_name
(mapi property)
pr_home_telephone_number
(mapi property)
pr_home2_telephone_number
(mapi property)
pr_initials
(mapi property)
pr_locality
(mapi property)
pr_mobile_telephone_number
(mapi property)
pr_office_location
(mapi property)
pr_pager_telephone_number
(mapi property)
pr_postal_code
(mapi property)
pr_primary_fax_number
(mapi property)
pr_state_or_province_name
(mapi property)
pr_surname
(mapi property)
pr_telex_number
(mapi property)
pr_title
(mapi property)


Mailbox-Agent Object

The Mailbox-Agent object represents an automated process that can receive mail. Use this object to implement a directory synchronization agent (DIRSYNC) between two servers.

A DIRSYNC agent sends address information from one organization site to another. This object represents a mailbox from which to retrieve, manipulate, and route this address information. For more information, see Creating a Directory Synchronization Agent.

Because Mailbox-Agent objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access a Mailbox-Agent object.

For more information on accessing Mailbox-Agent objects through MAPI and though directory access functions, see Using MAPI with Directory Objects and Initializing Connections with ADMIN_Initialize.


Mailbox-Agent Object Properties

For class information about this object, see Mailbox-Agent.

Property
pr_ems_ab_activation_schedule
pr_ems_ab_activation_style
pr_ems_ab_computer_name
pr_ems_ab_owner


Public-Folder Object

The Public-Folder object represents a public folder and resides within a public information store. For more information, see About Public Folders.

This object inherits from a Mail-Recipient object, which means that it can also be contained within a Distribution-List object.

Because Public-Folder objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access a Public-Folder object.

For more information on accessing Public-Folder objects through MAPI and through directory access functions, see Using MAPI with Directory Objects, Working with Public Folders.


Public-Folder Object Properties

For class information about this object, see Public-Folder.

Property
pr_ems_ab_delivery_mechanism
pr_ems_ab_display_name_override
pr_ems_ab_folder_pathname
pr_ems_ab_mdb_over_quota_limit
pr_ems_ab_mdb_storage_quota
pr_ems_ab_mdb_use_defaults
pr_ems_ab_pf_contacts


Remote-Address Object

The Remote-Address object represents any user outside of the Microsoft Exchange organization. For example, if you communicate with Internet or X.400 users, they are represented by this object.

This object inherits from a Mail-Recipient object, which means that it can also be contained within a Distribution-List object.

Because Remote-Address objects appear to MAPI as messaging user objects, use the MAPI IMailUser interface to access a Remote-Address object.

For more information on accessing Remote-Address objects through MAPI and through directory access functions, see Using MAPI with Directory Objects.


Remote-Address Object Properties

For class information about this object, see Remote-Address.

Property
PR_ASSISTANT
(MAPI property)
PR_ASSISTANT_TELEPHONE_NUMBER
(MAPI property)
PR_BUSINESS_TELEPHONE_NUMBER
(MAPI properties)
PR_BUSINESS2_TELEPHONE_NUMBER
(MAPI properties)
PR_COMPANY_NAME
(MAPI property)
PR_COUNTRY
(MAPI property)
PR_DEPARTMENT_NAME
(MAPI property)
PR_EMS_AB_INTERNATIONAL_ISDN_NUMBER
PR_EMS_AB_MANAGER
PR_EMS_AB_TARGET_ADDRESS
PR_EMS_AB_TELETEX_TERMINAL_IDENTIFIER
PR_EMS_AB_X121_ADDRESS
PR_GIVEN_NAME
(MAPI property)
PR_HOME_TELEPHONE_NUMBER

(MAPI property)
PR_HOME2_TELEPHONE_NUMBER

(MAPI property)
PR_INITIALS
(MAPI property)
PR_LOCALITY
(MAPI property)
PR_MOBILE_TELEPHONE_NUMBER
(MAPI property)
PR_OFFICE_LOCATION
(MAPI property)
PR_PAGER_TELEPHONE_NUMBER
(MAPI property)
PR_POSTAL_CODE
(MAPI property)
PR_PRIMARY_FAX_NUMBER
(MAPI (property)
PR_STATE_OR_PROVINCE
(MAPI property)
PR_STREET_ADDRESS
(MAPI property)
PR_SURNAME
(MAPI property)
PR_TELEX_NUMBER
(MAPI property)
PR_TITLE
(MAPI property)


Information Store Objects

The Microsoft Exchange information store is an implementation of a MAPI message store. Behavior specific to Microsoft Exchange Server is exposed through some of the standard information store attributes.

The most commonly used Microsoft Exchange Server information store objects represent MAPI message stores, messages, folders, attachments, and sessions.


Attachment Object

A message can have an attachment—additional data in the form of a file, another message, or an OLE object associated with it. This attachment appears either as an icon or metafile embedded within or adjacent to the main body of a message. A message can have zero, one, or many attachments. Attachments are always transmitted with the message.

An attachment object represents a document that is an attachment of a message. For more information on the attachment object, see the Active Messaging Library. To create a new attachment within a message, call the IMessage::CreateAttach method, which is implemented by information store providers.

For more information on accessing attachment objects through MAPI, see Message Transfer Envelopes and Attached Messages.


Attachment Properties

The following attachment property is declared by Microsoft Exchange Server in the EDKMDB.H file. No properties are declared by MAPI for attachment objects.

Property | Access
PR_IN_CONFLICT | Read-only


Notes on Using Attachments

  • All properties for attachments cause RPCs No attachment property can be retrieved without causing an RPC.
  • No bookmark support The Microsoft Exchange Server information store provider does not support the setting of bookmarks in attachment tables. However, the personal folders provider does support bookmarks in attachment tables in PSTs.


Folder Object

A folder object is a MAPI object that provides access to a folder in an information store. You use a folder object to manipulate messages within a folder. You create folder objects with the MAPI calls IMsgStore::OpenEntry (for an existing folder) and IMAPIFolder::CreateFolder (for a new folder), and you release folder objects with a call to IUnknown::Release.

Because folders reside in Microsoft Exchange Server information stores, this section describes the way the Microsoft Exchange Server information store provider implements folder objects.

For more information on accessing folder objects through MAPI, see Working with Folders.

After a call to CreateFolder or OpenEntry, the entry identifier of the open folder is stored on the client. (You used the entry identifier of the folder to open it.) Because it is stored locally, getting this property does not cause an RPC.

Note This section describes the implementation of properties by the Microsoft Exchange Server information store provider, not the service provider that controls access to a user’s set of personal folders (which are stored in a file that usually has the extension .PST.)


Folder Interface

The IMAPIFolder interface is used to perform operations on folders, such as creating, copying, and deleting messages and subfolders. For more information on this interface, see the MAPI Programmer’s Reference.


Microsoft Exchange Server Folder Properties

The folder properties in the following tables are declared by Microsoft Exchange Server in the EDKMDB.H file. The first table lists properties used on both private and public information stores, the second table lists properties used on folders in private information stores, and the third table lists properties used on folders in public information stores.

Microsoft Exchange Server Properties on Private and Public Folders

Property Designation | Description
PR_ACL_DATA | Read/write. Contains the binary form of the PR_ACL_TABLE object.
PR_ACL_TABLE | Read-only. Consists of a table that contains all access control lists (ACLs) applied to this folder.
PR_CHANGE_KEY | Read/write property. Returns a binary value indicating the last type of change that took place on the message or folder.
PR_FOLDER_CHILD_COUNT | Read-only. 32-bit integer that contains the number of child folders contained within the folder object.
PR_GW_ADMIN_OPERATIONS | Read/write. Used on a folder, is interpreted as a set of flags indicating operations allowed on messages in the folder. When used on a message, this property carries instructions for actions by the gateway.
PR_HAS_RULES | Read-only. Boolean value indicating whether or not the folder has rules in force.
PR_PARENT_SOURCE_KEY | Read-only. Used in incremental change synchronization and is available on folders and messages.
PR_PREDECESSOR_CHANGE_LIST | Read-only. Contains a list of change keys, including the current PR_CHANGE_KEY.
PR_RESOLVE_METHOD | Read/write. Indicates which resolution method will be used to resolve conflicts on messages in the folder.
PR_RIGHTS | Read-only. Indicates the user's effective rights on the folder.
PR_RULES_DATA | Read/write. Binary form of the PR_RULES_TABLE object.
PR_RULES_TABLE | Read-only. Consists of a table that contains all rules applied to this folder.

Microsoft Exchange Server Private Folder Properties

Property Designation | Description
PR_SOURCE_KEY | Read-only. Identifies the folder or message for further changes and deletions.

Microsoft Exchange Server Public Folder Properties

Property Designation | Description
PR_SECURE_ORIGINATION | Read/write. Indicates whether the messages moved into the folder are modified to look like a forwarded message that Microsoft Exchange Server did not generate.
PR_DESIGN_IN_PROGRESS | Read/write. Boolean value that can be set (with IMAPIProp::SetProps) only by an owner. If set to TRUE, only owners can have access to the folder object.
PR_ADDRESS_BOOK_ENTRYID | Read-only. Consists of the name-service entry identifier of a public folder.
PR_FOLDER_DESIGN_FLAGS | Read/write. Contains a reason for the status of the folder, which is PR_DESIGN_IN_PROGRESS, meaning that no access to the folder is possible during this time.
PR_PUBLISH_IN_ADDRESS_BOOK | Read/write. Indicates whether the folder display name appears in the address book.
PR_REPLICA_LIST | Read/write. Contains a list of the distinguished names of the servers that are replicating the contents of the public folder.


MAPI Folder Properties

The properties listed in the following table are declared by MAPI in the MAPITAGS.H file. They are all read-only properties. For a list of required MAPI folder properties, see the table that follows this one.

MAPI Folder Properties

Property Designation | Description
PR_ACCESS | Contains a bitmask of flags indicating the operations the client application can perform on the open object.
PR_ACCESS_LEVEL | Contains a bitmask of flags indicating the level at which the client application can access the open object.
PR_ASSOC_CONTENT_COUNT | Contains the count of items in the associated contents folder.
PR_CONTENT_COUNT | Contains the number of entries in a container, as computed by the information store.
PR_CONTENT_UNREAD | Contains a count of unread messages in a folder.
PR_DISPLAY_TYPE | Contains a value used to associate an icon with a particular row of a table.
PR_ENTRYID | Contains a MAPI entry identifier used to open and edit properties of a particular MAPI object.
PR_FOLDER_TYPE | Contains a constant that indicates the folder type.
PR_MAPPING_SIGNATURE | Contains the mapping signature for named properties of a particular MAPI object.
PR_MDB_PROVIDER | Contains a provider-defined identifier that indicates the type of the information store.
PR_MESSAGE_SIZE | Contains the sum in bytes of the sizes of all properties on a message object.
PR_OBJECT_TYPE | Contains the type of an object.
PR_PARENT_ENTRYID | Contains the entry identifier of the folder containing a folder or message.
PR_RECORD_KEY | Contains a unique binary-comparable identifier for a specific object.
PR_SEARCH_KEY | Contains a binary-comparable key that identifies correlated objects for a search.
PR_STORE_ENTRYID | Contains the unique entry identifier of the information store in which an object resides.
PR_STORE_RECORD_KEY | Contains the unique binary-comparable identifier (record key) of the information store in which an object resides.
PR_SUBFOLDERS | Contains TRUE if a folder contains subfolders.

The following folder properties are declared by MAPI, and are required. See Required and Optional Message Properties.

Required Folder Properties

PR_DISPLAY_NAME | Read/write
PR_ENTRYID | Read-only
PR_FOLDER_TYPE | Read/write
PR_OBJECT_TYPE | Read-only
PR_PARENT_DISPLAY | Read-only
PR_PARENT_ENTRYID | Read-only
PR_RECORD_KEY | Read-only
PR_STORE_ENTRYID | Read-only
PR_STORE_RECORD_KEY | Read-only


Working with Folder Objects

Newly created folders have the following special characteristics:

  • When created, the ACL of a new folder is set to the ACL of its parent folder plus the folder’s creator (the caller of IMAPIFolder::CreateFolder), which is added as an owner of the folder.
  • Replication settings for public folders are set to the parent folder’s settings if they are not set explicitly on the child folder. Otherwise, use the replication settings of the information store.
  • A directory store object is created when a public folder is created. That is, when you call CreateFolder on a public information store, the information store provider also creates an object for that folder in the directory. This object may be hidden to users by the address book provider unless the PR_PUBLISH_IN_ADDRESS_BOOK property is set.

Access Rights Needed for GetProps and SetProps

You can call IMAPIProp::GetProps if you have read-only access, and you need owner access to call IMAPIProp::SetProps. Certain replication properties require administrator’s rights to the site object in order to set them. For more information about accessing objects in the information store, see About Information Store Security.

SaveContentsSort

The IMAPIFolder::SaveContentsSort method is not implemented by the Microsoft Exchange Server information store provider and will return MAPI_E_NO_SUPPORT if called. Normally, calling this method stores the messages within a folder in a given sort order. In this case, Microsoft Exchange Server automatically caches indices on an LRU (least recently used) basis and automatically saving the sorted list to disk for future use. This makes calling SaveContentsSort unnecessary.

Notes on Folder Usage

  • The IMAPIContainer::GetHierarchyTable method is not implemented by the Microsoft Exchange Server information store provider.
  • You can use the CopyFolder method to copy or move any folders to other locations. The folder to be copied need not be a direct child folder of the providing object (the folder object for which the IMAPIFolder interface was returned).
  • There is no limit to the length of folder names and comments. NULL (““) folder names are not supported.
  • You can create and save messages in a public information store, but you cannot submit messages from a public information store. If you create a message in a public information store, you can have the message take on the nature of a move/copy message or a forwarded message. A move/copy message has properties as you have assigned them. Creating a message as a forwarded message assigns properties as if it had been sent to the public information store. The message receives a sender property (whoever dragged the message to the public folder) and a recipient property (which refers to the public folder itself).

Additional Folder Property Interfaces

These complex folder properties are objects and are accessed as such. You can open them like any other object, and an interface is returned.

Folder Property | Interface
PR_HIERARCHY_SYNCHRONIZER | IExchangeImportHierarchyChanges
PR_COLLECTOR | IExchangeExportChanges
PR_CONTENTS_SYNCHRONIZER | IExchangeExportChanges
PR_RULES_TABLE | IExchangeModifyTable
PR_ACL_TABLE | IExchangeModifyTable

Using Contents Tables

A contents table lists summary information about mail user or Distribution-List objects in address book containers, or about messages in folders. Address book providers implement contents tables for each of their containers. Both information store and remote transport providers implement contents tables for folders. For more information, see the MAPI Programmer’s Reference.

The following topics apply to the use of contents tables.

Sorting Limitations

The Microsoft Exchange Server information store provider supports sorting on the PR_NORMALIZED_SUBJECT and PR_SUBJECT_PREFIX properties, but not on the PR_SUBJECT property. Clients are expected to sort on the PR_NORMALIZED_SUBJECT property. For example, a call to IMAPITable::SortTable with PR_SUBJECT as the key fails on EMS_PRIVATE (and returns the error MAPI_E_TOO_COMPLEX), while the PST provider supports this call.

Truncation

In contents tables (returned with QueryRows), the Microsoft Exchange Server information store provider truncates both binary and text properties.


Message Object

The message object is a MAPI object that provides a view of a message. You create message objects with the following MAPI function calls: MAPIMessage::OpenEntry (for an existing message) and IMAPIFolder::CreateMessage (for a new message). You destroy message objects with a call to IUnknown::Release.

This section describes how the Microsoft Exchange Server information store provider implements message objects.

For more information on accessing message objects through MAPI, see Working with Messages.

For more information on the MAPI IMessage interface, see Message Interface.

For more information about information store properties declared by Microsoft Exchange Server and by MAPI, see Microsoft Exchange Server Message Properties and MAPI Message Properties with Special Behavior.

Note This section describes the implementation of properties by the Microsoft Exchange Server information store provider, not the service provider that controls access to a user’s set of personal folders, which are usually stored in a file with the extension .PST.


Message Interface

The IMessage interface is used for managing messages, attachments, and recipients. For more information on this interface, see the MAPI Programmer’s Reference.


Microsoft Exchange Server Message Properties

In addition to the standard message properties defined by MAPI, a number of message properties specific to Microsoft Exchange Server are declared by Microsoft Exchange Server in the EDKMDB.H file.

The following tables list these properties by usage type. Some properties in this section appear in more than one table. None of the message properties in the following tables are required to be present on a message.

The properties in the first table are for general use. For example, the PR_CREATOR_NAME property can be used to identify the creator of the message; particularly for messages in public folders. This is useful because the creator of a message is granted more permissions on that message than other users. The PR_REPLICA_SERVER property is used to determine the server on which the copy resides.

General Message Properties

Property Designation | Description
PR_CHANGE_KEY | Read-only. Returns a binary value indicating the last change that took place on the message or folder.
PR_CREATOR_NAME | Read-only. Specifies the display name of the user who created the message.
PR_LAST_MODIFIER_ENTRYID | Read-only. Specifies the entry identifier of the last person to modify the message.
PR_LAST_MODIFIER_NAME | Read-only. Contains the display name of the last person to modify the message.
PR_PARENT_SOURCE_KEY | Read-only. Used in incremental change synchronization. Available on folders and messages.
PR_PREDECESSOR_CHANGE_LIST | Read/write. Contains a list of change keys, including the current PR_CHANGE_KEY.
PR_REPLICA_SERVER | Read-only. Specifies the name of the server on which the copy of the message resides.
PR_SOURCE_KEY | Read/write. Identifies the folder or message.

To reduce the number of RPCs, certain functions that you call to manipulate message properties are automatically deferred by the Microsoft Exchange Server information store provider. Two examples are the IMAPIProp::SetProps and IMAPIProp::DeleteProps methods. This means that, for example, deleting a nonexistent property can return a SUCCESS_SUCCESS result where the MAPI_E_ERRORS_RETURNED result might be expected. Typically, the deferral of error reports and function calls is governed by the use of the MAPI_DEFERRED_ERRORS flag. For more information, see Using the MAPI_DEFERRED_ERRORS Flag.

In the Microsoft Exchange Client, the Send property page (which appears when you select Options from the Tools menu) is controlled by the server-based information store provider of Microsoft Exchange Server. A third-party application can also use these properties if it uses the Microsoft Exchange Server information store service provider.

The properties in the following table are set by the sender using the Send property page of the Microsoft Exchange Client. For example, PR_DEFERRED_SEND_TIME determines when a message is actually to be sent. PR_DEFERRED_SEND_TIME is used by the information store to defer messages at sending time and PR_DEFERRED_DELIVERY_TIME is used to defer messages at delivery time. These are all read/write properties.

Send Options Message Properties

Property Designation | Description
PR_DEFERRED_SEND_NUMBER | Indicates how many units of time to wait before sending a message.
PR_DEFERRED_SEND_TIME | Indicates a time at which a message should be sent.
PR_DEFERRED_SEND_UNITS | Specifies the unit of time to be used with the PR_DEFERRED_SEND_NUMBER property to determine the PR_DEFERRED_SEND_TIME for a deferred message.
PR_EXPIRY_NUMBER | Contains the number of time units that must pass before the message disappears if unread.
PR_EXPIRY_UNITS | Contains the time unit to be used in calculating the time for a message to expire.


MAPI Message Properties with Special Behavior

This section describes the special ways MAPI message properties are implemented by the Microsoft Exchange Server information store provider.

The following three tables list properties defined by MAPI for messages in general, report messages (such as delivery reports and read reports), and recipients. The properties listed in these tables are all required, as explained in Required and Optional Message Properties.

Required Message Properties

PR_CREATION_TIME | Read-only. New messages
PR_DISPLAY_BCC | Read-only. Saved messages
PR_DISPLAY_CC | Read-only. Saved messages
PR_DISPLAY_TO | Read-only. Saved messages
PR_ENTRYID | Read-only. Saved messages
PR_LAST_MODIFICATION_TIME | Read-only. Saved messages
PR_MESSAGE_CLASS | Read/write. All messages
PR_MESSAGE_FLAGS | Read-only. All messages. Writeable on unsaved messages.
PR_PARENT_DISPLAY | Read-only. All messages
PR_PARENT_ENTRYID | Read-only. All messages
PR_RECORD_KEY | Read-only. All messages
PR_SEARCH_KEY | Read/write. All messages
PR_STORE_ENTRYID | Read-only. All messages
PR_STORE_RECORD_KEY | Read-only. All messages

Required Message Report Properties

PR_BODY | Read/write
PR_MESSAGE_CLASS | Read/write
PR_MESSAGE_DELIVERY_TIME | Read-only
PR_ORIGINAL group of properties | Read-only
PR_REPORT_TAG | Read-only
PR_REPORT_TEXT | Read-only
PR_REPORT_TIME | Read-only
PR_SEARCH_KEY | Read-only
PR_SENDER group of properties | Read-only
PR_SUBJECT | Read/write
PR_NDR_DIAG_CODE | Required for NDRs
PR_NDR_REASON_CODE | Required for NDRs

Required Message Recipient Properties

PR_ADDRTYPE | Read/write
PR_DISPLAY_NAME | Read/write
PR_DISPLAY_TYPE | Read/write
PR_ENTRYID | Read/write
PR_OBJECT_TYPE | Read-only


Notes on MAPI Properties

You can increase the efficiency of how to use MAPI properties with Microsoft Exchange Server in the following ways.

Address Resolution

When you call IMAPIProp::SetProps or IMessage::ModifyRecipients, the Microsoft Exchange Server information store provider resolves addresses to either a native EX address-type entry identifier or a MAPI one-off format entry identifier. Similarly, when calling ModifyRecipients, a personal address book distribution list (DL) is expanded on the client side, and each recipient in that distribution list is stored as either a native EX address-type entry identifier or a MAPI one-off address.

Personal address book DLs are not expanded until the message is submitted. This means that it may not be possible to resolve a recipient entry identifier if the address-book provider is not currently available.

Methods Cached at the Client

The Microsoft Exchange Server information store provider has both a client and a server component. Each one uses its own memory space, in which it manipulates message objects. Some of the message’s properties exist on the message object on the client and some exist on the server, as shown in the illustration under About Information Store Client and Server Components. You can use this feature to increase the performance of your application. For more information, see Application Performance.

In addition, calls to IMAPIProp::SetProps, IMAPIProp::DeleteProps, and IMessage::ModifyRecipients are cached on the client until a call to IMAPIProp::GetProps or IMAPIProp::SaveChanges causes them to be executed on the server, or until a buffer that holds them is full. The rule of thumb is that the information store provider does write caching, but not read caching. This means that a call to the GetProps method, which gets (reads the value of) properties stored on the server computer is not cached, but rather executed immediately, thereby causing an RPC. The only method affected by the MAPI_DEFERRED_ERRORS flag is IMAPIProp::SaveChanges.

For more information on this and other performance-related issues, see Application Performance.

RTF Awareness

The Microsoft Exchange Server information store is RTF-aware. In other words, only the PR_COMPRESSED_RTF property is stored, which means that you never need to set the PR_BODY property. In fact, getting or setting PR_BODY can cause substandard server performance. When copying the message text from one message to another, it is best to call IMAPIProp::GetProps on PR_COMPRESSED_RTF for the first message and then call IMAPIProp::SetProps on PR_COMPRESSED_RTF for the second message.

The PR_COMPRESSED_RTF and PR_BODY properties are stored so that setting or deleting one property also sets or deletes the other.

Unicode Versions of Text Properties

The Microsoft Exchange Server information store provider supports IMAPIProp::SetProps and IMAPIProp::GetProps PT_UNICODE versions of all text properties except the PR_BODY property. It does not support setting the message text in Unicode. In general, it is recommended that you use PR_COMPRESSED_RTF instead of PR_BODY. If your application runs with Unicode as its effective codepage (the encoding of bytes into characters, do not use PT_STRING8 versions of the properties. In this case, only PT_UNICODE versions are supported.[[commented out because Milind wrote: “this can never happen in real life.” (Ok, but ask him why.)]] ›If your application runs with a non-Unicode code page, you can use both PT_STRING8 and PT_UNICODE versions of the text properties as you like.

Message Submission

Microsoft Exchange Server can grant or deny access to an application that is submitting a message. A message is accepted for submission if the SENT_REPRESENTING property is set to an addressable object in the Microsoft Exchange Server directory. Therefore, it can be set to nothing (the message is not being sent on behalf of another), or to a Microsoft Exchange Server user, a Microsoft Exchange Server distribution list, or a public folder.

Folder Access Rights

The ability to call IMsgStore::OpenEntry to open a message depends on the effective access rights on the folder containing the message in the context of the current session. For example, this determines whether a given message can be opened read/write, read-only, or not at all. Another factor that affects access is whether the caller is the creator of the message; that is, whether the entry identifier of the user you are logged on as matches PR_CREATOR_ENTRYID).

PR_MESSAGE_FLAGS

This is an unsigned long (ULONG) property. It is writeable if the message has not yet been saved. The information store provider does not set or clear the MAPI MSGFLAG_FROMME flag on this property. Also, the information store provider sets the MSGFLAG_READ flag (within PR_MESSAGE_FLAGS) on a per-user basis on messages in a public information store.

Properties of Posted Messages

The following properties should be set by the calling application on a message posted to a Microsoft Exchange Server public folder. These properties appear in addition to those set automatically by the Microsoft Exchange Server information store when the message is created. For a list of those properties, see Properties Set at Message Creation.

  • PR_MESSAGE_CLASS Set this property to IPM.Post. Setting this gives you the Post icon displayed by the Microsoft Exchange Client, and a read form that includes the Post Reply in This Folder toolbar button.
  • PR_SUBJECT Optional property, but Microsoft Exchange Server derives PR_CONVERSATION_TOPIC from PR_SUBJECT.
  • PR_BODY Optional property.
  • PR_SENDER_ENTRYID Property returned by QueryIdentity.
  • PR_SENDER_NAME Property read from the object returned by QueryIdentity.
  • PR_SENT_REPRESENTING_ENTRYID In this example, this property is set to the value of PR_SENDER_ENTRYID, but it can be set to a different property if delegate access is used.
  • PR_SENT_REPRESENTING_NAME In this example, this property is set to the value of PR_SENDER_NAME, but it can be set to a different property if delegate access is used. This is the string that appears in the From column in the right pane of the Microsoft Exchange Client.
  • PR_DELETE_AFTER_SUBMIT The client sets this property to 0 (FALSE) when it posts a message.
  • PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED The client sets this property to 0 (FALSE) when it posts a message. This property is ignored by the information store on public folder postings because no delivery actually takes place.
  • PR_READ_RECEIPT_REQUESTED The client sets this property to 0 (FALSE) when it posts a message. This property is ignored by the information store because there is no specified recipient for a public folder posting.
  • PR_PRIORITY Set appropriately. PRIO_NORMAL is the default.


Message Store Object

The message store object is a MAPI object that provides a view of an information store. It contains messages and folders organized hierarchically and implements the IMsgStore interface, which is used to access the folders in an information store and the messages in those folders.

The Microsoft Exchange Server information stores are accessed through their message store objects:

  • Public information store Contains public folders and resides on server computers.
  • Private information store Contains users’ mailboxes on server computers.
  • Offline information store Contains synchronized copies of folders stored on the server.
  • Personal information store Stores documents and messages in .PST files on client computers.

For more information on accessing message store objects through MAPI, see Working with Information Stores.

You create a message store object to access a particular information store with a call to IMAPISession::OpenMsgStore. You destroy a message store object with a call to IUnknown::Release.

For more information on the IMsgStore interface, see Message Store Interface. For more information on information store properties declared by Microsoft Exchange Server and by MAPI, see Microsoft Exchange Server Information Store Properties and MAPI Message Store Properties.


Message Store Interface

The IMsgStore interface provides access to details about the information store. For more information on this interface, see the MAPI Programmer’s Reference.


Microsoft Exchange Server Information Store Properties

Features that are specific to Microsoft Exchange Server information stores are accessed as properties and interfaces, and are defined in EDKMDB.H. Most properties on message store objects are read-only.

The information store properties declared by Microsoft Exchange Server in the EDKMDB.H file are listed in the following table. This table also indicates whether a function call to retrieve the value of a given property causes an RPC. For more information, see Reducing the Number of RPCs.

Microsoft Exchange Server Information Store Properties

Property Designation | Access | Causes RPC?
PR_EFORMS_REGISTRY_ENTRYID | Read-only | No
PR_FREE_BUSY_FOR_LOCAL_SITE_ENTRYID | Read-only | No
PR_GW_MTSIN_ENTRYID | Read-only | No
PR_GW_MTSOUT_ENTRYID | Read-only | No
PR_IPM_DAF_ENTRYID | Read-only | No
PR_MAILBOX_OWNER_ENTRYID | Read-only | Yes
PR_MAILBOX_OWNER_NAME | Read-only | Yes
PR_NON_IPM_SUBTREE_ENTRYID | Read-only | No
PR_OFFLINE_MESSAGE_ENTRYID | Read-only | No
PR_OOF_STATE | Read/write | Yes
PR_SCHEDULE_FOLDER_ENTRYID | Read-only | No
PR_SPLUS_FREE_BUSY_ENTRYID | Read-only | No
PR_TRANSFER_ENABLED | Read/write | Yes
PR_USER_ENTRYID | Read-only | Yes
PR_USER_NAME | Read-only | Yes


MAPI Message Store Properties

The following table lists message store properties declared by MAPI in the MAPITAGS.H file. This table also indicates whether a function call to retrieve the value of a given property causes an RPC. See Reducing the Number of RPCs.

MAPI Message Store Properties

Property Designation | Access | Causes RPC?
PR_ACCESS_LEVEL | Read-only | No
PR_COMMENT | Read/write | No
PR_DELETE_AFTER_SUBMIT | Read/write | Yes
PR_DISPLAY_NAME | Read/write | No
PR_ENTRYID | Read-only | No
PR_IPM_COMMON_VIEWS_ENTRYID | Read-only | No
PR_IPM_WASTEBASKET_ENTRYID | Read-only | No
PR_IPM_OUTBOX_ENTRYID | Read-only | No
PR_IPM_SENTMAIL_ENTRYID | Read-only | No
PR_IPM_SUBTREE_ENTRYID | Read-only | No
PR_IPM_VIEWS_ENTRYID | Read-only | No
PR_MDB_PROVIDER | Read-only | No
PR_OBJECT_TYPE | Read-only | No
PR_RECORD_KEY | Read-only | Yes
PR_OVERALL_MSG_AGE_LIMIT | Read-only | Yes
PR_SENTMAIL_ENTRYID | Read/write | Yes
PR_STORE_STATE | Read-only | No
PR_STORE_ENTRYID | Read-only | No
PR_STORE_RECORD_KEY | Read-only | No
PR_STORE_SUPPORT_MASK | Read-only | No
PR_VALID_FOLDER_MASK | Read-only | No


Notes on Using Message Store Properties

  • New message store properties You cannot create new properties on message store objects. You can, however, create properties on messages, folders, and attachments.
  • Message store properties on the profile The PR_DISPLAY_NAME and PR_COMMENT properties are stored in a user’s profile, not on the server. This allows users to assign display names to the information store services in their profiles.
  • Values of PR_MDB_PROVIDER This MAPI property contains a provider-defined identifier that indicates the type of the message store. For more information, see Identifying Providers by Provider GUIDs.
  • Unsupported Functions on Public Message Stores You cannot call the following MAPI methods to perform actions on public information stores: IMsgStore::SetReceiveFolder, IMsgStore::GetReceiveFolder, IMsgStore::GetReceiveFolderTable, and IMsgStore::AbortSubmit.
  • Unicode Not Supported for GetReceiveFolder Calling the MAPI IMsgStore::GetReceiveFolder method with the MAPI_UNICODE flag set causes an error (MAPI_E_BAD_CHARWIDTH) to be returned.
  • Notifications Calling the Advise method to request all notifications on the entire public information store is not supported. An Advise method call for all notifications on the private information store refers to all notifications on the mailbox, not for the entire private information store. For more information, see Using Event Notifications.


About the Directory Schema

The directory schema is the description within a Microsoft Exchange Server directory of all object classes and objects, and their attributes and inheritance structure. For programming purposes, every person, workgroup, location, gateway, mailbox agent, and resource within a Microsoft Exchange Server organization can be considered an object in the directory with a set of attributes. Groups of objects with the same attributes belong to the same object class. In other words, an object’s class defines the set of attributes it possesses. A single, specific object in the class is referred to as an instance of the object class. For example, JohnJ (the e-mail name for John Jones) is an instance of the Mail-Recipient class.


About Object Inheritance

Microsoft Exchange Server objects in the same class share a common set of attributes and behaviors. An object class derived from another class inherits all the attributes of that class. These derived classes, also called subclasses, usually include additional attributes of their own. For example, the classes Mailbox and Public-Folder are subclasses of the Mail-Recipient class, and both represent objects that can receive messages. In this case, the Mail-Recipient class is referred to as the superclass of Mailbox and Public-Folder. In the directory, any object class has exactly one superclass (except the Top class, which has no superclass).

Because objects inherit all attributes of the class above them, the schema can be represented using a tree structure. For example, the Mailbox-Agent class contains all attributes of the Mailbox class, the Mail-Recipient class, and the Top class because it inherits them from three levels of classes above it in the schema.


Directory Schema Reference

You will not normally modify the directory schema because it is a predefined part of Microsoft Exchange Server. However, it is helpful to refer to the schema when identifying an object's inherited and original attributes. For more information about the directory schema, see Directory Schema Contents.

The contents page of the directory schema reference lists the classes of the directory schema in a way that shows their inheritance structure. The following illustration shows how the directory schema contents page uses indentation to show subclass and superclass relationships, and thus inheritance.

Part of directory schema contents page, showing subclasses

In this illustration, the Top class is not indented. The Add-In class is indented one level, which means that it is a subclass of (and inherits directly from) the Top class. The next three classes listed also inherit from Top. The DSA class is beneath and indented from the class Application-Entity, and therefore inherits from Application-Entity, which in turn inherits from Top. (All classes inherit, directly or indirectly, from the Top class.)

The contents page lets you look up class information according to class hierarchy, but you can also find this information alphabetically. At the contents page, you can click a class name to see the attributes that belong to a member of that class. You can then obtain further class or attribute information as described in Navigating the Directory Schema Reference.


Navigating the Directory Schema Reference

At the contents page, click a class name to see the attributes that belong to a member of that class. At this point, you can obtain further class or attribute information.


Obtaining Class Information

Click Class Information to see more information about that class — specifically, the following elements and their values. Some of these elements are useful for those doing development work and some are not.

Details of Directory Schema Classes

Element | Meaning
ClassName | Name of the object’s class.
LDAPName | Attribute name used by LDAP clients.
Boot | System-level information assigned when the directory is populated. Not used by developers.
Space | Part of the OID for this object. Values are X500 or ms (Microsoft). Not used by developers.
ClassID | Part of the OID for this object. Not used by developers.
Package | Part of the OID for this object. Not used by developers.
Rdn | The relative distinguished name (RDN) of this object. Same as the object’s Common-Name.
SubOf | The object’s parent in the inheritance hierarchy. The object inherits directly from this object.
Superiors | Possible parents of the object in the DIT hierarchy. In other words, you can create an object of this (ClassName) class only under objects of the classes listed as Superiors.
Heuristics | 0 = class is replicated between sites; 1 = class is not replicated between sites
Comment | Additional information.


Obtaining Attribute Information

Click any attribute listed in the Attribute column to see more information about that attribute — specifically, the following elements and their values. Some of these elements are useful for those doing development work and some are not.

Details of Directory Schema Attributes

Element | Meaning
LDAPName | Attribute name used by LDAP clients.
Boot | System-level information assigned when the directory is populated. Not used by developers.
Space | Part of the OID for this attribute. Values are X500 or ms (Microsoft). Not used by developers.
AttID | Part of the OID for this object. Not used by developers.
SyntaxName | The attribute’s data type, such as Boolean, Integer, String(Octet), and Object(DS-DN).
MinLen | If the data type is an enumeration, the smallest value in the range of valid numbers. If the data type is string, the minimum size in bytes (0 or 1).
MaxLen | If the data type is an enumeration, the largest value in the range of valid numbers. If the data type is string, the maximum size in bytes, such as 255 or 32768; if the attribute is multivalued, this number applies to each of the attribute’s values.
Multi | Is this a multivalued attribute? TRUE or FALSE.
Acl | Requestors who have write access to this attribute. Possible values include System, Admin, and User. Requestors’ permissions are interrelated as follows: System = system only Admin = system + admin User = system + admin + user
MapiID | The attribute’s MAPI identifier, which is defined in EMSABTAGS.H.
Heuristics | Attribute configuration, including selected information on replication and security.

Within this set of information, you can find out more about the value of SyntaxName for this attribute — for example, String(Octet) — by clicking it.


Directory Schema Contents

The following table lists the classes of objects defined in the Microsoft Exchange Server 5.0 directory schema. By clicking a class name in the table, you see a description of the attributes that belong to an object in that class.

Required Attributes

In the attribute descriptions, attributes marked with an X in the Must column are required. This means that the attribute must be present on any object of this type. Function calls that attempt to create or import an object that is missing one or more required attributes will fail, as will function calls that attempt to delete a required attribute from an existing object. This requirement is enforced by the directory service agent of Microsoft Exchange Server. Required attributes are required not only on their object of origin, but also on any objects that inherit from it.

Top
Add-In
Admin-Extension
Addr-Type
Application-Entity
DSA
Application-Process
Attribute-Schema
Certification-Authority
Class-Schema
Container
Country
Cross-Ref
Device
Computer
Directory-Cfg
Display-Template
Address-Template
DMD
DXA-Site-Server
Encryption-Cfg
Information-Store-Cfg
Group-Of-Names
Locality
Mail-Gateway
Mail-Connector
MS-Mail-Connector
Mail-Gateway
X400-Link
Eicon-X25-X400-Link
RAS-X400-Link
RFC1006-X400-Link
TP4-X400-Link
Mail-Recipient
Distribution-List
Exchange-Admin-Service
Local-DXA
Mailbox
Mailbox-Agent
MHS-Message-Store
MHS-Public-Store
MSFT-DSA
Public-Folder
Remote-Address
MHS-Monitoring-Config
MHS-Link-Monitoring-Config
MHS-Server-Monitoring-Config
MTA
MTA-Cfg
NNTP-Newsfeed
Organization
Organizational-Role
Organizational-Unit
Person
Organizational-Person
Residential-Person
Protocol-Cfg
Protocol-Cfg-HTTP
Protocol-Cfg-HTTP-Server
Protocol-Cfg-HTTP-Site
Protocol-Cfg-LDAP
Protocol-Cfg-LDAP-Server
Protocol-Cfg-LDAP-Site
Protocol-Cfg-NNTP
Protocol-Cfg-NNTP-Server
Protocol-Cfg-NNTP-Site
Protocol-Cfg-POP
Protocol-Cfg-POP-Server
Protocol-Cfg-POP-Site
Protocol-Cfg-Shared
Protocol-Cfg-Shared-Server
Protocol-Cfg-Shared-Site
Remote-DXA
DX-Requestor
DX-Server-Conn
Replication-Connector
Site-Addressing
Strong-Authentication-User
Superior-Ref
Transport-Stack
Eicon-X25-Stack
RAS-Stack
RFC1006-Stack
TP4-Stack
Site-Connector


Alphabetical Index to Directory Schema Classes


A

Add-In
Address-Template
Addr-Type
Admin-Extension
Application-Entity
Application-Process
Attribute-Schema


C

Certification-Authority
Class-Schema
Computer
Container
Country
Cross-Ref


D

Device
Directory-Cfg
Display-Template
Distribution-List
DMD
DSA
DX-Requestor
DX-Server-Conn
DXA-Site-Server


E

Eicon-X25-Stack
Eicon-X25-X400-Link
Exchange-Admin-Service
Encryption-Cfg


G

Group-Of-Names


I

Information-Store-Cfg


L

Local-DXA
Locality


M

Mail-Connector
Mail-Gateway
Mail-Recipient
Mailbox
Mailbox-Agent
MHS-Message-Store
MHS-Link-Monitoring-Config
MHS-Monitoring-Config
MHS-Public-Store
MHS-Server-Monitoring-Config
MSFT-DSA
MS-Mail-Connector
MTA
MTA-Cfg


N

NNTP-Newsfeed


O

Organization
Organizational-Person
Organizational-Role
Organizational-Unit


P

Person
Protocol-Cfg
Protocol-Cfg-HTTP
Protocol-Cfg-HTTP-Server
Protocol-Cfg-HTTP-Site
Protocol-Cfg-LDAP
Protocol-Cfg-LDAP-Server
Protocol-Cfg-LDAP-Site
Protocol-Cfg-NNTP
Protocol-Cfg-NNTP-Server
Protocol-Cfg-NNTP-Site
Protocol-Cfg-POP
Protocol-Cfg-POP-Server
Protocol-Cfg-POP-Site
Public-Folder


R

RAS-Stack
RAS-X400-Link
Remote-Address
Remote-DXA
Replication-Connector
Residential-Person
RFC1006-Stack
RFC1006-X400-Link


S

Site-Addressing
Site-Connector
Strong-Authentication-User
Superior-Ref


T

Top
TP4-Stack
TP4-X400-Link
Transport-Stack


X

X400-Link


Add-In

Class Information

Attribute | Must | Description
Activation-Schedule |  |
Activation-Style |  |
Common-Name | X |
Computer-Name | X |
Owner |  |


Addr-Type

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of the Address-Type)
File-Version | X | Proxy address generator file version number
Proxy-Generation-Enabled |  | Whether proxy generation is enabled or not
Proxy-Generator-DLL | X | Proxy address generator file name used by this address type.


Address-Template

Class Information

Attribute | Must | Description
Address-Syntax |  | A grammer for encoding the display table propertes as a string
Address-Type |  |
Per-Msg-Dialog-Display-Table |  | The Per Message options MAPI display table
Per-Recip-Dialog-Display-Table |  | The Per Recipient options MAPI display table
Proxy-Generation-Enabled |  | Whether proxy generation is enabled or not


Admin-Extension

Class Information

Attribute | Must | Description
Admin-Extension-DLL | X |
Common-Name | X | X.500 Common Name
File-Version | X |


Application-Entity

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
Locality-Name |  |
Organization-Name |  |
Organizational-Unit-Name |  |
Presentation-Address | X |
See-Also |  |
Supported-Application-Context |  |


Application-Process

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
Locality-Name |  |
Organizational-Unit-Name |  |
See-Also |  |


Attribute-Schema

Class Information

Attribute | Must | Description
Access-Category | X | The access control category of this attribute type
Attribute-ID | X | The internal attribute Id that this record governs
Attribute-Syntax | X | Identifies the data representation syntax
Common-Name | X | X.500 Common Name (DN of this object)
Extended-Chars-Allowed |  | =1 Extended characters allowed, =0 not allowed.
Is-Single-Valued | X | Indicates if the att is single or multivalued
LDAP-Display-Name |  | LDAP display name for the attribute
Link-ID |  | Identifies Links and Backlinks (DL=>Member & Mailbox=>Is-Member-Of)
MAPI-ID |  | The MAPI ID of this attribute
OID-Type |  | Specifies the Object ID type in the scripts.
OM-Object-Class |  | The XAPIA OM Object class of this attribute (if it has one)
OM-Syntax | X | The XAPIA OM Syntax of this attribute
Range-Lower |  | Minimum size for attribute value
Range-Upper |  | Maximum size for attribute value
Schema-Flags |  | The flags for the attribute (replicate to other site or not etc.)
Search-Flags |  | TRUE will cause the DS to generate a fast search index.


Certification-Authority

Class Information

Attribute | Must | Description
Authority-Revocation-List | X | Cross Certificate CRLs
CA-Certificate | X | Certificate for CA
Certificate-Chain-V3 |  | Not used!
Certificate-Revocation-List | X | Exchange 4 client V1 CRL
Certificate-Revocation-List-V1 |  | Not Used!
Certificate-Revocation-List-V3 |  | Not Used!
Common-Name | X | X.500 Common Name (DN of this object class)
Compromised-Key-List |  | List of keys that have been compromised
Cross-Certificate-CRL |  | Not Used!
Cross-Certificate-Pair |  | V3 Cross Certificates
Delta-Revocation-List |  | From 97 X509
Domain-Def-Alt-Recip |  | KM server mailbox (used by Osmium+ clients)
DXA-Admin-Forward |  | Send token to user via E-Mail
DXA-Prev-Types |  | Enable Compatibility
Enable-Compatibility |  | Not Used!
Expiration-Time |  | Client Renewal Date
KCC-Status |  | Certificate Trust Lists
KM-Server |  | KM server mailbox
Search-Guide |  | X.509 V3 Certificate Chain
Security-Policy |  | Security Policy for this CA
Send-EMail-Message |  | Not Used! replaced by DXA-Admin-Forward that replicates between sites
Supported-Application-Context |  | X.509 V3 CRL
Teletex-Terminal-Identifier |  | Certification-Revocation-List-V1


Class-Schema

Class Information

Attribute | Must | Description
Auxiliary-Class |  | Classes from which attributes are inherited.
Common-Name | X | RDN string for DSA use only, e.g. "Class 2-5-5-3"
Governs-ID | X | The class of object that this record governs
LDAP-Display-Name |  | LDAP display Name for the object class
MAPI-Display-Type |  | The MAPI Display Type of the object class e.g. User, DL, Folder
May-Contain |  | A list of optional attributes for this class (OIDs)
Must-Contain |  | A list of required attributes for this class (OIDs)
Object-Class-Category | X | 0=88 Class, 1=Abstruct Class, 2=Structural Class & 3=Auxiliary Class
Poss-Superiors |  | The list of possible superior object classes defining DIT structure
RDN-Att-ID | X | The naming attribute for this class (OID)
Schema-Flags |  | The flags for the object class (replicate to other site or not etc.)
Sub-Class-Of | X | The parent obj class of the governsId class


Computer

Class Information

Attribute | Must | Description
Activation-Schedule |  | The schedule is used by the Server for scheduled maintenance.
Activation-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run
Log-Rollover-Interval |  |
Monitored-Configurations |  | The list of DNs of Monitoring Configurations to run on this computer
Monitored-Services |  | The list of names of the services on this computer monitored by EMS
Monitoring-Availability-Style |  |
Monitoring-Availability-Window |  |
Monitoring-Cached-Via-Mail |  | DNs of Computers from which this server caches Monitoring info by Mail
Monitoring-Cached-Via-RPC |  | DNs of Computers from which this server caches Monitoring info via RPC
Monitoring-Mail-Update-Interval |  | Number of seconds between mail-based monitoring messages
Monitoring-Mail-Update-Units |  | Units used for Updating monitoring info collected via mail
Monitoring-RPC-Update-Interval |  | Interval used for Updating monitoring info collected via mail
Monitoring-RPC-Update-Units |  | Units used for Updating monitoring info collected via RPC
Network-Address |  |
NT-Machine-Name |  | The possible full unicode name of the server (reserved for future use)
Promo-Expiration |  | The date/time after which the system will not operate
Security-Protocol |  | Security protocol information supported by this server
Sub-Site |  | Servers with the same value are in the same sub site
Tracking-Log-Path-Name |  | Path name to where the messag tracking logs are kept
Type |  |
X509-Cert |  | X509 certificate of the computer (used for strong authentication)


Container

Class Information

Attribute | Must | Description
Common-Name | X | Used as a parent object in the DIT to define a naming context
Container-Info |  | The MSB specifies if the container should show up in the Address Book
Schema-Version |  | The version of the schema
X500-RDN |  | The RDN of this container from X.500 namespace


Country

Class Information

Attribute | Must | Description
Country-Name | X |
Search-Guide |  |


CRL-Distribution-Point

Class Information

Attribute | Must | Description
Authority-Revocation-List |  |
Certificate-Revocation-List |  |
Common-Name | X |
Delta-Revocation-List |  |


Cross-Ref

Class Information

Attribute | Must | Description


Device

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
Locality-Name |  |
Organization-Name |  |
Organizational-Unit-Name |  |
Owner |  |
See-Also |  |
Serial-Number |  |


Directory-Cfg

Class Information

Attribute | Must | Description
Assoc-NT-Account |  | Anonymous Account SID
Common-Name | X |
Do-OAB-Version |  | Create OAB for down level clients
Garbage-Coll-Period |  | Specifies the Garbage Collection Period for the DS
Off-Line-AB-Containers |  | List of all the containers to use when generating the off-line AB files
Off-Line-AB-Schedule |  | Schedule telling MAD when to generate the off-line address book files
Off-Line-AB-Server |  | The server designated to generat the off-line address book files
Off-Line-AB-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run
RAS-Account |  |
RAS-Password |  | Anonymous account password
Site-Proxy-Space |  | Aliase names for the organization
Tombstone-Lifetime |  | The Lifetime of Tombstoned objects in this domain.
X500-NC |  | The X.500 Naming Context of this site


Display-Template

Class Information

Attribute | Must | Description
Address-Entry-Display-Table |  | The MAPI display table for address entry.
Address-Entry-Display-Table-MSDOS |  | The MAPI display table for address entry for MSDOS client.
Common-Name | X | X.500 Common Name (DN of the Address-Template)
Help-Data16 |  | Contains the binary help information for the template for Win16 client
Help-Data32 |  | Contains the binary help information for the template for Win32 clients
Help-File-Name |  | Name of help file that client should look for
Original-Display-Table |  | The MAPI (original) display table for address entry.
Original-Display-Table-MSDOS |  | The MAPI (original) display table for MSDOS address entry.


Distribution-List

Class Information

Attribute | Must | Description
Company |  | Mainly for AB View grouping
Department |  | Mainly for AB View grouping
DL-Member-Rule |  | Used to specify a search filter for the Rules-Based DLs function.
DXA-Task |  | Size limit after which messages can no longer be sent or received
Given-Name |  | Identifies if a DL is being used as a 'role' or a standard DL
Hide-DL-Membership |  | Indicates if he Membership should be hidden from the client (default is FALSE)
Locality-Name |  | Mainly for AB View grouping
Member |  | The list of DN's that are members of the Distribution List
OOF-Reply-To-Originator |  |
Owner |  | The DN of the Mailbox that "owns" this Distribution List.
Physical-Delivery-Office-Name |  | Mainly for AB View grouping
Report-To-Originator |  | TRUE if the message originator is to receive any reports, FALSE if not.
Report-To-Owner |  | TRUE if the Distribution List owner is to receive any reports, FALSE if not.
State-Or-Province-Name |  |
Text-Country |  | Mainly for AB View grouping
Title |  |


DMD

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
DMD-Name |  |
Foreign-DSAs |  | DSA's that exist outside of this DMD.
Local-Scope |  | a list of DSA's that are governed by this DMD


DSA

Class Information

Attribute | Must | Description
File-Version |  | Version of DSA in use
Knowledge-Information |  |


DX-Requestor

Class Information

Attribute | Must | Description
Activation-Schedule |  | The schedule is used by the DXA to determine when to export the updates
Activation-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run


DX-Server-Conn

Class Information

Attribute | Must | Description


DXA-Site-Server

Class Information

Attribute | Must | Description
Activation-Schedule |  | Schedule of when the server will send out updates
Activation-Style |  | 0=Never Update / 1=Update at Selected Times / 2=Always Update
Common-Name | X | X.500 Common Name (DN of this object)
DXA-Admin-Copy |  | TRUE=Copy the Admin on outgoing mail, FALSE=Don't
DXA-Admin-Forward |  | TRUE=Forward incoming mail to the Admin, FALSE=Don't
DXA-Local-Admin |  | DN of the local administrator of this DXA
Responsible-Local-DXA |  | Points to the Local-DXA that owns this object


Eicon-X25-Stack

Class Information

Attribute | Must | Description
X25-Call-User-Data-Incoming |  | Given by the public carrier. Example: 313 0101
X25-Facilities-Data-Incoming |  | Specifies which facilities the switch will support e.g. window size negoiation
X25-Leased-Line-Port | X | Specifies which port the Eicon card will use.
X25-Leased-or-Switched |  | If not specified defaults to Leased (TRUE=Leased, FALSE=Switched)


Eicon-X25-X400-Link

Class Information

Attribute | Must | Description
X25-Call-User-Data-Incoming |  | Given by the public carrier. Example: 313 0101
X25-Call-User-Data-Outgoing |  | Given by the public carrier. Example: 313 0101
X25-Facilities-Data-Incoming |  | Specifies which facilities the switch will support e.g. window size negoiation
X25-Facilities-Data-Outgoing |  | Specifies which facilities the switch will support e.g. window size negoiation
X25-Remote-MTA-Phone |  | Phone number of the remote X.400 MTA


Encryption-Cfg

Class Information

Attribute | Must | Description
Common-Name | X |
Default-Message-Format |  |
Encrypt-Alg-List-NA |  | List of Encryption algorithms available for North America
Encrypt-Alg-List-Other |  | List of Encryption algorithms available for non North American countries
Encrypt-Alg-Selected-NA |  | Encryption algorithm chosen for North American countries
Encrypt-Alg-Selected-Other |  | Encryption algorithm chosen for non North American countries
KM-Server |  | The server that advanced security mail is sent to to be processed by MAD
SMIME-Alg-List-NA |  |
SMIME-Alg-List-Other |  |
SMIME-Alg-Selected-NA |  |
SMIME-Alg-Selected-Other |  |


Exchange-Admin-Service

Class Information

Attribute | Must | Description
Delivery-Mechanism | X | The mechanism by which this object recieves mail - should always be XAPI
Diagnostic-reg-key |  | Registry Key where the diagnostic key/values are keptlog keys/values live


Group-Of-Names

Class Information

Attribute | Must | Description
Business-Category |  |
Common-Name | X | X.500 Common Name (DN of this object)
Member | X |
Organization-Name |  |
Organizational-Unit-Name |  |
Owner |  |
See-Also |  |


Information-Store-Cfg

Class Information

Attribute | Must | Description
Can-Create-PF |  | List of Mailboxes that can create Public Folders
Can-Create-PF-DL |  | List of DL membership that can create Public Folders
Can-Not-Create-PF |  | List of Mailboxes that can NOT create Public Folders
Can-Not-Create-PF-DL |  | List of DL membership that can NOT create Public Folders
Common-Name | X |
Display-Name |  | Not Used (DON'T USE THIS SINCE IT WILL MAKE THE OBJECT APPEAR IN AB)
Display-Name-Suffix |  | Display name prefix for all folders stored in this site.
Folders-Container |  | DN of the container into which MDBs in this domain will create folder objects
MDB-Over-Quota-Limit |  | The default number of bytes allowed over quota before sending is prevented
MDB-Storage-Quota |  | The max storage all Mailboxes are allowed (0 = 0K bytes, Absent = No limit)
Message-Tracking-Enabled |  |
Quota-Notification-Schedule |  | Schedule for MDB to send over-quota notification messages.
Quota-Notification-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run
Site-Affinity |  | Indicates cost of LAN connectivity to sites. (0=good, 100=bad, No value=none)
Site-Folder-GUID |  |
Site-Folder-Server |  |


Local-DXA

Class Information

Attribute | Must | Description
Delivery-Mechanism | X | The mechanism by which this DXA recieves mail - should always be XAPI
Diagnostic-reg-key |  | Registry Key where the diagnostic key/values are keptlog keys/values live
DXA-Admin-Update |  | Counter of major admin updates to DXA objects
DXA-In-Template-Map |  |
DXA-Out-Template-Map |  |
DXA-Template-TimeStamp |  |


Locality

Class Information

Attribute | Must | Description
Locality-Name | X |
Search-Guide |  |
See-Also |  |
State-Or-Province-Name |  |
Street-Address |  |


Mail-Connector

Class Information

Attribute | Must | Description


Mail-Gateway

Class Information

Attribute | Must | Description
Activation-Schedule |  | The schedule used by the MTA or Gateway to determine when to connect.
Activation-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run/ 3=Remote Initiated
ADMD |  | Used by the MTA to determine if Internal Trace Information should be stripped.
Auth-Orig |  | Originator(s) from whom this recipient will accept mail from
Can-Preserve-DNs |  |
Common-Name | X | X.500 Common Name (RDN of this gateway)
Computer-Name |  | The computer this gateway is running on
Connected-Domains |  | The list of other domains reached directly via this gateway
Country-Name |  | Used by the MTA to determine if Internal Trace Information should be stripped.
Deliv-Cont-Length |  | Maximum message size in K bytes. (0 = 0K bytes, Absent = No limit)
Deliv-EITs |  | Deliverable Encoded Information Types - for X.400 conversion
Deliv-Ext-Cont-Types |  | Deliverable External Content Types - For X.400 conversion
Delivery-Mechanism | X | Whether this gateway is of OSI, MDB or MT type.
Diagnostic-reg-key |  | Path to the registry key where various diagnostic log keys/values exist
DL-Mem-Reject-Perms |  | The list DLs whose members cannot submit messages to this gateway
DL-Mem-Submit-Perms |  | The list DLs whose members can submit messages to this gateway
Encapsulation-Method |  | The defualt encapsulation instructions to be used for recipietnts out this GW
Export-Containers |  | DNs of where to look for entires to export
Export-Custom-Recipients |  | If TRUE, indicates that Remote-Address's don't get exported.
Home-MDB |  | The DN of the Message Store used by this gateway
Home-MTA | X | the MTA it's associated with
Import-Container |  | DN of where to place imported entities
Import-Sensitivity |  | Sets the sensitivity level for all imported addresses
Line-Wrap |  | Specifies the Word-Wrap character position (0=don't wrap)
MDB-Backoff-Interval |  | Number of minutes MDB should wait when gateway queue is full
MDB-Msg-Time-Out-Period |  | Minutes a msg may remain unread by a gateway before the MDB will non-deliver
MDB-Storage-Quota |  | The max storage this Gateway is allowed (0 = 0K bytes, Absent = No limit)
MDB-Unread-Limit |  | Max number of unread msgs in queue before entering Backoff Interval
PRMD |  | Used by the MTA to determine if Internal Trace Information should be stripped.
Replication-Sensitivity |  |
Routing-List |  | Address space associated with this gateway (Proxy Format)
Supported-Application-Context |  | Used by the MTA for such things as 84 vs 88 conformance
Transfer-Retry-Interval |  | X.400 - Number of seconds the MTA waits before re-sending a message (10min)
Transfer-Timeout-Non-Urgent |  | X.400 - Max transfer timeout (minutes) to transmit a Non-Urgent message
Transfer-Timeout-Normal |  | X.400 - Max transfer timeout (minutes) to transmit a Normal message
Transfer-Timeout-Urgent |  | X.400 - Max transfer timeout (minutes) to transmit a Urgent message
Translation-Table-Used |  | The DN of the translation table used.
Unauth-Orig |  | Originator(s) from whom this recipient won't accpt mail from


Mail-Recipient

Class Information

Attribute | Must | Description
Alt-Recipient |  | Deliver to this recipient if can't deliver to specified recipient
Attribute-Certificate |  |
Auth-Orig |  | Originator(s) from whom this recipient will accept mail from
AutoReply |  | True if the recipient has turned on out-of-office notification
AutoReply-Message |  | IIS conference information
AutoReply-Subject |  | The Subject for the out-of-office message
Comment |  | This recipients comment in the EMS address book.
Common-Name | X | X.500 Common Name (DN of this object)
Deliv-Cont-Length |  | Maximum message size in K bytes. (0 = 0K bytes, Absent = No limit)
Deliv-EITs |  | Allowable Encoded Information Types (bodyparts)
Deliv-Ext-Cont-Types |  | '88 X.400 P1 Content Types
Deliver-And-Redirect |  | TRUE means BOTH the alternate & original recipients get a copy of the message
Display-Name |  | The String displayed by the address book
Display-Name-Printable |  | The Printable String version of the Display-Name.
DL-Mem-Reject-Perms |  | The members of these DLs cannot submit messages to this recipient
DL-Mem-Submit-Perms |  | Only members of these DLs can submit messages to this recipient
DXA-Flags |  | Bit-array of flags controlling deleted item recovery
Expiration-Time |  | Expiration time of a Mailbox, DL, ...
Extension-Attribute-1 |  | General extension attribute
Extension-Attribute-10 |  | General extension attribute
Extension-Attribute-11 |  |
Extension-Attribute-12 |  |
Extension-Attribute-13 |  |
Extension-Attribute-14 |  |
Extension-Attribute-15 |  |
Extension-Attribute-2 |  | General extension attribute
Extension-Attribute-3 |  | General extension attribute
Extension-Attribute-4 |  | General extension attribute
Extension-Attribute-5 |  | General extension attribute
Extension-Attribute-6 |  | General extension attribute
Extension-Attribute-7 |  | General extension attribute
Extension-Attribute-8 |  | General extension attribute
Extension-Attribute-9 |  | General extension attribute
Forwarding-Address |  | Address for mail to be forwarded
Garbage-Coll-Period |  | Length of time items are retained by store until they are permanently deleted
Gateway-Proxy |  | Not Used
Hide-From-Address-Book |  | default = FALSE = show in address book
Home-MDB |  | The DN of the Message Store used by this recipient
Home-MTA |  | The MTA associated with this recipient
Imported-From |  | Used by the DXA - not sure what for
Incoming-Msg-Size-Limit |  |
Internet-Encoding |  | See PR_SEND_INTERNET_ENCODING in MAPIDEFS.H
LabeledURI |  | URL specifying default HTML web page
Language |  | The language of the client
Language-ISO639 |  | ISO639 Language
Mail-Drop |  | Directory where mail is stored
Mail-nickname |  | Mail Nickname
Maintain-AutoReply-History |  | An indication to the MTA as to whether it should always return the OOF message
MAPI-Recipient |  | Indicates to a Gateway if the it's a MAPI recipient (True=Yes, False=No)
NNTP-Character-Set |  | MIME tag of the character set used by this mailbox in NNTP transactions
NNTP-Content-Format |  | The content format for the NNTP client
Override-NNTP-Content-Format |  |
POP-Character-Set |  | MIME tag of the character set used by this mailbox in POP 3 transactions
POP-Content-Format |  | The content format for the PoP client
Protocol-Settings |  | Protocol configuration information
Proxy-Addresses |  | The list of foriegn mail system addresses for this recipient
Replication-Sensitivity |  | The sensitivity of this instance to replciation beyond the local domain
Security-Protocol |  | Specifies the supported security protocols
Submission-Cont-Length |  | The max content size allowed for submission (0 = 0K bytes, Absent = No limit)
Supported-Algorithms |  | Defined in X500 93 to define supported security algorithms for recipient objec
Tagged-X509-Cert |  | Tagged X509 Certificate
Telephone-Number |  | The voice telephone number of this recipient
Unauth-Orig |  | Originator(s) from whom this recipient won't accpt mail from
Use-Server-Values |  | Whether or not to use server values
User-Cert |  | This recipient's public certificate (which contains the public key)
View-Container-1 |  |
View-Container-2 |  |
View-Container-3 |  |
View-Site |  |
Voice-Mail-Flags |  | Flags relating to voice mail
Voice-Mail-Greetings |  | The Voice Mail users recorded greeting(s)
Voice-Mail-Password |  | DTMF digits representing user account security code
Voice-Mail-Recorded-Name |  | The Voice Mail users spoken name
Voice-Mail-Recording-Length |  | Allowed Max/Min recording lengths
Voice-Mail-Speed |  | Playback speed setting
Voice-Mail-System-GUID |  | GUID identifying each Voice Mail system in operation
Voice-Mail-User-ID |  | DTMF digits representing a user account (e.g. phone extension)
Voice-Mail-Volume |  | Playback volume setting
WWW-Home-Page |  | WWW Home page associated with this entry
X500-NC |  | DN of this object in X.500 namespace
X509-Cert |  | The X.509 certificate(s) of the user


Mailbox

Class Information

Attribute | Must | Description
Address |  | Street address of the Mailbox Owner
Address-Home |  | Home Address
Assistant-Name |  | Mailbox Assistant Display Name
Assoc-NT-Account |  | The primary NT account assoceated with this Mailbox
Business-Roles |  | The business roles associated with this mailbox (e.g. Expense approver)
Company |  | Company of the Mailbox Owner
Delivery-Mechanism | X | The mechanism by which this mailbox recieves mail e.g. Message Store, XAPI
Department |  | The "Department" of this recipient.
DXA-Task |  | Mailbox size limit after which messages can no longer be sent or received
Employee-Number |  | Employee Number
Employee-Type |  | Type of Employee
Enabled-Protocols |  | Protocols enabled for this user
Folder-Pathname |  | The OWA server to use for special message classes
Form-Data |  | Outlook Web Access Form data for S+ access
Generation-Qualifier |  | Generation Qualifier e.g. Sr., Jr., IV
Given-Name |  | Specifies the first name (given name) of the Mailbox Owner
Help-Data32 |  | Outlook Web Access Form data for S+ access
House-Identifier |  | Building within a location
Initials |  | User's Initials
International-ISDN-Number |  |
Locality-Name |  | The location/City of the user
Manager |  | The "Manager" of this recipient.
MDB-Over-Quota-Limit |  | The number of bytes allowed over quota before sending is prevented
MDB-Storage-Quota |  | The max storage this Mailbox is allowed (0 = 0K bytes, Absent = No limit)
MDB-Use-Defaults |  | TRUE=Use default values, FALSE=Don't!
OWA-Server |  | Not Used!
Personal-Title |  | Personal Title (Mr. Mrs etc.)
Physical-Delivery-Office-Name |  | e.g. "1/1061"
Postal-Code |  | Postal/Zip Code
Public-Delegates |  | The list of DNs of the Public Delegates which may access this mailbox.
State-Or-Province-Name |  | The State or Province the user is located in
Street-Address |  | Physical street address
Surname |  | Specifies the last name (surname) of the Mailbox Owner
Telephone-Assistant |  | Assistant phone
Telephone-Fax |  | Fax Phone Number of the Mailbox Owner
Telephone-Home |  | Home Phone Number of the Mailbox Owner
Telephone-Home-Fax |  | Home Fax Number
Telephone-Home2 |  | Second home telephone number.
Telephone-Mobile |  | Cellular Phone Number of the Mailbox Owner
Telephone-Office1 |  | Office Phone Number (1) of the Mailbox Owner
Telephone-Office2 |  | Office Phone Number (2) of the Mailbox Owner
Telephone-Pager |  | Pager Phone Number of the Mailbox Owner
Telephone-Personal-Mobile |  | Personal Mobile Number
Telephone-Personal-Pager |  | Personal Pager Number
Teletex-Terminal-Identifier |  |
Telex-Number |  |
Text-Country |  | The country the user is located in
Title |  | Business title of the Mailbox Owner
X121-Address |  |


Mailbox-Agent

Class Information

Attribute | Must | Description
Activation-Schedule |  | Determins when the Mailbox-Agent should run.
Activation-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run
Computer-Name |  | The computer this Mailbox-Agent is running on
Owner |  | The DN of the Mailbox that "owns" this Mailbox-Agent.


MHS-Link-Monitoring-Config

Class Information

Attribute | Must | Description
Monitor-Servers |  | Indicates whether to Monitor servers or not
Monitoring-Alert-Delay |  | The delay, in seconds, before alert recipients are notified of a problem
Monitoring-Alert-Units |  | Units for Alert interval
Monitoring-Recipients |  | The list of DNs of recipients to which to send monitoring information
Monitoring-Recipients-NDR |  | The list of DNs of recipients from which NDR's should be received
Monitoring-Warning-Delay |  | The delay, in seconds, before a monitoring warning is generated
Monitoring-Warning-Units |  | Units for Warning interval


MHS-Message-Store

Class Information

Attribute | Must | Description
Delivery-Mechanism | X | The mechanism by which this MDB recieves mail - should always be MDB
Diagnostic-reg-key |  | Registry Key where the diagnostic key/values are keptlog keys/values live
DXA-Task |  | Size limit after which messages can no longer be sent or received
Home-Public-Server |  | Name of the Home Public Server for mailboxes on this Store.
Maximum-Object-ID |  |
MDB-Over-Quota-Limit |  | Default number of bytes allowed over default quota.
MDB-Storage-Quota |  | The default max storage for new objects created in the MDB.


MHS-Monitoring-Config

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (RDN of this class)
Log-Filename |  | The UNC Path Name of the Log File to log monitoring info for this config.
Monitored-Servers |  | The list of DNs of Computer objects which represented monitored servers
Monitoring-Availability-Style |  |
Monitoring-Availability-Window |  | The times during the week during when monitoring will escalate events
Monitoring-Escalation-Procedure |  | The Escalation Procedure for this monitoring config..
Monitoring-Hotsite-Poll-Interval |  | The Polling schedule for Hot Site Monitoring sites
Monitoring-Hotsite-Poll-Units |  | The units used to determine when to poll hotsite monitored sties
Monitoring-Normal-Poll-Interval |  | The Polling schedule for Normal Monitoring sites
Monitoring-Normal-Poll-Units |  | The units used to determine when to poll normal monitored sties
Runs-On |  | The list of DNs of Computer objects this config runs on - might be a backlink


MHS-Public-Store

Class Information

Attribute | Must | Description
Delivery-Mechanism | X | The mechanism by which this MDB recieves mail - should always be MDB
Diagnostic-reg-key |  | Registry Key where the diagnostic key/values are keptlog keys/values live
DXA-Task |  | Size limit after which messages can no longer be sent or received
Maximum-Object-ID |  |
MDB-Over-Quota-Limit |  | Default number of bytes allowed over default quota.
MDB-Storage-Quota |  | The default max storage for new objects created in the MDB.


MHS-Server-Monitoring-Config

Class Information

Attribute | Must | Description
Clock-Alert-Offset |  | The interval, in seconds, the clock is allowed to drift before alerting
Clock-Alert-Repair |  | Indicates if Mailbeat should adjust the remote clock
Clock-Warning-Offset |  | The interval, in seconds, the clock is allowed to drift before warning
Clock-Warning-Repair |  | Indicates if Mailbeat should adjust the remote clock
Monitor-Clock |  | Whether the config specifies to monitor the clock
Monitor-Services |  | Whether the config specifics to monitor the services
Service-Action-First |  | The set of actions to take when services misbehave...
Service-Action-Other |  | The set of actions to take when services misbehave...
Service-Action-Second |  | The set of actions to take when services misbehave...
Service-Restart-Delay |  | The delay, in seconds, before a service will be restarted
Service-Restart-Message |  | The message display prior to restarting a service


MS-Mail-Connector

Class Information

Attribute | Must | Description


MSFT-DSA

Class Information

Attribute | Must | Description
Delivery-Mechanism |  | The mechanism by which this DSA recieves mail - should always be XAPI
Diagnostic-reg-key |  | Registry Key where the diagnostic key/values are keptlog keys/values live
DMD-Location | X | Name (DN) & Address (Presentation Address) where the DMD is located
Has-Full-Replica-NCs |  | A list of full replica NCs stored on this DSA
Has-Master-NCs |  | A list of full replica NCs stored on this DSA
Invocation-Id |  | UUID of the DSA
Presentation-Address | X | OSI address of the DSA (the type depends on the transport)


MTA

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
Deliv-Cont-Length |  | Maximum message size in K bytes. (0 = 0K bytes, Absent = No limit)
Deliv-EITs |  | EITs supported by the MTA
Deliv-Ext-Cont-Types |  | Deliverable External Content Types - For X.400 conversion
Diagnostic-reg-key |  | Registry Key where the diagnostic key/values are keptlog keys/values live
Expand-DLs-Locally |  | An indication to the MTA if it should expand DLs in the origination domain
MTA-Local-Cred |  | X.400 - Password the remote MTA must use when establishing a connection
MTA-Local-Desig | X | X.400 - MTA name
Trans-Retry-Mins | X | Retry interval for connecting to other MTAs
Trans-Timeout-Mins | X | timeout interval for connecting to other MTAs


MTA-Cfg

Class Information

Attribute | Must | Description
Association-Lifetime |  | Used by the MTA when transferring messages within the Messaging Domain
Common-Name | X |
Domain-Def-Alt-Recip |  | Specifies the recipient to use when all routing fails. (dead-letter-recipient)
Message-Tracking-Enabled |  |
Num-Of-Open-Retries |  | X.400 - Number of times the MTA tries to establish a remote connection (20)
Num-Of-Transfer-Retries |  | X.400 - Number of times the MTA tries to resend a block of data (20)
Open-Retry-Interval |  | Used by the MTA when transferring messages within the Messaging Domain
RTS-Checkpoint-Size |  | X.400 - Size of data in K that is transfered in a block (1-4)
RTS-Recovery-Timeout |  | X.400 - Max number of seconds before aborting recovery of a connection (10)
RTS-Window-Size |  | X.400 - Number of Checkpoints that are sent before an ACK is expected
Session-Disconnect-Timer |  | X.400 - Number of seconds the MTA waits for an ACK after a session disconnect
Temp-Assoc-Threshold |  | When the queued messages reaches this value, another association is started
Transfer-Retry-Interval |  | X.400 - Number of seconds the MTA waits before re-sending a message (10min)
Transfer-Timeout-Non-Urgent |  | X.400 - Max transfer time/K to transmit a Non-Urgent message
Transfer-Timeout-Normal |  | X.400 - Max transfer time/K to transmit a Normal message
Transfer-Timeout-Urgent |  | X.400 - Max transfer time/K to transmit an Urgent message
Transport-Expedited-Data |  | X.400 - Used only if supported on the other end of the connection
XMIT-Timeout-Non-Urgent |  |
XMIT-Timeout-Normal |  |
XMIT-Timeout-Urgent |  |


NNTP-Newsfeed

Class Information

Attribute | Must | Description
Activation-Schedule |  | The schedule used by the NNTP connector to determine when to connect.
Activation-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run/ 3=Remote Initiated
Assoc-NT-Account |  | NT Account against which inbound connections are authenticated
Assoc-Protocol-Cfg-NNTP |  | The INC service that owns this newsfeed
Authentication-To-Use |  | The authentication method to use for all newsfeed connections
Authorized-Password |  | Password to use when connecting to the outbound host
Authorized-Password-Confirm |  | Confirmation of password to use when connecting to the outbound host
Authorized-User |  | Account name to use when connecting to the outbound host
Common-Name | X | Common name for this object
Connection-Type |  | TRUE=LAN; FALSE-Dial up
Disable-Deferred-Commit |  |
Enabled |  | Whether or not the newsfeed is enabled
Inbound-Accept-All |  | Whether or not to accept all inbound messages on this feed
Inbound-DN |  | The DN used by the remote server to logon to the Exchange server
Inbound-Host |  | Name or IP address of the hosts providing article feeds
Inbound-Newsfeed |  | List of newsgroup patterns to keep during inbound newsfeeds
Inbound-Newsfeed-Type |  | TRUE=push feed, FALSE=pull feed
Incoming-Msg-Size-Limit |  | Max size (KB) for messages fet inbound through this connector
Incoming-Password |  |
INSAdmin |  |
Newsfeed-Type | X | 0=Inbound only; 1=Outbound only; 2=Both
Newsgroup-List |  | The active list for this newsfeed in compressed format
NNTP-Distributions |  | List of distributions to replicate in the inbound and outbound feeds.
NNTP-Distributions-Flag |  | Whether the NNTP-Distributions-List represents replicate or not replicate list
Outbound-Host |  | Name or IP address of the host to which this connector feeds articles
Outbound-Host-Type |  | TRUE=Outbound host contains host name; FALSE=Outbound host contains IP address
Outbound-Newsfeed |  | List of newsgroup patterns to keep during outbound newsfeeds
Outgoing-Msg-Size-Limit |  | Max size (KB) for messages fet outbound through this connector
Port-Number |  |
RAS-Account |  |
RAS-Password |  |
RAS-Phonebook-Entry-Name |  | The name of the RAS connection information
Require-SSL |  | 1=require Secure (SSL) connection; 0=does not require Secure (SSL) connection
Send-TNEF |  | Whether or not to send rich text out of this connector
Usenet-Site-Name |  | Name of the remote Usenet site to which this connector connects


Organization

Class Information

Attribute | Must | Description
Business-Category |  |
Destination-Indicator |  |
Facsimile-Telephone-Number |  |
International-ISDN-Number |  |
Locality-Name |  |
Organization-Name | X |
Physical-Delivery-Office-Name |  |
Post-Office-Box |  |
Postal-Address |  |
Postal-Code |  |
Preferred-Delivery-Method |  |
Registered-Address |  |
Search-Guide |  |
See-Also |  |
State-Or-Province-Name |  |
Street-Address |  |
Telephone-Number |  |
Teletex-Terminal-Identifier |  |
Telex-Number |  |
User-Password |  |
X121-Address |  |


Organizational-Person

Class Information

Attribute | Must | Description
Destination-Indicator |  |
Facsimile-Telephone-Number |  |
International-ISDN-Number |  |
Locality-Name |  |
Organizational-Unit-Name |  |
Physical-Delivery-Office-Name |  |
Post-Office-Box |  |
Postal-Address |  |
Postal-Code |  |
Preferred-Delivery-Method |  |
Registered-Address |  |
State-Or-Province-Name |  |
Street-Address |  |
Teletex-Terminal-Identifier |  |
Telex-Number |  |
Title |  |
X121-Address |  |


Organizational-Role

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
Destination-Indicator |  |
Facsimile-Telephone-Number |  |
International-ISDN-Number |  |
Locality-Name |  |
Organizational-Unit-Name |  |
Physical-Delivery-Office-Name |  |
Post-Office-Box |  |
Postal-Address |  |
Postal-Code |  |
Preferred-Delivery-Method |  |
Registered-Address |  |
Role-Occupant |  |
See-Also |  |
State-Or-Province-Name |  |
Street-Address |  |
Telephone-Number |  |
Teletex-Terminal-Identifier |  |
Telex-Number |  |
X121-Address |  |


Organizational-Unit

Class Information

Attribute | Must | Description
Business-Category |  |
Destination-Indicator |  |
Facsimile-Telephone-Number |  |
International-ISDN-Number |  |
Locality-Name |  |
Organizational-Unit-Name | X | In subclass Messaging-Domain, contains the domainname.
Physical-Delivery-Office-Name |  |
Post-Office-Box |  |
Postal-Address |  |
Postal-Code |  |
Preferred-Delivery-Method |  |
Registered-Address |  |
Search-Guide |  |
See-Also |  |
State-Or-Province-Name |  |
Street-Address |  |
Telephone-Number |  |
Teletex-Terminal-Identifier |  |
Telex-Number |  |
User-Password |  |
X121-Address |  |


Person

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
See-Also |  |
Surname | X |
Telephone-Number |  |
User-Password |  |


Protocol-Cfg

Class Information

Attribute | Must | Description
Anonymous-Access |  | Whether or not anonymous access is allowed via this protocol.
Association-Lifetime |  | Length of time a connection can be idle before it is closed
Character-Set |  | MIME tag of character set used by client
Client-Access-Enabled |  | 1=client access enabled; 0=client access disabled
Common-Name | X | Directory name for the an instance of this object
Content-Type |  | Default message content type
Diagnostic-Reg-Key |  | Diagnostic registry key location
Enabled-Authorization-Packages |  | List of authorization packages enabled for this protocol.
Enabled-Protocol-Cfg |  | Whether this protocol is enabled or not
Incoming-Msg-Size-Limit |  |
Port-Number |  | The port number for the listener
Preserve-Internet-Content |  |
Require-SSL |  | 1=require Secure (SSL) connection; 0=does not require Secure (SSL) connection
Send-TNEF |  | Whether or not to send TNEF
Use-Site-Values |  | Whether to use site level values or not


Protocol-Cfg-HTTP

Class Information

Attribute | Must | Description
HTTP-Pub-AB-Attributes |  | Recipient properties viewed from the WEB
HTTP-Pub-GAL | X |
HTTP-Pub-Gal-Limit |  | Maximum number of entrys returned in a single response
HTTP-Pub-PF |  | List of Public folders that are accessible via the Web connector
HTTP-Servers |  | Associated IS servers


Protocol-Cfg-HTTP-Server

Class Information

Attribute | Must | Description


Protocol-Cfg-HTTP-Site

Class Information

Attribute | Must | Description


Protocol-Cfg-IMAP

Class Information

Attribute | Must | Description
Anonymous-Account |  | Anonymous IMAP account
Delegate-User |  | False=User doesn't have access to other mbx; True=User has access to other mbx
Folder-Pathname |  | The OWA server to use for special message classes
Form-Data |  | Outlook Web Access form data for S+ access
Help-Data32 |  | Outlook Web Access Form data for S+ access
List-Public-Folders |  | True=List Public Folders, False=Don't list Public Folders
OWA-Server |  | Not Used!
Return-Exact-Msg-Size |  | Return exact message size for IMAP client's like PINE


Protocol-Cfg-IMAP-Server

Class Information

Attribute | Must | Description


Protocol-Cfg-IMAP-Site

Class Information

Attribute | Must | Description


Protocol-Cfg-LDAP

Class Information

Attribute | Must | Description
LDAP-Search-Cfg |  |
Outgoing-Msg-Size-Limit |  | Maximum number of entries returned in a search result


Protocol-Cfg-LDAP-Server

Class Information

Attribute | Must | Description
Referral-List |  | List of referrals configured for this server


Protocol-Cfg-LDAP-Site

Class Information

Attribute | Must | Description
Referral-List |  | List of referrals to other directories


Protocol-Cfg-NNTP

Class Information

Attribute | Must | Description
Available-Distributions |  | A list of NNTP distributions which can be used at this server
Control-Msg-Folder-ID |  | The Entry ID of the PF where control messages are stored
Control-Msg-Rules |  | All control message assistant rules fort his server
INSAdmin |  | The mailbox that owns all PFs created by Internet News Service in this site
Root-Newsgroups-Folder-ID |  | The entry ID of the root public folder for newsgroups
Support-SMIME-Signatures |  | FALSE=No support for SMIME sig; TRUE=Support for SMIME sig
Usenet-Site-Name |  | The Usenet site corresponding to the Exchange org being administered


Protocol-Cfg-NNTP-Server

Class Information

Attribute | Must | Description


Protocol-Cfg-NNTP-Site

Class Information

Attribute | Must | Description


Protocol-Cfg-POP

Class Information

Attribute | Must | Description
Folder-Pathname |  | The OWA server to use for special message classes
Form-Data |  | Outlook Web Access form data for S+ access
Help-Data32 |  | Outlook Web Access Form data for S+ access
OWA-Server |  | Not Used!


Protocol-Cfg-POP-Server

Class Information

Attribute | Must | Description


Protocol-Cfg-POP-Site

Class Information

Attribute | Must | Description


Protocol-Cfg-Shared

Class Information

Attribute | Must | Description
Available-Authorization-Packages |  | List of security packages that may be configured on a per protocol basis
Character-Set-List |  | List of character sets known to the system.
Common-Name | X | The Common Name of the object
Connection-List-Filter |  | List of IP address masks, with embedded accept/reject information.
Connection-List-Filter-Type |  | The type of Connection-List-Filter attribute
Folder-Pathname |  | The OWA server to use for special message classes
Form-Data |  | Outlook Web Access form data for S+ access
Help-Data32 |  | Outlook Web Access Form data for S+ access
MIME-Types |  | MIME type
OWA-Server |  | Not Used!
Use-Site-Values |  | Whether or not to use site-level values, even if server-level values exist.


Protocol-Cfg-Shared-Server

Class Information

Attribute | Must | Description


Protocol-Cfg-Shared-Site

Class Information

Attribute | Must | Description


Public-Folder

Class Information

Attribute | Must | Description
Company |  | Mainly for AB View grouping
Delivery-Mechanism | X | The mechanism by which this folder recieves mail - should always be MDB
Department |  | Mainly for AB View grouping
Display-Name-Override |  | TRUE = Display Name can be set by non-administrator, FALSE = it can't
DXA-Task |  | Size limit after which messages can no longer be sent or received
Folder-Pathname |  | Folder path in the directory. A user can view this to find a folder.
Locality-Name |  | Mainly for AB View grouping
MDB-Over-Quota-Limit |  | The number of bytes allowed over quota before... what?
MDB-Storage-Quota |  | The max storage this Public Folder is allowed (0 = 0K bytes,Absent = No limit)
MDB-Use-Defaults |  | TRUE=Use default values, FALSE=Don't!
Moderated |  | Whether the newsgroup is moderated or not
Moderator |  | E-mail alias of the newsgroup moderator (store full name?)
Newsgroup |  | Name of the newsgroup fed to this folder
PF-Contacts |  | The DN of the Contact(s) of the folder
Physical-Delivery-Office-Name |  | Mainly for AB View grouping
State-Or-Province-Name |  | Mainly for AB View grouping
Text-Country |  | Mainly for AB View grouping
Title |  | Mainly for AB View grouping
Usenet-Site-Name |  | Name of the local Usenet site from which this folder is fed messages


RAS-Stack

Class Information

Attribute | Must | Description
Encrypt |  | 1 = RPC Encryption turned on, 0 = RPC Encryption turned off
RAS-Callback-Number |  | Optional phone number for the remote MTA to call back


RAS-X400-Link

Class Information

Attribute | Must | Description
Authorized-Domain |  | NT Domain name where the remote MTA is located
Authorized-Password |  | NT Password used to gain access to the remote domain
Authorized-User |  | NT User name used to gain access to the remote domain
RAS-Callback-Number |  | Optional phone number for the remote MTA to call back
RAS-Phone-Number |  | Optional overriding phone number to call
RAS-Phonebook-Entry-Name |  | Entry name in the RAS Phonebook
RAS-Remote-SRVR-Name |  | Remote RAS server name


Remote-Address

Class Information

Attribute | Must | Description
Address |  | Street address of the Remote Recipient
Address-Home |  | Home Address
Assistant-Name |  | Assistant Display Name
Assoc-NT-Account |  | The NT account associated with this object.
Company |  | Company of the Remote Recipient
Department |  | The "Department" of the recipient.
DXA-Task |  | Size limit after which messages can no longer be sent or received
Employee-Number |  |
Employee-Type |  |
Enabled-Protocols |  | Protocols enabled for this user
Generation-Qualifier |  | Generation Qualifier e.g. Sr., Jr., IV
Given-Name |  | Specifies the first name (given name) of the Remote Recipient
House-Identifier |  | Building within a location
Initials |  | User's initials
International-ISDN-Number |  |
Locality-Name |  | The location/City of the user.
Manager |  | The "Manager" of this recipient.
Personal-Title |  |
Physical-Delivery-Office-Name |  | The location of this recipient
Postal-Code |  | Postal/Zip Code
State-Or-Province-Name |  | The State or Province the user is located in
Street-Address |  | Physical street address
Surname |  | Specifies the last name (surname) of the Remote Recipient
Target-Address | X | Actual address of the recipient (this address is in the Proxy format)
Telephone-Assistant |  | Assistant phone
Telephone-Fax |  | Fax Phone Number of the Remote Recipient
Telephone-Home |  | Home Phone Number of the Remote Recipient
Telephone-Home-Fax |  |
Telephone-Home2 |  | Second home telephone number.
Telephone-Mobile |  | Cellular Phone Number of the Remote Recipient
Telephone-Office1 |  | Office Phone Number (1) of the Remote Recipient
Telephone-Office2 |  | Office Phone Number (2) of the Remote Recipient
Telephone-Pager |  | Pager Phone Number of the Remote Recipient
Telephone-Personal-Mobile |  |
Telephone-Personal-Pager |  |
Teletex-Terminal-Identifier |  |
Telex-Number |  |
Text-Country |  | The country the user is located in
Title |  | Business title of the Remote Recipient
User-Password |  | For authenticating users without an NT account
X121-Address |  |


Remote-DXA

Class Information

Attribute | Must | Description
Common-Name | X | Common Name For remote DXA
DXA-Append-ReqCN |  | Append Requestor's CN to the Custom Recipient DN created.
DXA-Conf-Container-List |  | List of containers from confirmed dirsync session
DXA-Conf-Req-Time |  |
DXA-Conf-Seq |  |
DXA-Conf-Seq-USN |  | Confirmed seq num to USN mapping
DXA-Exchange-Options |  | 0=None, 1=Send, 2=Receive & 3=Both
DXA-Export-Now |  | TRUE=Do export at next connection, FALSE=Don't
DXA-Flags |  |
DXA-Imp-Seq |  |
DXA-Imp-Seq-Time |  |
DXA-Imp-Seq-USN |  | Import seq num to USN mapping
DXA-Import-Now |  | TRUE=Do import at next connection, FALSE=Don't
DXA-Local-Admin |  | DN of the local admin of this foreign DXA
DXA-Native-Address-Type |  | The Address Type to use for native EMS recipients when exporting
DXA-Password |  | Two-way encrypted password to be used in the exchange.
DXA-Prev-Exchange-Options |  | Previous value of rxchange options
DXA-Prev-Export-Native-Only |  | Previous value of export native only option
DXA-Prev-In-Exchange-Sensitivity |  | The previous sensitivity level set for all imported addresses
DXA-Prev-Remote-Entries |  | Previous value of remote entries
DXA-Prev-Replication-Sensitivity |  | Specifies the Previous Sensitivity level used for this Remote-DXA
DXA-Prev-Template-Options |  | Previous value of template options
DXA-Prev-Types |  | Previous value of type
DXA-Recipient-CP |  | The code page for the foreign system
DXA-Remote-Client | X | DN of the foreign DXA Daemon
DXA-Req-Seq |  |
DXA-Req-Seq-Time |  |
DXA-Req-Seq-USN |  | Requestor seq num to USN mapping
DXA-ReqName |  | Originating requestor name
DXA-Svr-Seq |  |
DXA-Svr-Seq-Time |  |
DXA-Svr-Seq-USN |  | Server seq num to USN mapping
DXA-Task |  |
DXA-Template-Options |  | 0=None, 1=Incoming, 2=Outgoing & 3=Both
DXA-Types |  |
DXA-UnConf-Container-List |  | List of containers from unconfirmed dirsync session
Export-Containers |  | DNs of where to look for entires to export
Export-Custom-Recipients | X | If TRUE, indicates that Remote-Address's don't get exported.
Import-Container |  | DN of where to place imported entities
Import-Sensitivity |  | Sets the sensitivity level for all imported addresses
Replication-Sensitivity |  | The sensitivity of this instance to replciation beyond the local domain
Req-Seq |  |
Responsible-Local-DXA |  | Specifies which Local-DXA is associated with this Remote-DXA


Replication-Connector

Class Information

Attribute | Must | Description
Activation-Schedule |  | Schedule for replication requests sent from replicating sites from remote site
Activation-Style |  | Related attribute to activation schedule
Address-Type |  | Address type of address to use when setting up replication to remote site
Common-Name | X | Common name for this class
Inbound-Sites |  | List of sites we replicate from the remote site
KCC-Status |  |
Local-Bridge-Head |  | DN of the bridge-head server in the local site
Local-Bridge-Head-Address |  | Address of local bridge head
Outbound-Sites |  | List of sites we authorize to replicate to the remote site
Remote-Bridge-Head |  | DN of the bridge-head server in the remote site
Remote-Bridge-Head-Address |  | Initial address of the remote bridge-head server
Remote-Site |  | DN of the remote site object
Replication-Mail-Msg-Size |  |
Replication-Stagger |  | The stagger (randomization) value for adding remote replicas to the local site
Trust-Level |  | Trust level of the link (i.e. how much local site trusts the remote site)


Residential-Person

Class Information

Attribute | Must | Description
Business-Category |  |
Destination-Indicator |  |
Facsimile-Telephone-Number |  |
International-ISDN-Number |  |
Locality-Name |  |
Organizational-Unit-Name |  |
Physical-Delivery-Office-Name |  |
Post-Office-Box |  |
Postal-Address |  |
Postal-Code |  |
Preferred-Delivery-Method |  |
Registered-Address |  |
State-Or-Province-Name |  |
Street-Address |  |
Teletex-Terminal-Identifier |  |
Telex-Number |  |
Title |  |
X121-Address |  |


RFC1006-Stack

Class Information

Attribute | Must | Description


RFC1006-X400-Link

Class Information

Attribute | Must | Description


Site-Addressing

Class Information

Attribute | Must | Description
Activation-Schedule |  | The schedule used by the RID to determine when to run.
Activation-Style |  | 0=Never Run / 1=Run at Selected Times / 2=Always Run
Common-Name | X |
Disabled-Gateway-Proxy |  |
Filter-Local-Addresses |  |
Gateway-Proxy |  | Used by gateways to specify Domain Unique Proxies. Like PCM:APPSWGA
Gateway-Routing-Tree |  | The Routing Tree used by the MTA for extra-domain messages
GWART-Last-Modified |  | a time/date string
Rid-Server |  | Name of the server responsible for generating the GWART
Routing-List |  | Address space associated with this Site (Proxy Format)
Site-Proxy-Space |  | Holds the address space of the site (defined by all X.400 proxies on recips)
Space-Last-Computed |  | The time at which the "Site-Proxy-Space" was last computed


Site-Connector

Class Information

Attribute | Must | Description
Authorized-Domain |  | Override domain used to authenticate against the remote site MTA
Authorized-Password |  | Override password used to authenticate against the remote site MTA
Authorized-User |  | Override Username used to authenticate against the remote site MTA
Bridgehead-Servers |  | Bridgehead servers
Common-Name | X | X.500 Common Name (DN of the Inter-Domain Connection)
Cost |  | Specifies the "Cost" to the MTA of routing messages through this VD
Domain-Name |  | DN of Messaging-Domain object for this MTA's domain
Home-MTA |  |
Routing-List |  | Address space associated with this gateway (Proxy Format)
Target-MTAs |  | The list of MTAs in the represented msg domain to which messages my be sent


Strong-Authentication-User

Class Information

Attribute | Must | Description
User-Cert | X |


Superior-Ref

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
Ref-Full-Replicas |  | DSAs that hold replicas of the root
Ref-Master-DSA | X | Points to the DSA that holds master Root


Top

Class Information

Attribute | Must | Description
Admin-Description |  | Used by Admin to hold a small discription of any object in the directory
Admin-Display-Name |  | Admin Display Name for the object
Alt-Recipient-BL |  | Backlink for Alt-Recipient on Mail-Recipient
Ancestor-ID |  | (on NC prefix) invocation_id of dsa which created master of this NC
Assoc-Remote-DXA |  | Backlink for Responsible-Local-DXA on Remote-DXA
Auth-Orig-BL |  | Backlink for Auth-Orig on Mail-Recipient
Can-Create-PF-BL |  | Backlink for List of Mailboxes that can create Public Folders
Can-Create-PF-DL-BL |  | Backlink for List of DL membership that can create Public Folders
Can-Not-Create-PF-BL |  | Backlink for List of Mailboxes that can NOT create Public Folders
Can-Not-Create-PF-DL-BL |  | Backlink for List of DL membership that can NOT create Public Folders
Description |  | optional long description allowed on any type of object
DL-Mem-Reject-Perms-BL |  | Backlink for DL-Mem-Reject-Perms on Mail-Recipient
DL-Mem-Submit-Perms-BL |  | Backlink for DL-Mem-Submit-Perms on Mail-Recipient
DSA-Signature |  | For Replication
Extension-Data |  | Extension-specific Data blobs
Extension-Name |  | Path & Name of an Extension DLL to add property pages (NOT Inherited).
Extension-Name-Inherited |  | Path & Name of an Extension DLL to add property pages (Inherited).
Heuristics |  |
Home-MDB-BL |  | Backlink: List of users associated with a server
Instance-Type |  | identifies this as master or replica NC
Is-Deleted |  | boolean: this object is a tombstone
Is-Member-Of-DL |  | Backlink for Member on Distribution-List
Master-DSA |  | points to DSA that holds the master instance of this NC
NNTP-Newsfeeds |  | List of newsfeeds for this internet news connector
NT-Security-Descriptor |  | The NT Security descriptor controlling access to this object
Obj-Dist-Name |  | DN of this object (system-created)
Obj-View-Containers |  | The views this object is a member of
Object-Class | X | OID of this object's class and (optionally) the OIDs of its superclasses
Object-Version |  | For Replication
Owner-BL |  | Backlink on owner of a DL
Period-Rep-Sync-Times |  | for replication
Period-Repl-Stagger |  | for replication
Public-Delegates-BL |  | Backlink for Public-Delegates on Mailbox
Replicated-Object-Version |  | Object verion of this object set by LDAP bidirectional sync agent
Reports |  | List of direct reports (Backlink to Manager)
Reps-From |  | DSA Internal use for replication
Reps-To |  | DSA Internal use for replication
Reps-To-Ext |  | Contains the Attribute list & Replication-Sensitivity for Messaging Domains
Sub-Refs |  | list of subordinate references of this NC
Supporting-Stack-BL |  | Backlink for Supporting-Stack on X.400 Links
Unauth-Orig-BL |  | Backlink for Unauth-Orig on Mail-Recipient
USN-Changed |  | for replication
USN-Created |  | The USN for the object when it was created.
USN-DSA-Last-Obj-Removed |  | for replication
USN-Intersite |  | The USN for intersite replication
USN-Last-Obj-Rem |  | for replication
USN-Source |  | for replication
When-Changed |  | system timestamp of last change to this object
When-Created |  | system timestamp of creation of this object
X500-Access-Control-List |  | X500 Access Control List


TP4-Stack

Class Information

Attribute | Must | Description


TP4-X400-Link

Class Information

Attribute | Must | Description


Transport-Stack

Class Information

Attribute | Must | Description
Common-Name | X | X.500 Common Name (DN of this object)
N-Address |  | X.400 - The N-Address portion of this MTA's Presentation Address
N-Address-Type |  | X.400 - If not specified, defaults to Network Address
P-Selector |  | X.400 - The P-Selector portion of this MTA's Presentation Address
S-Selector |  | X.400 - The S-Selector portion of this MTA's Presentation Address
T-Selector |  | X.400 - The T-Selector portion of this MTA's Presentation Address
X400-Selector-Syntax |  | Specifies the syntax of the P, S, & T selecters (0 or undefined=Hex, 1=Text)


View-Container

Class Information

Attribute | Must | Description
Group-By-Attr-1 |  |
Group-By-Attr-2 |  |
Group-By-Attr-3 |  |
Group-By-Attr-4 |  |
Group-By-Attr-Value-DN |  |
Group-By-Attr-Value-Str |  |
Hide-From-Address-Book |  | default = FALSE = show in address book
View-Definition |  |
View-Flags |  |


View-Root

Class Information

Attribute | Must | Description
Hide-From-Address-Book |  | default = FALSE = show in address book


X400-Link

Class Information

Attribute | Must | Description
Association-Lifetime |  | X.400 - Number of seconds an association is idle before it is removed (60)
Gateway-Local-Cred |  | X.400 - Password the remote MTA must use when establishing a connection
Gateway-Local-Desig |  | X.400 - Password the remote MTA must use when establishing a connection
Local-Initial-Turn |  | Specifies if the initial turn on the association is local
MTA-Local-Cred |  | X.400 - Override Password for the Local MTA
MTA-Local-Desig |  | X.400 - Override Name for the Local MTA
N-Address |  | X.400 - The N-Address portion of this Gateway's Presentation Address
N-Address-Type |  | X.400 - If not specified, defaults to Network Address
Num-Of-Open-Retries |  | X.400 - Number of times the MTA tries to establish a remote connection (20)
Num-Of-Transfer-Retries |  | X.400 - Number of times the MTA tries to resend a block of data (20)
Open-Retry-Interval |  | X.400 - Number of seconds the MTA will wait before trying to re-connect (60)
P-Selector |  | X.400 - The P-Selector portion of this Gateway's Presentation Address
P-Selector-Inbound |  |
RTS-Checkpoint-Size |  | X.400 - Size of data in K that is transfered in a block (1-4)
RTS-Recovery-Timeout |  | X.400 - Max number of seconds before aborting recovery of a connection (10)
RTS-Window-Size |  | X.400 - Number of Checkpoints sent before an ACK is expected
S-Selector |  | X.400 - The S-Selector portion of this Gateway's Presentation Address
S-Selector-Inbound |  |
Session-Disconnect-Timer |  | X.400 - Number of seconds the MTA waits for an ACK after a session disconnect
Supporting-Stack |  | DN of the associated stack
T-Selector |  | X.400 - The T-Selector portion of this Gateway's Presentation Address
T-Selector-Inbound |  |
Temp-Assoc-Threshold |  | When the queued messages reaches this value, another association is started
Transport-Expedited-Data |  | X.400 - Used only if supported on the other end of the connection
Turn-Request-Threshold |  | Specifies how many comms can occur after request but before it's granted
Two-Way-Alternate-Facility |  | Specifies if the inter-MTA association is to be two way alternate
X400-Attachment-Type |  | Bodypart type to use for encoding attachments when sending to X.400 world
X400-Selector-Syntax |  | Specifies the syntax of the P, S, & T selecters (0 or undefined=Hex, 1=Text)


Add-In

ClassName: Add-In

LDAPName: | Add-In
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196644 (36, \x2A864886F714010324)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Addr-Type

ClassName: Addr-Type

LDAPName: | Addr-Type
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196665 (57, \x2A864886F714010339)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Specifies an EMS Address type: SMTP, MHS, PROFS, ...


Address-Template

ClassName: Address-Template

LDAPName: | Address-Template
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196666 (58, \x2A864886F71401033A)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Display-Template
Superiors: | Container
Heuristics: | 12
Comment: | Specifies information for an Display Template


Admin-Extension

ClassName: Admin-Extension

LDAPName: | Admin-Extension
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196629 (21, \x2A864886F714010315)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Specifies a Remote X.400 MTA


Application-Entity

ClassName: Application-Entity

LDAPName: | applicationEntity
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65548 (12, \x55060C)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container;Organizational-Unit
Heuristics: | 12
Comment: | Directory Service only uses subclass MSFT-DSA


Application-Process

ClassName: Application-Process

LDAPName: | applicationProcess
Boot: | Boot = TRUE
Space: | x500
ClassID: | 65547 (11, \x55060B)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Computer;Container
Heuristics: | 12
Comment: | Directory Service only uses subclass DSA-Application


Attribute-Schema

ClassName: Attribute-Schema

LDAPName: | Attribute-Schema
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196622 (14, \x2A864886F71401030E)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | DMD
Heuristics: | 12
Comment: | Contains all the Schema Attributes


Certification-Authority

ClassName: Certification-Authority

LDAPName: | certificationAuthority
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65552 (16, \x550610)
Package: | SAP
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Class-Schema

ClassName: Class-Schema

LDAPName: | Class-Schema
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196621 (13, \x2A864886F71401030D)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | DMD
Heuristics: | 12
Comment: | Contains all the Schema Classes


Computer

ClassName: Computer

LDAPName: | Computer
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196638 (30, \x2A864886F71401031E)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Device
Superiors: | Container
Heuristics: | 12
Comment: | Used by the DSA itself


Container

ClassName: Container

LDAPName: | Container
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196631 (23, \x2A864886F714010317)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Organizational-Unit;Container
Heuristics: | 12
Comment: | Generic Container


Country

ClassName: Country

LDAPName: | country
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65538 (2, \x550602)
Package: | bdcp
Rdn: | Country-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


CRL-Distribution-Point

ClassName: CRL-Distribution-Point

LDAPName: | CRL-Distribution-Point
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196695 (87, \x2A864886F714010357)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Cross-Ref

ClassName: Cross-Ref

LDAPName: | Cross-Ref
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196619 (11, \x2A864886F71401030B)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Device

ClassName: Device

LDAPName: | device
Boot: | Boot = TRUE
Space: | x500
ClassID: | 65550 (14, \x55060E)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | EMS only uses several subclasses


Directory-Cfg

ClassName: Directory-Cfg

LDAPName: | Directory-Cfg
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196612 (4, \x2A864886F714010304)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Display-Template

ClassName: Display-Template

LDAPName: | Display-Template
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196667 (59, \x2A864886F71401033B)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Specifies information for an Address Template


Distribution-List

ClassName: Distribution-List

LDAPName: | groupOfNames
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196655 (47, \x2A864886F71401032F)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Container
MapiDisplayType: | 1
Heuristics: | 12
Comment: | Representation of a Distribution List


DMD

ClassName: DMD

LDAPName: | DMD
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196617 (9, \x2A864886F714010309)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Application-Process;Organizational-Unit
Heuristics: | 12


DSA

ClassName: DSA

LDAPName: | dsa
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65549 (13, \x55060D)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Application-Entity
Superiors: | Computer
Heuristics: | 12
Comment: | Directory Service only uses subclass MSFT-DSA


DX-Requestor

ClassName: DX-Requestor

LDAPName: | DX-Requestor
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196627 (19, \x2A864886F714010313)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Remote-DXA
Superiors: | Container
Heuristics: | 12
Comment: | Remote DXA Requestor


DX-Server-Conn

ClassName: DX-Server-Conn

LDAPName: | DX-Server-Conn
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196628 (20, \x2A864886F714010314)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Remote-DXA
Superiors: | DXA-Site-Server
Heuristics: | 12
Comment: | Remote DXA Server


DXA-Site-Server

ClassName: DXA-Site-Server

LDAPName: | DXA-Site-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196668 (60, \x2A864886F71401033C)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Hub for all the DXA server connections


Eicon-X25-Stack

ClassName: Eicon-X25-Stack

LDAPName: | Eicon-X25-Stack
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196635 (27, \x2A864886F71401031B)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Transport-Stack
Superiors: | Computer;MTA
Heuristics: | 12
Comment: | X.25 Transport Stack for the MTA


Eicon-X25-X400-Link

ClassName: Eicon-X25-X400-Link

LDAPName: | Eicon-X25-X400-Link
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196643 (35, \x2A864886F714010323)
Package: | msmsg
Rdn: | Common-Name
SubOf: | X400-Link
Superiors: | Container
Heuristics: | 12
Comment: | Specifies a Remote X.400 MTA using an X.25 Tranasport


Encryption-Cfg

ClassName: Encryption-Cfg

LDAPName: | Encryption-Cfg
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196624 (16, \x2A864886F714010310)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Exchange-Admin-Service

ClassName: Exchange-Admin-Service

LDAPName: | Exchange-Admin-Service
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196670 (62, \x2A864886F71401033E)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Computer;Container
MapiDisplayType: | 0
Heuristics: | 12
Comment: | The MAD process


Group-Of-Names

ClassName: Group-Of-Names

LDAPName: | Group-Of-Names
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65545 (9, \x550609)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


Information-Store-Cfg

ClassName: Information-Store-Cfg

LDAPName: | Information-Store-Cfg
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196613 (5, \x2A864886F714010305)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Local-DXA

ClassName: Local-DXA

LDAPName: | Local-DXA
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196609 (1, \x2A864886F714010301)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Computer
Heuristics: | 12
Comment: | Represents the DXA process


Locality

ClassName: Locality

LDAPName: | locality
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65539 (3, \x550603)
Package: | bdcp
Rdn: | Locality-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


Mail-Connector

ClassName: Mail-Connector

LDAPName: | Mail-Connector
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196669 (61, \x2A864886F71401033D)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Gateway
Superiors: | Container
Heuristics: | 12
Comment: | Microsoft Mail Connector Object (More special than a Gateway)


Mail-Gateway

ClassName: Mail-Gateway

LDAPName: | Mail-Gateway
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196659 (51, \x2A864886F714010333)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Main Gateway Class


Mail-Recipient

ClassName: Mail-Recipient

LDAPName: | person
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196654 (46, \x2A864886F71401032E)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container;Organizational-Unit
Heuristics: | 12
Comment: | All objects that send/receive mail start here


Mailbox

ClassName: Mailbox

LDAPName: | organizationalPerson
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196630 (22, \x2A864886F714010316)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Container;Organizational-Unit
MapiDisplayType: | 0
Heuristics: | 12
Comment: | Represents of a Mailbox


Mailbox-Agent

ClassName: Mailbox-Agent

LDAPName: | Mailbox-Agent
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196625 (17, \x2A864886F714010311)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mailbox
Superiors: | Container
Heuristics: | 12
Comment: | Represents a Mailbox Process


MHS-Link-Monitoring-Config

ClassName: MHS-Link-Monitoring-Config

LDAPName: | MHS-Link-Monitoring-Config
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196620 (12, \x2A864886F71401030C)
Package: | msmsg
Rdn: | Common-Name
SubOf: | MHS-Monitoring-Config
Superiors: | Container
Heuristics: | 12
Comment: | EMS Saved Linked Monitoring Configuration


MHS-Message-Store

ClassName: MHS-Message-Store

LDAPName: | MHS-Message-Store
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196664 (56, \x2A864886F714010338)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Computer
Heuristics: | 12
Comment: | An EMS MDB


MHS-Monitoring-Config

ClassName: MHS-Monitoring-Config

LDAPName: | MHS-Monitoring-Config
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196614 (6, \x2A864886F714010306)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | EMS Saved Monitoring Configuration


MHS-Public-Store

ClassName: MHS-Public-Store

LDAPName: | MHS-Public-Store
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196636 (28, \x2A864886F71401031C)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Computer
Heuristics: | 12
Comment: | Specifies the Public Store


MHS-Server-Monitoring-Config

ClassName: MHS-Server-Monitoring-Config

LDAPName: | MHS-Server-Monitoring-Config
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196615 (7, \x2A864886F714010307)
Package: | msmsg
Rdn: | Common-Name
SubOf: | MHS-Monitoring-Config
Superiors: | Container
Heuristics: | 12
Comment: | EMS Saved Server Monitoring Configuration


MS-Mail-Connector

ClassName: MS-Mail-Connector

LDAPName: | MS-Mail-Connector
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196639 (31, \x2A864886F71401031F)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Gateway
Superiors: | Container
Heuristics: | 12
Comment: | Microsoft Mail Connector (Goal Line) Object


MSFT-DSA

ClassName: MSFT-DSA

LDAPName: | MSFT-DSA
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196616 (8, \x2A864886F714010308)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Computer
Heuristics: | 12
Comment: | Represents the DSA process on the computer


MTA

ClassName: MTA

LDAPName: | MTA
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196657 (49, \x2A864886F714010331)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Computer
Heuristics: | 12
Comment: | Represents the MTA process on the computer


MTA-Cfg

ClassName: MTA-Cfg

LDAPName: | MTA-Cfg
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196611 (3, \x2A864886F714010303)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


NNTP-Newsfeed

ClassName: NNTP-Newsfeed

LDAPName: | NNTP-Newsfeed
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196686 (78, \x2A864886F71401034E)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Organization

ClassName: Organization

LDAPName: | organization
Boot: | Boot = TRUE
Space: | x500
ClassID: | 65540 (4, \x550604)
Package: | bdcp
Rdn: | Organization-Name
SubOf: | Top
Superiors: | Top
Heuristics: | 12
Comment: | Only one is allow in the EMS Enterprise


Organizational-Person

ClassName: Organizational-Person

LDAPName: | Organizational-Person
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65543 (7, \x550607)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Person
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


Organizational-Role

ClassName: Organizational-Role

LDAPName: | organizationalRole
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65544 (8, \x550608)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


Organizational-Unit

ClassName: Organizational-Unit

LDAPName: | organizationalUnit
Boot: | Boot = TRUE
Space: | x500
ClassID: | 65541 (5, \x550605)
Package: | bdcp
Rdn: | Organizational-Unit-Name
SubOf: | Top
Superiors: | Organization;Organizational-Unit
MapiDisplayType: | 4
Heuristics: | 12
Comment: | EMS only uses subclass Messaging-Domain


Person

ClassName: Person

LDAPName: | x500Person
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65542 (6, \x550606)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


Protocol-Cfg

ClassName: Protocol-Cfg

LDAPName: | Protocol-Cfg
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196676 (68, \x2A864886F714010344)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Protocol-Cfg-HTTP

ClassName: Protocol-Cfg-HTTP

LDAPName: | Protocol-Cfg-HTTP
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196687 (79, \x2A864886F71401034F)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg
Superiors: | Protocol-Cfg-Shared-Site;Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-HTTP-Server

ClassName: Protocol-Cfg-HTTP-Server

LDAPName: | Protocol-Cfg-HTTP-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196688 (80, \x2A864886F714010350)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-HTTP
Superiors: | Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-HTTP-Site

ClassName: Protocol-Cfg-HTTP-Site

LDAPName: | Protocol-Cfg-HTTP-Site
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196689 (81, \x2A864886F714010351)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-HTTP
Superiors: | Protocol-Cfg-Shared-Site
Heuristics: | 12


Protocol-Cfg-IMAP

ClassName: Protocol-Cfg-IMAP

LDAPName: | Protocol-Cfg-IMAP
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196692 (84, \x2A864886F714010354)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg
Superiors: | Protocol-Cfg-Shared-Site;Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-IMAP-Server

ClassName: Protocol-Cfg-IMAP-Server

LDAPName: | Protocol-Cfg-IMAP-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196693 (85, \x2A864886F714010355)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-IMAP
Superiors: | Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-IMAP-Site

ClassName: Protocol-Cfg-IMAP-Site

LDAPName: | Protocol-Cfg-IMAP-Site
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196694 (86, \x2A864886F714010356)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-IMAP
Superiors: | Protocol-Cfg-Shared-Site
Heuristics: | 12


Protocol-Cfg-LDAP

ClassName: Protocol-Cfg-LDAP

LDAPName: | Protocol-Cfg-LDAP
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196683 (75, \x2A864886F71401034B)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg
Superiors: | Protocol-Cfg-Shared-Site;Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-LDAP-Server

ClassName: Protocol-Cfg-LDAP-Server

LDAPName: | Protocol-Cfg-LDAP-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196685 (77, \x2A864886F71401034D)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-LDAP
Superiors: | Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-LDAP-Site

ClassName: Protocol-Cfg-LDAP-Site

LDAPName: | Protocol-Cfg-LDAP-Site
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196684 (76, \x2A864886F71401034C)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-LDAP
Superiors: | Protocol-Cfg-Shared-Site
Heuristics: | 12


Protocol-Cfg-NNTP

ClassName: Protocol-Cfg-NNTP

LDAPName: | Protocol-Cfg-NNTP
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196680 (72, \x2A864886F714010348)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg
Superiors: | Protocol-Cfg-Shared-Site;Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-NNTP-Server

ClassName: Protocol-Cfg-NNTP-Server

LDAPName: | Protocol-Cfg-NNTP-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196682 (74, \x2A864886F71401034A)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-NNTP
Superiors: | Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-NNTP-Site

ClassName: Protocol-Cfg-NNTP-Site

LDAPName: | Protocol-Cfg-NNTP-Site
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196681 (73, \x2A864886F714010349)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-NNTP
Superiors: | Protocol-Cfg-Shared-Site
Heuristics: | 12


Protocol-Cfg-POP

ClassName: Protocol-Cfg-POP

LDAPName: | Protocol-Cfg-POP
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196677 (69, \x2A864886F714010345)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg
Superiors: | Protocol-Cfg-Shared-Site;Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-POP-Server

ClassName: Protocol-Cfg-POP-Server

LDAPName: | Protocol-Cfg-POP-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196679 (71, \x2A864886F714010347)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-POP
Superiors: | Protocol-Cfg-Shared-Server
Heuristics: | 12


Protocol-Cfg-POP-Site

ClassName: Protocol-Cfg-POP-Site

LDAPName: | Protocol-Cfg-POP-Site
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196678 (70, \x2A864886F714010346)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-POP
Superiors: | Protocol-Cfg-Shared-Site
Heuristics: | 12


Protocol-Cfg-Shared

ClassName: Protocol-Cfg-Shared

LDAPName: | Protocol-Cfg-Shared
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196673 (65, \x2A864886F714010341)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container;Computer
Heuristics: | 12


Protocol-Cfg-Shared-Server

ClassName: Protocol-Cfg-Shared-Server

LDAPName: | Protocol-Cfg-Shared-Server
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196675 (67, \x2A864886F714010343)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-Shared
Superiors: | Computer
Heuristics: | 12


Protocol-Cfg-Shared-Site

ClassName: Protocol-Cfg-Shared-Site

LDAPName: | Protocol-Cfg-Shared-Site
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196674 (66, \x2A864886F714010342)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Protocol-Cfg-Shared
Superiors: | Container
Heuristics: | 12


Public-Folder

ClassName: Public-Folder

LDAPName: | Public-Folder
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196623 (15, \x2A864886F71401030F)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Container;Organizational-Unit
MapiDisplayType: | 2
Heuristics: | 12
Comment: | Representation of a Public Folder


RAS-Stack

ClassName: RAS-Stack

LDAPName: | RAS-Stack
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196634 (26, \x2A864886F71401031A)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Transport-Stack
Superiors: | Computer;MTA
Heuristics: | 12
Comment: | RAS Transport Stack for the MTA


RAS-X400-Link

ClassName: RAS-X400-Link

LDAPName: | RAS-X400-Link
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196642 (34, \x2A864886F714010322)
Package: | msmsg
Rdn: | Common-Name
SubOf: | X400-Link
Superiors: | Container
Heuristics: | 12
Comment: | Specifies a Remote X.400 MTA using an RAS Tranasport


Remote-Address

ClassName: Remote-Address

LDAPName: | Remote-Address
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196656 (48, \x2A864886F714010330)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Recipient
Superiors: | Container;Organizational-Unit
MapiDisplayType: | 6
Heuristics: | 12
Comment: | Representation of a Remote Address


Remote-DXA

ClassName: Remote-DXA

LDAPName: | Remote-DXA
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196610 (2, \x2A864886F714010302)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Remote Directory Exchange Objects (Requester & Server)


Replication-Connector

ClassName: Replication-Connector

LDAPName: | Replication-Connector
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196672 (64, \x2A864886F714010340)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12


Residential-Person

ClassName: Residential-Person

LDAPName: | Residential-Person
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65546 (10, \x55060A)
Package: | bdcp
Rdn: | Common-Name
SubOf: | Person
Superiors: | Container
Heuristics: | 12
Comment: | Only subclasses are used by EMS


RFC1006-Stack

ClassName: RFC1006-Stack

LDAPName: | RFC1006-Stack
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196632 (24, \x2A864886F714010318)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Transport-Stack
Superiors: | Computer;MTA
Heuristics: | 12
Comment: | RFC1006 (TCP/IP) Transport Stack for the MTA


RFC1006-X400-Link

ClassName: RFC1006-X400-Link

LDAPName: | RFC1006-X400-Link
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196640 (32, \x2A864886F714010320)
Package: | msmsg
Rdn: | Common-Name
SubOf: | X400-Link
Superiors: | Container
Heuristics: | 12
Comment: | Specifies a Remote X.400 MTA using an RFC1006 (TCP/IP) Tranasport


Site-Addressing

ClassName: Site-Addressing

LDAPName: | Site-Addressing
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196608 (0, \x2A864886F714010300)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Represents the Messaging Domain


Site-Connector

ClassName: Site-Connector

LDAPName: | Site-Connector
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196658 (50, \x2A864886F714010332)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Symbolic link to another domain's MTAs


Strong-Authentication-User

ClassName: Strong-Authentication-User

LDAPName: | strongAuthenticationUser
Boot: | Boot = FALSE
Space: | x500
ClassID: | 65551 (15, \x55060F)
Package: | SAP
Rdn: | User-Certificate
SubOf: | Top
Superiors: | Container
Heuristics: | 12
Comment: | Not used by EMS


Superior-Ref

ClassName: Superior-Ref

LDAPName: | Superior-Ref
Boot: | Boot = TRUE
Space: | ms
ClassID: | 196618 (10, \x2A864886F71401030A)
Package: |
Rdn: | Common-Name
SubOf: | Top
Superiors: | MSFT-DSA
Heuristics: | 12


Top

ClassName: Top

LDAPName: | Top
Boot: | Boot = TRUE
Space: | x500
ClassID: | 65536 (0, \x550600)
Package: |
Rdn: | *none*
SubOf: | Top
Superiors: | Top
Heuristics: | 12
Comment: | Top of the Schema (all other classes inherit from Top)


TP4-Stack

ClassName: TP4-Stack

LDAPName: | TP4-Stack
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196633 (25, \x2A864886F714010319)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Transport-Stack
Superiors: | Computer;MTA
Heuristics: | 12
Comment: | TP4 Transport Stack for the MTA


TP4-X400-Link

ClassName: TP4-X400-Link

LDAPName: | TP4-X400-Link
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196641 (33, \x2A864886F714010321)
Package: | msmsg
Rdn: | Common-Name
SubOf: | X400-Link
Superiors: | Container
Heuristics: | 12
Comment: | Specifies a Remote X.400 MTA using an TP4 Tranasport


Transport-Stack

ClassName: Transport-Stack

LDAPName: | Transport-Stack
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196626 (18, \x2A864886F714010312)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Top
Superiors: | Computer;MTA
Heuristics: | 12
Comment: | Represents the X.400 Transport Stacks


View-Container

ClassName: View-Container

LDAPName: | View-Container
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196690 (82, \x2A864886F714010352)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Container
Superiors: | View-Container;View-Root
Heuristics: | 12


View-Root

ClassName: View-Root

LDAPName: | View-Root
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196691 (83, \x2A864886F714010353)
Package: | msmsg
Rdn: | Organizational-Unit-Name
SubOf: | Organizational-Unit
Superiors: | Organization
Heuristics: | 12


X400-Link

ClassName: X400-Link

LDAPName: | X400-Link
Boot: | Boot = FALSE
Space: | ms
ClassID: | 196637 (29, \x2A864886F71401031D)
Package: | msmsg
Rdn: | Common-Name
SubOf: | Mail-Gateway
Superiors: | Container
Heuristics: | 12
Comment: | Specifies a Remote X.400 MTA


Access-Category

AttName: Access-Category

LDAPName: | Access-Category
Boot: | TRUE
Space: | ms
AttID: | 131084 (12, \x2A864886F71401020C)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 6
Multi: | FALSE
MapiID: | 0x8044
Heuristics: | 4


Activation-Schedule

AttName: Activation-Schedule

LDAPName: | Activation-Schedule
Boot: | FALSE
Space: | ms
AttID: | 131285 (213, \x2A864886F71401028155)
SyntaxName: | String(Octet)
MinLen: | 84
MaxLen: | 84
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8045
Heuristics: | 12


Activation-Style

AttName: Activation-Style

LDAPName: | Activation-Style
Boot: | FALSE
Space: | ms
AttID: | 131145 (73, \x2A864886F714010249)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8046
Heuristics: | 12


Address

AttName: Address

LDAPName: | postalAddress
Boot: | FALSE
Space: | ms
AttID: | 131328 (256, \x2A864886F71401028200)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | User
MapiID: | 0x3A29
Heuristics: | 18


Address-Entry-Display-Table

AttName: Address-Entry-Display-Table

LDAPName: | Address-Entry-Display-Table
Boot: | FALSE
Space: | ms
AttID: | 131396 (324, \x2A864886F71401028244)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8017
Heuristics: | 12


Address-Entry-Display-Table-MSDOS

AttName: Address-Entry-Display-Table-MSDOS

LDAPName: | Address-Entry-Display-Table-MSDOS
Boot: | FALSE
Space: | ms
AttID: | 131472 (400, \x2A864886F71401028310)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8047
Heuristics: | 12


Address-Home

AttName: Address-Home

LDAPName: | homePostalAddress
Boot: | FALSE
Space: | ms
AttID: | 131689 (617, \x2A864886F71401028469)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 4096
Multi: | FALSE
Acl: | User
MapiID: | 0x3A5D
Heuristics: | 21


Address-Syntax

AttName: Address-Syntax

LDAPName: | Address-Syntax
Boot: | FALSE
Space: | ms
AttID: | 131327 (255, \x2A864886F7140102817F)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | FALSE
Acl: | User
MapiID: | 0x8018
Heuristics: | 12


Address-Type

AttName: Address-Type

LDAPName: | Address-Type
Boot: | FALSE
Space: | ms
AttID: | 131422 (350, \x2A864886F7140102825E)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | User
MapiID: | 0x8048
Heuristics: | 12


ADMD

AttName: ADMD

LDAPName: | ADMD
Boot: | FALSE
Space: | ms
AttID: | 131304 (232, \x2A864886F71401028168)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 16
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8049
Heuristics: | 12


Admin-Description

AttName: Admin-Description

LDAPName: | Admin-Description
Boot: | FALSE
Space: | ms
AttID: | 131298 (226, \x2A864886F71401028162)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x804A
Heuristics: | 20


Admin-Display-Name

AttName: Admin-Display-Name

LDAPName: | Admin-Display-Name
Boot: | TRUE
Space: | ms
AttID: | 131266 (194, \x2A864886F71401028142)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | User
MapiID: | 0x804B
Heuristics: | 2


Admin-Extension-DLL

AttName: Admin-Extension-DLL

LDAPName: | Admin-Extension-DLL
Boot: | FALSE
Space: | ms
AttID: | 131167 (95, \x2A864886F71401025F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 255
Multi: | FALSE
Acl: | Admin
MapiID: | 0x804C
Heuristics: | 4


Aliased-Object-Name

AttName: Aliased-Object-Name

LDAPName: | aliasedObjectName
Boot: | FALSE
Space: | x500
AttID: | 1 (1, \x550401)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x804D
Heuristics: | 12


Alt-Recipient

AttName: Alt-Recipient

LDAPName: | Alt-Recipient
Boot: | FALSE
Space: | ms
AttID: | 131198 (126, \x2A864886F71401027E)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
LinkID: | Link-6
MapiID: | 0x804E
Heuristics: | 20


Alt-Recipient-BL

AttName: Alt-Recipient-BL

LDAPName: | Alt-Recipient-BL
Boot: | FALSE
Space: | ms
AttID: | 131366 (294, \x2A864886F71401028226)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-6
Acl: | System
MapiID: | 0x804F
Heuristics: | 12


Ancestor-ID

AttName: Ancestor-ID

LDAPName: | Ancestor-ID
Boot: | TRUE
Space: | ms
AttID: | 131333 (261, \x2A864886F71401028205)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | FALSE
Acl: | System
MapiID: | 0x8050
Heuristics: | 12


Anonymous-Access

AttName: Anonymous-Access

LDAPName: | Anonymous-Access
Boot: | FALSE
Space: | ms
AttID: | 131554 (482, \x2A864886F71401028362)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8187
Heuristics: | 13


Anonymous-Account

AttName: Anonymous-Account

LDAPName: | Anonymous-Account
Boot: | FALSE
Space: | ms
AttID: | 131633 (561, \x2A864886F71401028431)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C26
Heuristics: | 13


Assistant-Name

AttName: Assistant-Name

LDAPName: | secretary
Boot: | FALSE
Space: | ms
AttID: | 131516 (444, \x2A864886F7140102833C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | User
MapiID: | 0x3A30
Heuristics: | 18


Assoc-NT-Account

AttName: Assoc-NT-Account

LDAPName: | Assoc-NT-Account
Boot: | FALSE
Space: | ms
AttID: | 131284 (212, \x2A864886F71401028154)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8027
FastSearch: | 1
Heuristics: | 12


Assoc-Protocol-Cfg-NNTP

AttName: Assoc-Protocol-Cfg-NNTP

LDAPName: | Assoc-Protocol-Cfg-NNTP
Boot: | FALSE
Space: | ms
AttID: | 131584 (512, \x2A864886F71401028400)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
LinkID: | Link-23
Acl: | Admin
MapiID: | 0x81A5
Heuristics: | 13


Assoc-Remote-DXA

AttName: Assoc-Remote-DXA

LDAPName: | Assoc-Remote-DXA
Boot: | FALSE
Space: | ms
AttID: | 131371 (299, \x2A864886F7140102822B)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-8
Acl: | System
MapiID: | 0x8051
Heuristics: | 12


Association-Lifetime

AttName: Association-Lifetime

LDAPName: | Association-Lifetime
Boot: | FALSE
Space: | ms
AttID: | 131221 (149, \x2A864886F71401028115)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8052
Heuristics: | 12


Attribute-Certificate

AttName: Attribute-Certificate

LDAPName: | Attribute-Certificate
Boot: | FALSE
Space: | ms
AttID: | 131659 (587, \x2A864886F7140102844B)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32767
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C45
Heuristics: | 13


Attribute-ID

AttName: Attribute-ID

LDAPName: | Attribute-ID
Boot: | TRUE
Space: | ms
AttID: | 131102 (30, \x2A864886F71401021E)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
Object ID Type: | ATTID
Heuristics: | 4


Attribute-Syntax

AttName: Attribute-Syntax

LDAPName: | Attribute-Syntax
Boot: | TRUE
Space: | ms
AttID: | 131104 (32, \x2A864886F714010220)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
Object ID Type: | ATTID
Heuristics: | 4


Auth-Orig

AttName: Auth-Orig

LDAPName: | Auth-Orig
Boot: | FALSE
Space: | ms
AttID: | 131201 (129, \x2A864886F71401028101)
SyntaxName: | Object(OR-Name)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-2
Acl: | User
Heuristics: | 20


Auth-Orig-BL

AttName: Auth-Orig-BL

LDAPName: | Auth-Orig-BL
Boot: | FALSE
Space: | ms
AttID: | 131362 (290, \x2A864886F71401028222)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-2
Acl: | System
MapiID: | 0x8053
Heuristics: | 12


Authentication-To-Use

AttName: Authentication-To-Use

LDAPName: | Authentication-To-Use
Boot: | FALSE
Space: | ms
AttID: | 131573 (501, \x2A864886F71401028375)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x819A
Heuristics: | 13


Authority-Revocation-List

AttName: Authority-Revocation-List

LDAPName: | authorityRevocationList
Boot: | FALSE
Space: | x500
AttID: | 38 (38, \x550426)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8026
Heuristics: | 4


Authorized-Domain

AttName: Authorized-Domain

LDAPName: | Authorized-Domain
Boot: | FALSE
Space: | ms
AttID: | 131274 (202, \x2A864886F7140102814A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 15
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8054
Heuristics: | 12


Authorized-Password

AttName: Authorized-Password

LDAPName: | Authorized-Password
Boot: | FALSE
Space: | ms
AttID: | 131265 (193, \x2A864886F71401028141)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 512
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8055
Heuristics: | 12


Authorized-Password-Confirm

AttName: Authorized-Password-Confirm

LDAPName: | Authorized-Password-Confirm
Boot: | FALSE
Space: | ms
AttID: | 131565 (493, \x2A864886F7140102836D)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 512
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8192
Heuristics: | 13


Authorized-User

AttName: Authorized-User

LDAPName: | Authorized-User
Boot: | FALSE
Space: | ms
AttID: | 131348 (276, \x2A864886F71401028214)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 512
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8056
Heuristics: | 12


AutoReply

AttName: AutoReply

LDAPName: | AutoReply
Boot: | FALSE
Space: | ms
AttID: | 131358 (286, \x2A864886F7140102821E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x800B
Heuristics: | 12


AutoReply-Message

AttName: AutoReply-Message

LDAPName: | conferenceInformation
Boot: | FALSE
Space: | ms
AttID: | 131359 (287, \x2A864886F7140102821F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | User
MapiID: | 0x800A
Heuristics: | 2


AutoReply-Subject

AttName: AutoReply-Subject

LDAPName: | AutoReply-Subject
Boot: | FALSE
Space: | ms
AttID: | 131514 (442, \x2A864886F7140102833A)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | FALSE
Acl: | User
MapiID: | 0x803E
Heuristics: | 12


Auxiliary-Class

AttName: Auxiliary-Class

LDAPName: | Auxiliary-Class
Boot: | TRUE
Space: | ms
AttID: | 131423 (351, \x2A864886F7140102825F)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Object ID Type: | CLASSID
Heuristics: | 12


Available-Authorization-Packages

AttName: Available-Authorization-Packages

LDAPName: | Available-Authorization-Packages
Boot: | FALSE
Space: | ms
AttID: | 131548 (476, \x2A864886F7140102835C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 512
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8181
Heuristics: | 13


Available-Distributions

AttName: Available-Distributions

LDAPName: | Available-Distributions
Boot: | FALSE
Space: | ms
AttID: | 131558 (486, \x2A864886F71401028366)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 10240
Multi: | FALSE
Acl: | Admin
MapiID: | 0x818B
Heuristics: | 13


Bridgehead-Servers

AttName: Bridgehead-Servers

LDAPName: | Bridgehead-Servers
Boot: | FALSE
Space: | ms
AttID: | 131535 (463, \x2A864886F7140102834F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8174
Heuristics: | 12


Business-Category

AttName: Business-Category

LDAPName: | businessCategory
Boot: | FALSE
Space: | x500
AttID: | 15 (15, \x55040F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | User
MapiID: | 0x8057
Heuristics: | 18


Business-Roles

AttName: Business-Roles

LDAPName: | Business-Roles
Boot: | FALSE
Space: | ms
AttID: | 131177 (105, \x2A864886F714010269)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8023
Heuristics: | 12


CA-Certificate

AttName: CA-Certificate

LDAPName: | cACertificate
Boot: | FALSE
Space: | x500
AttID: | 37 (37, \x550425)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8003
Heuristics: | 4


Can-Create-PF

AttName: Can-Create-PF

LDAPName: | Can-Create-PF
Boot: | FALSE
Space: | ms
AttID: | 131083 (11, \x2A864886F71401020B)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-10
Acl: | Admin
MapiID: | 0x8058
Heuristics: | 12


Can-Create-PF-BL

AttName: Can-Create-PF-BL

LDAPName: | Can-Create-PF-BL
Boot: | FALSE
Space: | ms
AttID: | 131411 (339, \x2A864886F71401028253)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-10
Acl: | System
MapiID: | 0x8059
Heuristics: | 12


Can-Create-PF-DL

AttName: Can-Create-PF-DL

LDAPName: | Can-Create-PF-DL
Boot: | FALSE
Space: | ms
AttID: | 131134 (62, \x2A864886F71401023E)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-11
Acl: | Admin
MapiID: | 0x805A
Heuristics: | 12


Can-Create-PF-DL-BL

AttName: Can-Create-PF-DL-BL

LDAPName: | Can-Create-PF-DL-BL
Boot: | FALSE
Space: | ms
AttID: | 131412 (340, \x2A864886F71401028254)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-11
Acl: | System
MapiID: | 0x805B
Heuristics: | 12


Can-Not-Create-PF

AttName: Can-Not-Create-PF

LDAPName: | Can-Not-Create-PF
Boot: | FALSE
Space: | ms
AttID: | 131135 (63, \x2A864886F71401023F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-12
Acl: | Admin
MapiID: | 0x805C
Heuristics: | 12


Can-Not-Create-PF-BL

AttName: Can-Not-Create-PF-BL

LDAPName: | Can-Not-Create-PF-BL
Boot: | FALSE
Space: | ms
AttID: | 131413 (341, \x2A864886F71401028255)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-12
Acl: | System
MapiID: | 0x805D
Heuristics: | 12


Can-Not-Create-PF-DL

AttName: Can-Not-Create-PF-DL

LDAPName: | Can-Not-Create-PF-DL
Boot: | FALSE
Space: | ms
AttID: | 131372 (300, \x2A864886F7140102822C)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-13
Acl: | Admin
MapiID: | 0x805E
Heuristics: | 12


Can-Not-Create-PF-DL-BL

AttName: Can-Not-Create-PF-DL-BL

LDAPName: | Can-Not-Create-PF-DL-BL
Boot: | FALSE
Space: | ms
AttID: | 131414 (342, \x2A864886F71401028256)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-13
Acl: | System
MapiID: | 0x805F
Heuristics: | 12


Can-Preserve-DNs

AttName: Can-Preserve-DNs

LDAPName: | Can-Preserve-DNs
Boot: | FALSE
Space: | ms
AttID: | 131527 (455, \x2A864886F71401028347)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8060
Heuristics: | 12


Certificate-Chain-V3

AttName: Certificate-Chain-V3

LDAPName: | Certificate-Chain-V3
Boot: | FALSE
Space: | ms
AttID: | 131634 (562, \x2A864886F71401028432)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C27
Heuristics: | 13


Certificate-Revocation-List

AttName: Certificate-Revocation-List

LDAPName: | certificateRevocationList
Boot: | FALSE
Space: | x500
AttID: | 39 (39, \x550427)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8016
Heuristics: | 4


Certificate-Revocation-List-V1

AttName: Certificate-Revocation-List-V1

LDAPName: | Certificate-Revocation-List-V1
Boot: | FALSE
Space: | ms
AttID: | 131636 (564, \x2A864886F71401028434)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C29
Heuristics: | 13


Certificate-Revocation-List-V3

AttName: Certificate-Revocation-List-V3

LDAPName: | Certificate-Revocation-List-V3
Boot: | FALSE
Space: | ms
AttID: | 131635 (563, \x2A864886F71401028433)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C28
Heuristics: | 13


Character-Set

AttName: Character-Set

LDAPName: | Character-Set
Boot: | FALSE
Space: | ms
AttID: | 131552 (480, \x2A864886F71401028360)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8185
Heuristics: | 13


Character-Set-List

AttName: Character-Set-List

LDAPName: | Character-Set-List
Boot: | FALSE
Space: | ms
AttID: | 131549 (477, \x2A864886F7140102835D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8182
Heuristics: | 13


Client-Access-Enabled

AttName: Client-Access-Enabled

LDAPName: | Client-Access-Enabled
Boot: | FALSE
Space: | ms
AttID: | 131631 (559, \x2A864886F7140102842F)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C24
Heuristics: | 13


Clock-Alert-Offset

AttName: Clock-Alert-Offset

LDAPName: | Clock-Alert-Offset
Boot: | FALSE
Space: | ms
AttID: | 131237 (165, \x2A864886F71401028125)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8061
Heuristics: | 12


Clock-Alert-Repair

AttName: Clock-Alert-Repair

LDAPName: | Clock-Alert-Repair
Boot: | FALSE
Space: | ms
AttID: | 131236 (164, \x2A864886F71401028124)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8062
Heuristics: | 12


Clock-Warning-Offset

AttName: Clock-Warning-Offset

LDAPName: | Clock-Warning-Offset
Boot: | FALSE
Space: | ms
AttID: | 131249 (177, \x2A864886F71401028131)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8063
Heuristics: | 12


Clock-Warning-Repair

AttName: Clock-Warning-Repair

LDAPName: | Clock-Warning-Repair
Boot: | FALSE
Space: | ms
AttID: | 131238 (166, \x2A864886F71401028126)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8064
Heuristics: | 12


Comment

AttName: Comment

LDAPName: | info
Boot: | FALSE
Space: | ms
AttID: | 131153 (81, \x2A864886F714010251)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | User
MapiID: | 0x3004
Heuristics: | 18


Common-Name

AttName: Common-Name

LDAPName: | rdn
Boot: | TRUE
Space: | x500
AttID: | 3 (3, \x550403)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A0F
FastSearch: | 1
Heuristics: | 2


Company

AttName: Company

LDAPName: | Company
Boot: | FALSE
Space: | ms
AttID: | 131218 (146, \x2A864886F71401028112)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A16
Heuristics: | 18


Compromised-Key-List

AttName: Compromised-Key-List

LDAPName: | Compromised-Key-List
Boot: | FALSE
Space: | ms
AttID: | 131614 (542, \x2A864886F7140102841E)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81C4
Heuristics: | 13


Computer-Name

AttName: Computer-Name

LDAPName: | Computer-Name
Boot: | FALSE
Space: | ms
AttID: | 131092 (20, \x2A864886F714010214)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8065
Heuristics: | 4


Connected-Domains

AttName: Connected-Domains

LDAPName: | Connected-Domains
Boot: | FALSE
Space: | ms
AttID: | 131283 (211, \x2A864886F71401028153)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 1243
Multi: | TRUE
Acl: | User
MapiID: | 0x8066
Heuristics: | 12


Connection-List-Filter

AttName: Connection-List-Filter

LDAPName: | Connection-List-Filter
Boot: | FALSE
Space: | ms
AttID: | 131547 (475, \x2A864886F7140102835B)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 10240
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8180
Heuristics: | 13


Connection-List-Filter-Type

AttName: Connection-List-Filter-Type

LDAPName: | Connection-List-Filter-Type
Boot: | FALSE
Space: | ms
AttID: | 131598 (526, \x2A864886F7140102840E)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B4
Heuristics: | 13


Connection-Type

AttName: Connection-Type

LDAPName: | Connection-Type
Boot: | FALSE
Space: | ms
AttID: | 131597 (525, \x2A864886F7140102840D)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B3
Heuristics: | 13


Container-Info

AttName: Container-Info

LDAPName: | Container-Info
Boot: | TRUE
Space: | ms
AttID: | 131368 (296, \x2A864886F71401028228)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8067
Heuristics: | 12


Content-Type

AttName: Content-Type

LDAPName: | Content-Type
Boot: | FALSE
Space: | ms
AttID: | 131553 (481, \x2A864886F71401028361)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 4
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8186
Heuristics: | 13


Control-Msg-Folder-ID

AttName: Control-Msg-Folder-ID

LDAPName: | Control-Msg-Folder-ID
Boot: | FALSE
Space: | ms
AttID: | 131555 (483, \x2A864886F71401028363)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8188
Heuristics: | 13


Control-Msg-Rules

AttName: Control-Msg-Rules

LDAPName: | Control-Msg-Rules
Boot: | FALSE
Space: | ms
AttID: | 131557 (485, \x2A864886F71401028365)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x818A
Heuristics: | 13


Cost

AttName: Cost

LDAPName: | Cost
Boot: | FALSE
Space: | ms
AttID: | 131207 (135, \x2A864886F71401028107)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8068
Heuristics: | 12


Country-Name

AttName: Country-Name

LDAPName: | c
Boot: | FALSE
Space: | x500
AttID: | 6 (6, \x550406)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8069
Heuristics: | 18


Cross-Certificate-CRL

AttName: Cross-Certificate-CRL

LDAPName: | Cross-Certificate-CRL
Boot: | FALSE
Space: | ms
AttID: | 131637 (565, \x2A864886F71401028435)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C30
Heuristics: | 13


Cross-Certificate-Pair

AttName: Cross-Certificate-Pair

LDAPName: | crossCertificatePair
Boot: | FALSE
Space: | x500
AttID: | 40 (40, \x550428)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8025
Heuristics: | 4


Default-Message-Format

AttName: Default-Message-Format

LDAPName: | Default-Message-Format
Boot: | FALSE
Space: | ms
AttID: | 131644 (572, \x2A864886F7140102843C)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C37
Heuristics: | 13


Delegate-User

AttName: Delegate-User

LDAPName: | Delegate-User
Boot: | FALSE
Space: | ms
AttID: | 131663 (591, \x2A864886F7140102844F)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C49
Heuristics: | 13


Deliv-Cont-Length

AttName: Deliv-Cont-Length

LDAPName: | Deliv-Cont-Length
Boot: | FALSE
Space: | ms
AttID: | 131210 (138, \x2A864886F7140102810A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x806A
Heuristics: | 12


Deliv-EITs

AttName: Deliv-EITs

LDAPName: | Deliv-EITs
Boot: | FALSE
Space: | ms
AttID: | 131211 (139, \x2A864886F7140102810B)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | User
MapiID: | 0x806B
Object ID Type: | ATTID
Heuristics: | 12


Deliv-Ext-Cont-Types

AttName: Deliv-Ext-Cont-Types

LDAPName: | Deliv-Ext-Cont-Types
Boot: | FALSE
Space: | ms
AttID: | 131212 (140, \x2A864886F7140102810C)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | User
MapiID: | 0x806C
Heuristics: | 12


Deliver-And-Redirect

AttName: Deliver-And-Redirect

LDAPName: | Deliver-And-Redirect
Boot: | FALSE
Space: | ms
AttID: | 131262 (190, \x2A864886F7140102813E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
MapiID: | 0x806D
Heuristics: | 12


Delivery-Mechanism

AttName: Delivery-Mechanism

LDAPName: | mailPreferenceOption
Boot: | FALSE
Space: | ms
AttID: | 131313 (241, \x2A864886F71401028171)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x806E
Heuristics: | 4


Delta-Revocation-List

AttName: Delta-Revocation-List

LDAPName: | deltaRevocationList
Boot: | FALSE
Space: | ms
AttID: | 131660 (588, \x2A864886F7140102844C)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C46
Heuristics: | 13


Department

AttName: Department

LDAPName: | department
Boot: | FALSE
Space: | ms
AttID: | 131213 (141, \x2A864886F7140102810D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A18
Heuristics: | 18


Description

AttName: Description

LDAPName: | description
Boot: | TRUE
Space: | x500
AttID: | 13 (13, \x55040D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | TRUE
Acl: | Admin
MapiID: | 0x806F
Heuristics: | 2


Destination-Indicator

AttName: Destination-Indicator

LDAPName: | destinationIndicator
Boot: | FALSE
Space: | x500
AttID: | 27 (27, \x55041B)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8070
Heuristics: | 12


Diagnostic-reg-key

AttName: Diagnostic-reg-key

LDAPName: | Diagnostic-reg-key
Boot: | FALSE
Space: | ms
AttID: | 131261 (189, \x2A864886F7140102813D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8071
Heuristics: | 12


Disable-Deferred-Commit

AttName: Disable-Deferred-Commit

LDAPName: | Disable-Deferred-Commit
Boot: | FALSE
Space: | ms
AttID: | 131630 (558, \x2A864886F7140102842E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C23
Heuristics: | 13


Disabled-Gateway-Proxy

AttName: Disabled-Gateway-Proxy

LDAPName: | Disabled-Gateway-Proxy
Boot: | FALSE
Space: | ms
AttID: | 131613 (541, \x2A864886F7140102841D)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 1024
Multi: | TRUE
Acl: | Admin
MapiID: | 0x81C3
Heuristics: | 13


Display-Name

AttName: Display-Name

LDAPName: | cn
Boot: | TRUE
Space: | ms
AttID: | 131085 (13, \x2A864886F71401020D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
FastSearch: | 2
Heuristics: | 2


Display-Name-Override

AttName: Display-Name-Override

LDAPName: | Display-Name-Override
Boot: | FALSE
Space: | ms
AttID: | 131392 (320, \x2A864886F71401028240)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8001
Heuristics: | 12


Display-Name-Printable

AttName: Display-Name-Printable

LDAPName: | name
Boot: | FALSE
Space: | ms
AttID: | 131425 (353, \x2A864886F71401028261)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x39FF
Heuristics: | 18


Display-Name-Suffix

AttName: Display-Name-Suffix

LDAPName: | Display-Name-Suffix
Boot: | FALSE
Space: | ms
AttID: | 131658 (586, \x2A864886F7140102844A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C44
Heuristics: | 13


DL-Mem-Reject-Perms

AttName: DL-Mem-Reject-Perms

LDAPName: | DL-Mem-Reject-Perms
Boot: | FALSE
Space: | ms
AttID: | 131119 (47, \x2A864886F71401022F)
SyntaxName: | Object(OR-Name)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-5
Acl: | Admin
Heuristics: | 12


DL-Mem-Reject-Perms-BL

AttName: DL-Mem-Reject-Perms-BL

LDAPName: | DL-Mem-Reject-Perms-BL
Boot: | FALSE
Space: | ms
AttID: | 131365 (293, \x2A864886F71401028225)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-5
Acl: | System
MapiID: | 0x8072
Heuristics: | 12


DL-Mem-Submit-Perms

AttName: DL-Mem-Submit-Perms

LDAPName: | DL-Mem-Submit-Perms
Boot: | FALSE
Space: | ms
AttID: | 131216 (144, \x2A864886F71401028110)
SyntaxName: | Object(OR-Name)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-3
Acl: | User
Heuristics: | 12


DL-Mem-Submit-Perms-BL

AttName: DL-Mem-Submit-Perms-BL

LDAPName: | DL-Mem-Submit-Perms-BL
Boot: | FALSE
Space: | ms
AttID: | 131363 (291, \x2A864886F71401028223)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-3
Acl: | System
MapiID: | 0x8073
Heuristics: | 12


DL-Member-Rule

AttName: DL-Member-Rule

LDAPName: | DL-Member-Rule
Boot: | FALSE
Space: | ms
AttID: | 131402 (330, \x2A864886F7140102824A)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8074
Heuristics: | 12


DMD-Location

AttName: DMD-Location

LDAPName: | DMD-Location
Boot: | TRUE
Space: | ms
AttID: | 131108 (36, \x2A864886F714010224)
SyntaxName: | Object(Access-Point)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Heuristics: | 4


DMD-Name

AttName: DMD-Name

LDAPName: | dmdName
Boot: | FALSE
Space: | ms
AttID: | 131670 (598, \x2A864886F71401028456)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C56
Heuristics: | 13


Do-OAB-Version

AttName: Do-OAB-Version

LDAPName: | Do-OAB-Version
Boot: | FALSE
Space: | ms
AttID: | 131647 (575, \x2A864886F7140102843F)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C3A
Heuristics: | 13


Domain-Def-Alt-Recip

AttName: Domain-Def-Alt-Recip

LDAPName: | Domain-Def-Alt-Recip
Boot: | FALSE
Space: | ms
AttID: | 131217 (145, \x2A864886F71401028111)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8075
Heuristics: | 12


Domain-Name

AttName: Domain-Name

LDAPName: | Domain-Name
Boot: | FALSE
Space: | ms
AttID: | 131219 (147, \x2A864886F71401028113)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 362
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8076
Heuristics: | 12


DSA-Signature

AttName: DSA-Signature

LDAPName: | DSA-Signature
Boot: | TRUE
Space: | ms
AttID: | 131146 (74, \x2A864886F71401024A)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x8077
Heuristics: | 12


DXA-Admin-Copy

AttName: DXA-Admin-Copy

LDAPName: | DXA-Admin-Copy
Boot: | FALSE
Space: | ms
AttID: | 131450 (378, \x2A864886F7140102827A)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8078
Heuristics: | 12


DXA-Admin-Forward

AttName: DXA-Admin-Forward

LDAPName: | DXA-Admin-Forward
Boot: | FALSE
Space: | ms
AttID: | 131451 (379, \x2A864886F7140102827B)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8079
Heuristics: | 12


DXA-Admin-Update

AttName: DXA-Admin-Update

LDAPName: | DXA-Admin-Update
Boot: | FALSE
Space: | ms
AttID: | 131453 (381, \x2A864886F7140102827D)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x807A
Heuristics: | 12


DXA-Append-ReqCN

AttName: DXA-Append-ReqCN

LDAPName: | DXA-Append-ReqCN
Boot: | FALSE
Space: | ms
AttID: | 131246 (174, \x2A864886F7140102812E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x807B
Heuristics: | 12


DXA-Conf-Container-List

AttName: DXA-Conf-Container-List

LDAPName: | DXA-Conf-Container-List
Boot: | FALSE
Space: | ms
AttID: | 131252 (180, \x2A864886F71401028134)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x807C
Heuristics: | 12


DXA-Conf-Req-Time

AttName: DXA-Conf-Req-Time

LDAPName: | DXA-Conf-Req-Time
Boot: | FALSE
Space: | ms
AttID: | 131194 (122, \x2A864886F71401027A)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x807D
Heuristics: | 12


DXA-Conf-Seq

AttName: DXA-Conf-Seq

LDAPName: | DXA-Conf-Seq
Boot: | FALSE
Space: | ms
AttID: | 131256 (184, \x2A864886F71401028138)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x807E
Heuristics: | 12


DXA-Conf-Seq-USN

AttName: DXA-Conf-Seq-USN

LDAPName: | DXA-Conf-Seq-USN
Boot: | FALSE
Space: | ms
AttID: | 131117 (45, \x2A864886F71401022D)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x807F
Heuristics: | 12


DXA-Exchange-Options

AttName: DXA-Exchange-Options

LDAPName: | DXA-Exchange-Options
Boot: | FALSE
Space: | ms
AttID: | 131431 (359, \x2A864886F71401028267)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8080
Heuristics: | 12


DXA-Export-Now

AttName: DXA-Export-Now

LDAPName: | DXA-Export-Now
Boot: | FALSE
Space: | ms
AttID: | 131449 (377, \x2A864886F71401028279)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8081
Heuristics: | 12


DXA-Flags

AttName: DXA-Flags

LDAPName: | DXA-Flags
Boot: | FALSE
Space: | ms
AttID: | 131178 (106, \x2A864886F71401026A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8082
Heuristics: | 12


DXA-Imp-Seq

AttName: DXA-Imp-Seq

LDAPName: | DXA-Imp-Seq
Boot: | FALSE
Space: | ms
AttID: | 131188 (116, \x2A864886F714010274)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8083
Heuristics: | 12


DXA-Imp-Seq-Time

AttName: DXA-Imp-Seq-Time

LDAPName: | DXA-Imp-Seq-Time
Boot: | FALSE
Space: | ms
AttID: | 131189 (117, \x2A864886F714010275)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8084
Heuristics: | 12


DXA-Imp-Seq-USN

AttName: DXA-Imp-Seq-USN

LDAPName: | DXA-Imp-Seq-USN
Boot: | FALSE
Space: | ms
AttID: | 131158 (86, \x2A864886F714010256)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8085
Heuristics: | 12


DXA-Import-Now

AttName: DXA-Import-Now

LDAPName: | DXA-Import-Now
Boot: | FALSE
Space: | ms
AttID: | 131448 (376, \x2A864886F71401028278)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8086
Heuristics: | 12


DXA-In-Template-Map

AttName: DXA-In-Template-Map

LDAPName: | DXA-In-Template-Map
Boot: | FALSE
Space: | ms
AttID: | 131435 (363, \x2A864886F7140102826B)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8087
Heuristics: | 12


DXA-Local-Admin

AttName: DXA-Local-Admin

LDAPName: | DXA-Local-Admin
Boot: | FALSE
Space: | ms
AttID: | 131185 (113, \x2A864886F714010271)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8088
Heuristics: | 12


DXA-Logging-Level

AttName: DXA-Logging-Level

LDAPName: | DXA-Logging-Level
Boot: | FALSE
Space: | ms
AttID: | 131454 (382, \x2A864886F7140102827E)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 1
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8089
Heuristics: | 12


DXA-Native-Address-Type

AttName: DXA-Native-Address-Type

LDAPName: | DXA-Native-Address-Type
Boot: | FALSE
Space: | ms
AttID: | 131403 (331, \x2A864886F7140102824B)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x808A
Heuristics: | 12


DXA-Out-Template-Map

AttName: DXA-Out-Template-Map

LDAPName: | DXA-Out-Template-Map
Boot: | FALSE
Space: | ms
AttID: | 131436 (364, \x2A864886F7140102826C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | Admin
MapiID: | 0x808B
Heuristics: | 12


DXA-Password

AttName: DXA-Password

LDAPName: | DXA-Password
Boot: | FALSE
Space: | ms
AttID: | 131377 (305, \x2A864886F71401028231)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 12
Multi: | FALSE
Acl: | Admin
MapiID: | 0x808C
Heuristics: | 12


DXA-Prev-Exchange-Options

AttName: DXA-Prev-Exchange-Options

LDAPName: | DXA-Prev-Exchange-Options
Boot: | FALSE
Space: | ms
AttID: | 131288 (216, \x2A864886F71401028158)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x808D
Heuristics: | 12


DXA-Prev-Export-Native-Only

AttName: DXA-Prev-Export-Native-Only

LDAPName: | DXA-Prev-Export-Native-Only
Boot: | FALSE
Space: | ms
AttID: | 131275 (203, \x2A864886F7140102814B)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x808E
Heuristics: | 12


DXA-Prev-In-Exchange-Sensitivity

AttName: DXA-Prev-In-Exchange-Sensitivity

LDAPName: | DXA-Prev-In-Exchange-Sensitivity
Boot: | FALSE
Space: | ms
AttID: | 131162 (90, \x2A864886F71401025A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x808F
Heuristics: | 12


DXA-Prev-Remote-Entries

AttName: DXA-Prev-Remote-Entries

LDAPName: | DXA-Prev-Remote-Entries
Boot: | FALSE
Space: | ms
AttID: | 131337 (265, \x2A864886F71401028209)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8090
Heuristics: | 12


DXA-Prev-Replication-Sensitivity

AttName: DXA-Prev-Replication-Sensitivity

LDAPName: | DXA-Prev-Replication-Sensitivity
Boot: | FALSE
Space: | ms
AttID: | 131287 (215, \x2A864886F71401028157)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8091
Heuristics: | 12


DXA-Prev-Template-Options

AttName: DXA-Prev-Template-Options

LDAPName: | DXA-Prev-Template-Options
Boot: | FALSE
Space: | ms
AttID: | 131467 (395, \x2A864886F7140102830B)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8092
Heuristics: | 12


DXA-Prev-Types

AttName: DXA-Prev-Types

LDAPName: | DXA-Prev-Types
Boot: | FALSE
Space: | ms
AttID: | 131289 (217, \x2A864886F71401028159)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8093
Heuristics: | 12


DXA-Recipient-CP

AttName: DXA-Recipient-CP

LDAPName: | DXA-Recipient-CP
Boot: | FALSE
Space: | ms
AttID: | 131456 (384, \x2A864886F71401028300)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 24
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8094
Heuristics: | 12


DXA-Remote-Client

AttName: DXA-Remote-Client

LDAPName: | DXA-Remote-Client
Boot: | FALSE
Space: | ms
AttID: | 131184 (112, \x2A864886F714010270)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8095
Heuristics: | 4


DXA-Req-Seq

AttName: DXA-Req-Seq

LDAPName: | DXA-Req-Seq
Boot: | FALSE
Space: | ms
AttID: | 131173 (101, \x2A864886F714010265)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8096
Heuristics: | 12


DXA-Req-Seq-Time

AttName: DXA-Req-Seq-Time

LDAPName: | DXA-Req-Seq-Time
Boot: | FALSE
Space: | ms
AttID: | 131186 (114, \x2A864886F714010272)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8097
Heuristics: | 12


DXA-Req-Seq-USN

AttName: DXA-Req-Seq-USN

LDAPName: | DXA-Req-Seq-USN
Boot: | FALSE
Space: | ms
AttID: | 131254 (182, \x2A864886F71401028136)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8098
Heuristics: | 12


DXA-ReqName

AttName: DXA-ReqName

LDAPName: | DXA-ReqName
Boot: | FALSE
Space: | ms
AttID: | 131518 (446, \x2A864886F7140102833E)
SyntaxName: | string(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8099
Heuristics: | 12


DXA-Svr-Seq

AttName: DXA-Svr-Seq

LDAPName: | DXA-Svr-Seq
Boot: | FALSE
Space: | ms
AttID: | 131432 (360, \x2A864886F71401028268)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x809A
Heuristics: | 12


DXA-Svr-Seq-Time

AttName: DXA-Svr-Seq-Time

LDAPName: | DXA-Svr-Seq-Time
Boot: | FALSE
Space: | ms
AttID: | 131433 (361, \x2A864886F71401028269)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x809B
Heuristics: | 12


DXA-Svr-Seq-USN

AttName: DXA-Svr-Seq-USN

LDAPName: | DXA-Svr-Seq-USN
Boot: | FALSE
Space: | ms
AttID: | 131196 (124, \x2A864886F71401027C)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x809C
Heuristics: | 12


DXA-Task

AttName: DXA-Task

LDAPName: | DXA-Task
Boot: | FALSE
Space: | ms
AttID: | 131172 (100, \x2A864886F714010264)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x809D
Heuristics: | 12


DXA-Template-Options

AttName: DXA-Template-Options

LDAPName: | DXA-Template-Options
Boot: | FALSE
Space: | ms
AttID: | 131430 (358, \x2A864886F71401028266)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x809E
Heuristics: | 12


DXA-Template-TimeStamp

AttName: DXA-Template-TimeStamp

LDAPName: | DXA-Template-TimeStamp
Boot: | FALSE
Space: | ms
AttID: | 131437 (365, \x2A864886F7140102826D)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x809F
Heuristics: | 12


DXA-Types

AttName: DXA-Types

LDAPName: | DXA-Types
Boot: | FALSE
Space: | ms
AttID: | 131191 (119, \x2A864886F714010277)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80A0
Heuristics: | 12


DXA-UnConf-Container-List

AttName: DXA-UnConf-Container-List

LDAPName: | DXA-UnConf-Container-List
Boot: | FALSE
Space: | ms
AttID: | 131253 (181, \x2A864886F71401028135)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80A1
Heuristics: | 12


Employee-Number

AttName: Employee-Number

LDAPName: | employeeNumber
Boot: | FALSE
Space: | ms
AttID: | 131682 (610, \x2A864886F71401028462)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 512
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C67
Heuristics: | 21


Employee-Type

AttName: Employee-Type

LDAPName: | employeeType
Boot: | FALSE
Space: | ms
AttID: | 131685 (613, \x2A864886F71401028465)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C69
Heuristics: | 21


Enable-Compatibility

AttName: Enable-Compatibility

LDAPName: | Enable-Compatibility
Boot: | FALSE
Space: | ms
AttID: | 131639 (567, \x2A864886F71401028437)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C32
Heuristics: | 13


Enabled

AttName: Enabled

LDAPName: | Enabled
Boot: | FALSE
Space: | ms
AttID: | 131629 (557, \x2A864886F7140102842D)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C21
Heuristics: | 13


Enabled-Authorization-Packages

AttName: Enabled-Authorization-Packages

LDAPName: | Enabled-Authorization-Packages
Boot: | FALSE
Space: | ms
AttID: | 131551 (479, \x2A864886F7140102835F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8184
Heuristics: | 13


Enabled-Protocol-Cfg

AttName: Enabled-Protocol-Cfg

LDAPName: | Enabled-Protocol-Cfg
Boot: | FALSE
Space: | ms
AttID: | 131587 (515, \x2A864886F71401028403)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81A8
Heuristics: | 13


Enabled-Protocols

AttName: Enabled-Protocols

LDAPName: | Enabled-Protocols
Boot: | FALSE
Space: | ms
AttID: | 131546 (474, \x2A864886F7140102835A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x817F
Heuristics: | 12


Encapsulation-Method

AttName: Encapsulation-Method

LDAPName: | Encapsulation-Method
Boot: | FALSE
Space: | ms
AttID: | 131520 (448, \x2A864886F71401028340)
SyntaxName: | Enumeration
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80A2
Heuristics: | 12


Encrypt

AttName: Encrypt

LDAPName: | Encrypt
Boot: | FALSE
Space: | ms
AttID: | 131308 (236, \x2A864886F7140102816C)
SyntaxName: | boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80A3
Heuristics: | 12


Encrypt-Alg-List-NA

AttName: Encrypt-Alg-List-NA

LDAPName: | Encrypt-Alg-List-NA
Boot: | FALSE
Space: | ms
AttID: | 131202 (130, \x2A864886F71401028102)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8040
Heuristics: | 12


Encrypt-Alg-List-Other

AttName: Encrypt-Alg-List-Other

LDAPName: | Encrypt-Alg-List-Other
Boot: | FALSE
Space: | ms
AttID: | 131471 (399, \x2A864886F7140102830F)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8041
Heuristics: | 12


Encrypt-Alg-Selected-NA

AttName: Encrypt-Alg-Selected-NA

LDAPName: | Encrypt-Alg-Selected-NA
Boot: | FALSE
Space: | ms
AttID: | 131473 (401, \x2A864886F71401028311)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8043
Heuristics: | 12


Encrypt-Alg-Selected-Other

AttName: Encrypt-Alg-Selected-Other

LDAPName: | Encrypt-Alg-Selected-Other
Boot: | FALSE
Space: | ms
AttID: | 131469 (397, \x2A864886F7140102830D)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x803D
Heuristics: | 12


Expand-DLs-Locally

AttName: Expand-DLs-Locally

LDAPName: | Expand-DLs-Locally
Boot: | FALSE
Space: | ms
AttID: | 131273 (201, \x2A864886F71401028149)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80A4
Heuristics: | 12


Expiration-Time

AttName: Expiration-Time

LDAPName: | Expiration-Time
Boot: | FALSE
Space: | ms
AttID: | 131466 (394, \x2A864886F7140102830A)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8028
FastSearch: | 1
Heuristics: | 12


Export-Containers

AttName: Export-Containers

LDAPName: | Export-Containers
Boot: | FALSE
Space: | ms
AttID: | 131183 (111, \x2A864886F71401026F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80A5
Heuristics: | 12


Export-Custom-Recipients

AttName: Export-Custom-Recipients

LDAPName: | Export-Custom-Recipients
Boot: | FALSE
Space: | ms
AttID: | 131379 (307, \x2A864886F71401028233)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80A6
Heuristics: | 4


Extended-Chars-Allowed

AttName: Extended-Chars-Allowed

LDAPName: | Extended-Chars-Allowed
Boot: | TRUE
Space: | ms
AttID: | 131452 (380, \x2A864886F7140102827C)
SyntaxName: | boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80A7
Heuristics: | 12


Extension-Attribute-1

AttName: Extension-Attribute-1

LDAPName: | Extension-Attribute-1
Boot: | FALSE
Space: | ms
AttID: | 131495 (423, \x2A864886F71401028327)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x802D
Heuristics: | 20


Extension-Attribute-10

AttName: Extension-Attribute-10

LDAPName: | Extension-Attribute-10
Boot: | FALSE
Space: | ms
AttID: | 131504 (432, \x2A864886F71401028330)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8036
Heuristics: | 20


Extension-Attribute-11

AttName: Extension-Attribute-11

LDAPName: | Extension-Attribute-11
Boot: | FALSE
Space: | ms
AttID: | 131671 (599, \x2A864886F71401028457)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 2048
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C57
Heuristics: | 21


Extension-Attribute-12

AttName: Extension-Attribute-12

LDAPName: | Extension-Attribute-12
Boot: | FALSE
Space: | ms
AttID: | 131672 (600, \x2A864886F71401028458)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 2048
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C58
Heuristics: | 21


Extension-Attribute-13

AttName: Extension-Attribute-13

LDAPName: | Extension-Attribute-13
Boot: | FALSE
Space: | ms
AttID: | 131673 (601, \x2A864886F71401028459)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 2048
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C59
Heuristics: | 21


Extension-Attribute-14

AttName: Extension-Attribute-14

LDAPName: | Extension-Attribute-14
Boot: | FALSE
Space: | ms
AttID: | 131674 (602, \x2A864886F7140102845A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 2048
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C60
Heuristics: | 21


Extension-Attribute-15

AttName: Extension-Attribute-15

LDAPName: | Extension-Attribute-15
Boot: | FALSE
Space: | ms
AttID: | 131675 (603, \x2A864886F7140102845B)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 2048
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C61
Heuristics: | 21


Extension-Attribute-2

AttName: Extension-Attribute-2

LDAPName: | Extension-Attribute-2
Boot: | FALSE
Space: | ms
AttID: | 131496 (424, \x2A864886F71401028328)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x802E
Heuristics: | 20


Extension-Attribute-3

AttName: Extension-Attribute-3

LDAPName: | Extension-Attribute-3
Boot: | FALSE
Space: | ms
AttID: | 131497 (425, \x2A864886F71401028329)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x802F
Heuristics: | 20


Extension-Attribute-4

AttName: Extension-Attribute-4

LDAPName: | Extension-Attribute-4
Boot: | FALSE
Space: | ms
AttID: | 131498 (426, \x2A864886F7140102832A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8030
Heuristics: | 20


Extension-Attribute-5

AttName: Extension-Attribute-5

LDAPName: | Extension-Attribute-5
Boot: | FALSE
Space: | ms
AttID: | 131499 (427, \x2A864886F7140102832B)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8031
Heuristics: | 20


Extension-Attribute-6

AttName: Extension-Attribute-6

LDAPName: | Extension-Attribute-6
Boot: | FALSE
Space: | ms
AttID: | 131500 (428, \x2A864886F7140102832C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8032
Heuristics: | 20


Extension-Attribute-7

AttName: Extension-Attribute-7

LDAPName: | Extension-Attribute-7
Boot: | FALSE
Space: | ms
AttID: | 131501 (429, \x2A864886F7140102832D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8033
Heuristics: | 20


Extension-Attribute-8

AttName: Extension-Attribute-8

LDAPName: | Extension-Attribute-8
Boot: | FALSE
Space: | ms
AttID: | 131502 (430, \x2A864886F7140102832E)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8034
Heuristics: | 20


Extension-Attribute-9

AttName: Extension-Attribute-9

LDAPName: | Extension-Attribute-9
Boot: | FALSE
Space: | ms
AttID: | 131503 (431, \x2A864886F7140102832F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8035
Heuristics: | 20


Extension-Data

AttName: Extension-Data

LDAPName: | Extension-Data
Boot: | FALSE
Space: | ms
AttID: | 131300 (228, \x2A864886F71401028164)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | TRUE
Acl: | User
MapiID: | 0x80A8
Heuristics: | 12


Extension-Name

AttName: Extension-Name

LDAPName: | Extension-Name
Boot: | FALSE
Space: | ms
AttID: | 131299 (227, \x2A864886F71401028163)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 255
Multi: | TRUE
Acl: | User
MapiID: | 0x80A9
Heuristics: | 4


Extension-Name-Inherited

AttName: Extension-Name-Inherited

LDAPName: | Extension-Name-Inherited
Boot: | FALSE
Space: | ms
AttID: | 131169 (97, \x2A864886F714010261)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 255
Multi: | TRUE
Acl: | User
MapiID: | 0x80AA
Heuristics: | 12


Facsimile-Telephone-Number

AttName: Facsimile-Telephone-Number

LDAPName: | Facsimile-Telephone-Number
Boot: | FALSE
Space: | x500
AttID: | 23 (23, \x550417)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | User
MapiID: | 0x80AB
Heuristics: | 12


File-Version

AttName: File-Version

LDAPName: | File-Version
Boot: | FALSE
Space: | ms
AttID: | 131250 (178, \x2A864886F71401028132)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 8
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80AC
Heuristics: | 4


Filter-Local-Addresses

AttName: Filter-Local-Addresses

LDAPName: | Filter-Local-Addresses
Boot: | FALSE
Space: | ms
AttID: | 131116 (44, \x2A864886F71401022C)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80AD
Heuristics: | 12


Folder-Pathname

AttName: Folder-Pathname

LDAPName: | Folder-Pathname
Boot: | FALSE
Space: | ms
AttID: | 131409 (337, \x2A864886F71401028251)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8004
Heuristics: | 12


Folders-Container

AttName: Folders-Container

LDAPName: | Folders-Container
Boot: | FALSE
Space: | ms
AttID: | 131307 (235, \x2A864886F7140102816B)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80AE
Heuristics: | 12


Foreign-DSAs

AttName: Foreign-DSAs

LDAPName: | Foreign-DSAs
Boot: | FALSE
Space: | ms
AttID: | 131140 (68, \x2A864886F714010244)
SyntaxName: | Object(Access-Point)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
Heuristics: | 12


Form-Data

AttName: Form-Data

LDAPName: | Form-Data
Boot: | FALSE
Space: | ms
AttID: | 131679 (607, \x2A864886F7140102845F)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C65
Heuristics: | 13


Forwarding-Address

AttName: Forwarding-Address

LDAPName: | forwardingAddress
Boot: | FALSE
Space: | ms
AttID: | 131678 (606, \x2A864886F7140102845E)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C64
Heuristics: | 5


Garbage-Coll-Period

AttName: Garbage-Coll-Period

LDAPName: | Garbage-Coll-Period
Boot: | FALSE
Space: | ms
AttID: | 131373 (301, \x2A864886F7140102822D)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80AF
Heuristics: | 12


Gateway-Local-Cred

AttName: Gateway-Local-Cred

LDAPName: | Gateway-Local-Cred
Boot: | FALSE
Space: | ms
AttID: | 131109 (37, \x2A864886F714010225)
SyntaxName: | String(IA5)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x80B0
Heuristics: | 12


Gateway-Local-Desig

AttName: Gateway-Local-Desig

LDAPName: | Gateway-Local-Desig
Boot: | FALSE
Space: | ms
AttID: | 131101 (29, \x2A864886F71401021D)
SyntaxName: | String(IA5)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | User
MapiID: | 0x80B1
Heuristics: | 12


Gateway-Proxy

AttName: Gateway-Proxy

LDAPName: | Gateway-Proxy
Boot: | FALSE
Space: | ms
AttID: | 131374 (302, \x2A864886F7140102822E)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1123
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80B2
Heuristics: | 12


Gateway-Routing-Tree

AttName: Gateway-Routing-Tree

LDAPName: | Gateway-Routing-Tree
Boot: | FALSE
Space: | ms
AttID: | 131239 (167, \x2A864886F71401028127)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80B3
Heuristics: | 12


Generation-Qualifier

AttName: Generation-Qualifier

LDAPName: | generationQualifier
Boot: | FALSE
Space: | ms
AttID: | 131667 (595, \x2A864886F71401028453)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C53
Heuristics: | 13


Given-Name

AttName: Given-Name

LDAPName: | givenName
Boot: | FALSE
Space: | ms
AttID: | 131113 (41, \x2A864886F714010229)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A06
FastSearch: | 1
Heuristics: | 18


Governs-ID

AttName: Governs-ID

LDAPName: | Governs-ID
Boot: | TRUE
Space: | ms
AttID: | 131094 (22, \x2A864886F714010216)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
Object ID Type: | CLASSID
Heuristics: | 4


Group-By-Attr-1

AttName: Group-By-Attr-1

LDAPName: | Group-By-Attr-1
Boot: | FALSE
Space: | ms
AttID: | 131601 (529, \x2A864886F71401028411)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B7
Heuristics: | 12


Group-By-Attr-2

AttName: Group-By-Attr-2

LDAPName: | Group-By-Attr-2
Boot: | FALSE
Space: | ms
AttID: | 131602 (530, \x2A864886F71401028412)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B8
Heuristics: | 12


Group-By-Attr-3

AttName: Group-By-Attr-3

LDAPName: | Group-By-Attr-3
Boot: | FALSE
Space: | ms
AttID: | 131603 (531, \x2A864886F71401028413)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B9
Heuristics: | 12


Group-By-Attr-4

AttName: Group-By-Attr-4

LDAPName: | Group-By-Attr-4
Boot: | FALSE
Space: | ms
AttID: | 131604 (532, \x2A864886F71401028414)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81BA
Heuristics: | 12


Group-By-Attr-Value-DN

AttName: Group-By-Attr-Value-DN

LDAPName: | Group-By-Attr-Value-DN
Boot: | FALSE
Space: | ms
AttID: | 131620 (548, \x2A864886F71401028424)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C1A
Heuristics: | 12


Group-By-Attr-Value-Str

AttName: Group-By-Attr-Value-Str

LDAPName: | Group-By-Attr-Value-Str
Boot: | FALSE
Space: | ms
AttID: | 131619 (547, \x2A864886F71401028423)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C19
Heuristics: | 12


GWART-Last-Modified

AttName: GWART-Last-Modified

LDAPName: | GWART-Last-Modified
Boot: | FALSE
Space: | ms
AttID: | 131332 (260, \x2A864886F71401028204)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80B4
Heuristics: | 12


Has-Full-Replica-NCs

AttName: Has-Full-Replica-NCs

LDAPName: | Has-Full-Replica-NCs
Boot: | TRUE
Space: | ms
AttID: | 131087 (15, \x2A864886F71401020F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80B5
Heuristics: | 12


Has-Master-NCs

AttName: Has-Master-NCs

LDAPName: | Has-Master-NCs
Boot: | TRUE
Space: | ms
AttID: | 131086 (14, \x2A864886F71401020E)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80B6
Heuristics: | 12


Help-Data16

AttName: Help-Data16

LDAPName: | Help-Data16
Boot: | FALSE
Space: | ms
AttID: | 131474 (402, \x2A864886F71401028312)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x803A
Heuristics: | 12


Help-Data32

AttName: Help-Data32

LDAPName: | Help-Data32
Boot: | FALSE
Space: | ms
AttID: | 131081 (9, \x2A864886F714010209)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8010
Heuristics: | 12


Help-File-Name

AttName: Help-File-Name

LDAPName: | Help-File-Name
Boot: | FALSE
Space: | ms
AttID: | 131399 (327, \x2A864886F71401028247)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 13
Multi: | FALSE
Acl: | Admin
MapiID: | 0x803B
Heuristics: | 12


Heuristics

AttName: Heuristics

LDAPName: | Heuristics
Boot: | TRUE
Space: | ms
AttID: | 131524 (452, \x2A864886F71401028344)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80B7
Heuristics: | 12


Hide-DL-Membership

AttName: Hide-DL-Membership

LDAPName: | Hide-DL-Membership
Boot: | FALSE
Space: | ms
AttID: | 131369 (297, \x2A864886F71401028229)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80B8
Heuristics: | 20


Hide-From-Address-Book

AttName: Hide-From-Address-Book

LDAPName: | Hide-From-Address-Book
Boot: | TRUE
Space: | ms
AttID: | 131241 (169, \x2A864886F71401028129)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80B9
FastSearch: | 1
Heuristics: | 20


Home-MDB

AttName: Home-MDB

LDAPName: | Home-MDB
Boot: | FALSE
Space: | ms
AttID: | 131316 (244, \x2A864886F71401028174)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
LinkID: | Link-16
Acl: | Admin
MapiID: | 0x8006
Heuristics: | 12


Home-MDB-BL

AttName: Home-MDB-BL

LDAPName: | Home-MDB-BL
Boot: | FALSE
Space: | ms
AttID: | 131465 (393, \x2A864886F71401028309)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-16
Acl: | System
MapiID: | 0x8014
Heuristics: | 12


Home-MTA

AttName: Home-MTA

LDAPName: | Home-MTA
Boot: | FALSE
Space: | ms
AttID: | 131243 (171, \x2A864886F7140102812B)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8007
Heuristics: | 4


Home-Public-Server

AttName: Home-Public-Server

LDAPName: | Home-Public-Server
Boot: | FALSE
Space: | ms
AttID: | 131513 (441, \x2A864886F71401028339)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x803F
Heuristics: | 12


House-Identifier

AttName: House-Identifier

LDAPName: | houseIdentifier
Boot: | FALSE
Space: | ms
AttID: | 131668 (596, \x2A864886F71401028454)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C54
Heuristics: | 13


HTTP-Pub-AB-Attributes

AttName: HTTP-Pub-AB-Attributes

LDAPName: | HTTP-Pub-AB-Attributes
Boot: | FALSE
Space: | ms
AttID: | 131588 (516, \x2A864886F71401028404)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | Admin
MapiID: | 0x81A9
Heuristics: | 13


HTTP-Pub-GAL

AttName: HTTP-Pub-GAL

LDAPName: | HTTP-Pub-GAL
Boot: | FALSE
Space: | ms
AttID: | 131574 (502, \x2A864886F71401028376)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x819B
Heuristics: | 5


HTTP-Pub-GAL-Limit

AttName: HTTP-Pub-GAL-Limit

LDAPName: | HTTP-Pub-GAL-Limit
Boot: | FALSE
Space: | ms
AttID: | 131575 (503, \x2A864886F71401028377)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x819C
Heuristics: | 13


HTTP-Pub-PF

AttName: HTTP-Pub-PF

LDAPName: | HTTP-Pub-PF
Boot: | FALSE
Space: | ms
AttID: | 131577 (505, \x2A864886F71401028379)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 1024
Multi: | TRUE
Acl: | Admin
MapiID: | 0x819E
Heuristics: | 13


HTTP-Servers

AttName: HTTP-Servers

LDAPName: | HTTP-Servers
Boot: | FALSE
Space: | ms
AttID: | 131589 (517, \x2A864886F71401028405)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | TRUE
Acl: | Admin
MapiID: | 0x81AB
Heuristics: | 13


Import-Container

AttName: Import-Container

LDAPName: | Import-Container
Boot: | FALSE
Space: | ms
AttID: | 131182 (110, \x2A864886F71401026E)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80BA
Heuristics: | 12


Import-Sensitivity

AttName: Import-Sensitivity

LDAPName: | Import-Sensitivity
Boot: | FALSE
Space: | ms
AttID: | 131455 (383, \x2A864886F7140102827F)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80BB
Heuristics: | 12


Imported-From

AttName: Imported-From

LDAPName: | Imported-From
Boot: | FALSE
Space: | ms
AttID: | 131335 (263, \x2A864886F71401028207)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | User
MapiID: | 0x8042
Heuristics: | 12


Inbound-Accept-All

AttName: Inbound-Accept-All

LDAPName: | Inbound-Accept-All
Boot: | FALSE
Space: | ms
AttID: | 131627 (555, \x2A864886F7140102842B)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C20
Heuristics: | 13


Inbound-DN

AttName: Inbound-DN

LDAPName: | Inbound-DN
Boot: | FALSE
Space: | ms
AttID: | 131625 (553, \x2A864886F71401028429)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C1E
Heuristics: | 13


Inbound-Host

AttName: Inbound-Host

LDAPName: | Inbound-Host
Boot: | FALSE
Space: | ms
AttID: | 131561 (489, \x2A864886F71401028369)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 512
Multi: | TRUE
Acl: | Admin
MapiID: | 0x818E
Heuristics: | 13


Inbound-Newsfeed

AttName: Inbound-Newsfeed

LDAPName: | Inbound-Newsfeed
Boot: | FALSE
Space: | ms
AttID: | 131566 (494, \x2A864886F7140102836E)
SyntaxName: | String(Unicode)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8193
Heuristics: | 13


Inbound-Newsfeed-Type

AttName: Inbound-Newsfeed-Type

LDAPName: | Inbound-Newsfeed-Type
Boot: | FALSE
Space: | ms
AttID: | 131626 (554, \x2A864886F7140102842A)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C1F
Heuristics: | 13


Inbound-Sites

AttName: Inbound-Sites

LDAPName: | Inbound-Sites
Boot: | FALSE
Space: | ms
AttID: | 131143 (71, \x2A864886F714010247)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80BC
Heuristics: | 12


Incoming-Msg-Size-Limit

AttName: Incoming-Msg-Size-Limit

LDAPName: | Incoming-Msg-Size-Limit
Boot: | FALSE
Space: | ms
AttID: | 131563 (491, \x2A864886F7140102836B)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8190
Heuristics: | 13


Incoming-Password

AttName: Incoming-Password

LDAPName: | Incoming-Password
Boot: | FALSE
Space: | ms
AttID: | 131593 (521, \x2A864886F71401028409)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81AF
Heuristics: | 13


Initials

AttName: Initials

LDAPName: | initials
Boot: | FALSE
Space: | ms
AttID: | 131470 (398, \x2A864886F7140102830E)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 6
Multi: | FALSE
Acl: | User
MapiID: | 0x3A0A
Heuristics: | 18


INSAdmin

AttName: INSAdmin

LDAPName: | INSAdmin
Boot: | FALSE
Space: | ms
AttID: | 131615 (543, \x2A864886F7140102841F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81C5
Heuristics: | 13


Instance-Type

AttName: Instance-Type

LDAPName: | Instance-Type
Boot: | TRUE
Space: | ms
AttID: | 131073 (1, \x2A864886F714010201)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x80BD
Heuristics: | 12


International-ISDN-Number

AttName: International-ISDN-Number

LDAPName: | internationalISDNNumber
Boot: | FALSE
Space: | x500
AttID: | 25 (25, \x550419)
SyntaxName: | String(Numeric)
MinLen: | 1
MaxLen: | 16
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80BE
Heuristics: | 18


Internet-Encoding

AttName: Internet-Encoding

LDAPName: | Internet-Encoding
Boot: | FALSE
Space: | ms
AttID: | 131623 (551, \x2A864886F71401028427)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A71
Heuristics: | 13


Invocation-Id

AttName: Invocation-Id

LDAPName: | Invocation-Id
Boot: | TRUE
Space: | ms
AttID: | 131187 (115, \x2A864886F714010273)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80BF
Heuristics: | 12


Is-Deleted

AttName: Is-Deleted

LDAPName: | Is-Deleted
Boot: | TRUE
Space: | ms
AttID: | 131120 (48, \x2A864886F714010230)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x80C0
Heuristics: | 12


Is-Member-Of-DL

AttName: Is-Member-Of-DL

LDAPName: | memberOf
Boot: | FALSE
Space: | ms
AttID: | 131174 (102, \x2A864886F714010266)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-1
Acl: | System
MapiID: | 0x8008
Heuristics: | 20


Is-Single-Valued

AttName: Is-Single-Valued

LDAPName: | Is-Single-Valued
Boot: | TRUE
Space: | ms
AttID: | 131105 (33, \x2A864886F714010221)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80C1
Heuristics: | 4


KCC-Status

AttName: KCC-Status

LDAPName: | KCC-Status
Boot: | FALSE
Space: | ms
AttID: | 131309 (237, \x2A864886F7140102816D)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80C2
Heuristics: | 12


KM-Server

AttName: KM-Server

LDAPName: | KM-Server
Boot: | FALSE
Space: | ms
AttID: | 131512 (440, \x2A864886F71401028338)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x800D
Heuristics: | 12


Knowledge-Information

AttName: Knowledge-Information

LDAPName: | knowledgeInformation
Boot: | FALSE
Space: | x500
AttID: | 2 (2, \x550402)
SyntaxName: | String(Teletex)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80C3
Heuristics: | 12


LabeledURI

AttName: LabeledURI

LDAPName: | LabeledURI
Boot: | FALSE
Space: | ms
AttID: | 131665 (593, \x2A864886F71401028451)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | User
MapiID: | 0x8C51
Heuristics: | 5


Language

AttName: Language

LDAPName: | clientLanguage
Boot: | FALSE
Space: | ms
AttID: | 131539 (467, \x2A864886F71401028353)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8178
Heuristics: | 12


Language-ISO639

AttName: Language-ISO639

LDAPName: | language
Boot: | FALSE
Space: | ms
AttID: | 131688 (616, \x2A864886F71401028468)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x8C6C
Heuristics: | 3


LDAP-Display-Name

AttName: LDAP-Display-Name

LDAPName: | systemAttribute1
Boot: | FALSE
Space: | ms
AttID: | 131532 (460, \x2A864886F7140102834C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8171
Heuristics: | 12


LDAP-Search-Cfg

AttName: LDAP-Search-Cfg

LDAPName: | LDAP-Search-Cfg
Boot: | FALSE
Space: | ms
AttID: | 131624 (552, \x2A864886F71401028428)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C1D
Heuristics: | 13


Line-Wrap

AttName: Line-Wrap

LDAPName: | Line-Wrap
Boot: | FALSE
Space: | ms
AttID: | 131521 (449, \x2A864886F71401028341)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80C4
Heuristics: | 12


Link-ID

AttName: Link-ID

LDAPName: | Link-ID
Boot: | TRUE
Space: | ms
AttID: | 131122 (50, \x2A864886F714010232)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80C5
Heuristics: | 12


List-Public-Folders

AttName: List-Public-Folders

LDAPName: | List-Public-Folders
Boot: | FALSE
Space: | ms
AttID: | 131664 (592, \x2A864886F71401028450)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C50
Heuristics: | 13


Local-Bridge-Head

AttName: Local-Bridge-Head

LDAPName: | Local-Bridge-Head
Boot: | FALSE
Space: | ms
AttID: | 131383 (311, \x2A864886F71401028237)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80C6
Heuristics: | 12


Local-Bridge-Head-Address

AttName: Local-Bridge-Head-Address

LDAPName: | Local-Bridge-Head-Address
Boot: | FALSE
Space: | ms
AttID: | 131297 (225, \x2A864886F71401028161)
SyntaxName: | String(Teletex)
MinLen: | 0
MaxLen: | 1118
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80C7
Heuristics: | 12


Local-Initial-Turn

AttName: Local-Initial-Turn

LDAPName: | Local-Initial-Turn
Boot: | FALSE
Space: | ms
AttID: | 131111 (39, \x2A864886F714010227)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80C8
Heuristics: | 12


Local-Scope

AttName: Local-Scope

LDAPName: | Local-Scope
Boot: | FALSE
Space: | ms
AttID: | 131089 (17, \x2A864886F714010211)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
MapiID: | 0x80C9
Heuristics: | 12


Locality-Name

AttName: Locality-Name

LDAPName: | l
Boot: | FALSE
Space: | x500
AttID: | 7 (7, \x550407)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | User
MapiID: | 0x3A27
FastSearch: | 1
Heuristics: | 18


Log-Filename

AttName: Log-Filename

LDAPName: | Log-Filename
Boot: | FALSE
Space: | ms
AttID: | 131264 (192, \x2A864886F71401028140)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | User
MapiID: | 0x80CA
Heuristics: | 12


Log-Rollover-Interval

AttName: Log-Rollover-Interval

LDAPName: | Log-Rollover-Interval
Boot: | FALSE
Space: | ms
AttID: | 131420 (348, \x2A864886F7140102825C)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80CB
Heuristics: | 12


Mail-Drop

AttName: Mail-Drop

LDAPName: | mailDrop
Boot: | FALSE
Space: | ms
AttID: | 131677 (605, \x2A864886F7140102845D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C63
Heuristics: | 5


Mail-nickname

AttName: Mail-nickname

LDAPName: | uid
Boot: | FALSE
Space: | ms
AttID: | 131519 (447, \x2A864886F7140102833F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A00
FastSearch: | 2
Heuristics: | 18


Maintain-AutoReply-History

AttName: Maintain-AutoReply-History

LDAPName: | Maintain-AutoReply-History
Boot: | FALSE
Space: | ms
AttID: | 131281 (209, \x2A864886F71401028151)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80CC
Heuristics: | 12


Manager

AttName: Manager

LDAPName: | manager
Boot: | FALSE
Space: | ms
AttID: | 131407 (335, \x2A864886F7140102824F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
LinkID: | Link-21
Acl: | Admin
MapiID: | 0x8005
Heuristics: | 18


MAPI-Display-Type

AttName: MAPI-Display-Type

LDAPName: | MAPI-Display-Type
Boot: | TRUE
Space: | ms
AttID: | 131127 (55, \x2A864886F714010237)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80CD
Heuristics: | 12


MAPI-ID

AttName: MAPI-ID

LDAPName: | MAPI-ID
Boot: | TRUE
Space: | ms
AttID: | 131121 (49, \x2A864886F714010231)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80CE
Heuristics: | 12


MAPI-Recipient

AttName: MAPI-Recipient

LDAPName: | MAPI-Recipient
Boot: | FALSE
Space: | ms
AttID: | 131443 (371, \x2A864886F71401028273)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A40
Heuristics: | 18


Master-DSA

AttName: Master-DSA

LDAPName: | Master-DSA
Boot: | TRUE
Space: | ms
AttID: | 131078 (6, \x2A864886F714010206)
SyntaxName: | Object(Access-Point)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
Heuristics: | 12


Maximum-Object-ID

AttName: Maximum-Object-ID

LDAPName: | Maximum-Object-ID
Boot: | FALSE
Space: | ms
AttID: | 131530 (458, \x2A864886F7140102834A)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 22
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8169
Heuristics: | 12


May-Contain

AttName: May-Contain

LDAPName: | May-Contain
Boot: | TRUE
Space: | ms
AttID: | 131097 (25, \x2A864886F714010219)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Object ID Type: | ATTID
Heuristics: | 4


MDB-Backoff-Interval

AttName: MDB-Backoff-Interval

LDAPName: | MDB-Backoff-Interval
Boot: | FALSE
Space: | ms
AttID: | 131144 (72, \x2A864886F714010248)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80CF
Heuristics: | 12


MDB-Msg-Time-Out-Period

AttName: MDB-Msg-Time-Out-Period

LDAPName: | MDB-Msg-Time-Out-Period
Boot: | FALSE
Space: | ms
AttID: | 131136 (64, \x2A864886F714010240)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D0
Heuristics: | 12


MDB-Over-Quota-Limit

AttName: MDB-Over-Quota-Limit

LDAPName: | MDB-Over-Quota-Limit
Boot: | FALSE
Space: | ms
AttID: | 131344 (272, \x2A864886F71401028210)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D1
Heuristics: | 12


MDB-Storage-Quota

AttName: MDB-Storage-Quota

LDAPName: | MDB-Storage-Quota
Boot: | FALSE
Space: | ms
AttID: | 131338 (266, \x2A864886F7140102820A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D2
Heuristics: | 12


MDB-Unread-Limit

AttName: MDB-Unread-Limit

LDAPName: | MDB-Unread-Limit
Boot: | FALSE
Space: | ms
AttID: | 131141 (69, \x2A864886F714010245)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D3
Heuristics: | 12


MDB-Use-Defaults

AttName: MDB-Use-Defaults

LDAPName: | MDB-Use-Defaults
Boot: | FALSE
Space: | ms
AttID: | 131381 (309, \x2A864886F71401028235)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D4
Heuristics: | 12


Member

AttName: Member

LDAPName: | member
Boot: | FALSE
Space: | x500
AttID: | 31 (31, \x55041F)
SyntaxName: | Object(OR-Name)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-1
Acl: | User
MapiID: | 0x8009
Heuristics: | 20


Message-Tracking-Enabled

AttName: Message-Tracking-Enabled

LDAPName: | Message-Tracking-Enabled
Boot: | FALSE
Space: | ms
AttID: | 131525 (453, \x2A864886F71401028345)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D5
Heuristics: | 12


MIME-Types

AttName: MIME-Types

LDAPName: | MIME-Types
Boot: | FALSE
Space: | ms
AttID: | 131622 (550, \x2A864886F71401028426)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 10240
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C1C
Heuristics: | 13


Moderated

AttName: Moderated

LDAPName: | Moderated
Boot: | FALSE
Space: | ms
AttID: | 131590 (518, \x2A864886F71401028406)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81AC
Heuristics: | 13


Moderator

AttName: Moderator

LDAPName: | Moderator
Boot: | FALSE
Space: | ms
AttID: | 131572 (500, \x2A864886F71401028374)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8199
Heuristics: | 13


Monitor-Clock

AttName: Monitor-Clock

LDAPName: | Monitor-Clock
Boot: | FALSE
Space: | ms
AttID: | 131235 (163, \x2A864886F71401028123)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D6
Heuristics: | 12


Monitor-Servers

AttName: Monitor-Servers

LDAPName: | Monitor-Servers
Boot: | FALSE
Space: | ms
AttID: | 131228 (156, \x2A864886F7140102811C)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D7
Heuristics: | 12


Monitor-Services

AttName: Monitor-Services

LDAPName: | Monitor-Services
Boot: | FALSE
Space: | ms
AttID: | 131232 (160, \x2A864886F71401028120)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80D8
Heuristics: | 12


Monitored-Configurations

AttName: Monitored-Configurations

LDAPName: | Monitored-Configurations
Boot: | FALSE
Space: | ms
AttID: | 131270 (198, \x2A864886F71401028146)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80D9
Heuristics: | 12


Monitored-Servers

AttName: Monitored-Servers

LDAPName: | Monitored-Servers
Boot: | FALSE
Space: | ms
AttID: | 131251 (179, \x2A864886F71401028133)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80DA
Heuristics: | 12


Monitored-Services

AttName: Monitored-Services

LDAPName: | Monitored-Services
Boot: | FALSE
Space: | ms
AttID: | 131271 (199, \x2A864886F71401028147)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80DB
Heuristics: | 12


Monitoring-Alert-Delay

AttName: Monitoring-Alert-Delay

LDAPName: | Monitoring-Alert-Delay
Boot: | FALSE
Space: | ms
AttID: | 131230 (158, \x2A864886F7140102811E)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80DC
Heuristics: | 12


Monitoring-Alert-Units

AttName: Monitoring-Alert-Units

LDAPName: | Monitoring-Alert-Units
Boot: | FALSE
Space: | ms
AttID: | 131129 (57, \x2A864886F714010239)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80DD
Heuristics: | 12


Monitoring-Availability-Style

AttName: Monitoring-Availability-Style

LDAPName: | Monitoring-Availability-Style
Boot: | FALSE
Space: | ms
AttID: | 131522 (450, \x2A864886F71401028342)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80DE
Heuristics: | 12


Monitoring-Availability-Window

AttName: Monitoring-Availability-Window

LDAPName: | Monitoring-Availability-Window
Boot: | FALSE
Space: | ms
AttID: | 131272 (200, \x2A864886F71401028148)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 84
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80DF
Heuristics: | 12


Monitoring-Cached-Via-Mail

AttName: Monitoring-Cached-Via-Mail

LDAPName: | Monitoring-Cached-Via-Mail
Boot: | FALSE
Space: | ms
AttID: | 131268 (196, \x2A864886F71401028144)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80E0
Heuristics: | 12


Monitoring-Cached-Via-RPC

AttName: Monitoring-Cached-Via-RPC

LDAPName: | Monitoring-Cached-Via-RPC
Boot: | FALSE
Space: | ms
AttID: | 131269 (197, \x2A864886F71401028145)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80E1
Heuristics: | 12


Monitoring-Escalation-Procedure

AttName: Monitoring-Escalation-Procedure

LDAPName: | Monitoring-Escalation-Procedure
Boot: | FALSE
Space: | ms
AttID: | 131260 (188, \x2A864886F7140102813C)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 1064
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80E2
Heuristics: | 12


Monitoring-Hotsite-Poll-Interval

AttName: Monitoring-Hotsite-Poll-Interval

LDAPName: | Monitoring-Hotsite-Poll-Interval
Boot: | FALSE
Space: | ms
AttID: | 131258 (186, \x2A864886F7140102813A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80E3
Heuristics: | 12


Monitoring-Hotsite-Poll-Units

AttName: Monitoring-Hotsite-Poll-Units

LDAPName: | Monitoring-Hotsite-Poll-Units
Boot: | FALSE
Space: | ms
AttID: | 131159 (87, \x2A864886F714010257)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80E4
Heuristics: | 12


Monitoring-Mail-Update-Interval

AttName: Monitoring-Mail-Update-Interval

LDAPName: | Monitoring-Mail-Update-Interval
Boot: | FALSE
Space: | ms
AttID: | 131267 (195, \x2A864886F71401028143)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80E5
Heuristics: | 12


Monitoring-Mail-Update-Units

AttName: Monitoring-Mail-Update-Units

LDAPName: | Monitoring-Mail-Update-Units
Boot: | FALSE
Space: | ms
AttID: | 131165 (93, \x2A864886F71401025D)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80E6
Heuristics: | 12


Monitoring-Normal-Poll-Interval

AttName: Monitoring-Normal-Poll-Interval

LDAPName: | Monitoring-Normal-Poll-Interval
Boot: | FALSE
Space: | ms
AttID: | 131259 (187, \x2A864886F7140102813B)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80E7
Heuristics: | 12


Monitoring-Normal-Poll-Units

AttName: Monitoring-Normal-Poll-Units

LDAPName: | Monitoring-Normal-Poll-Units
Boot: | FALSE
Space: | ms
AttID: | 131160 (88, \x2A864886F714010258)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80E8
Heuristics: | 12


Monitoring-Recipients

AttName: Monitoring-Recipients

LDAPName: | Monitoring-Recipients
Boot: | FALSE
Space: | ms
AttID: | 131231 (159, \x2A864886F7140102811F)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80E9
Heuristics: | 12


Monitoring-Recipients-NDR

AttName: Monitoring-Recipients-NDR

LDAPName: | Monitoring-Recipients-NDR
Boot: | FALSE
Space: | ms
AttID: | 131459 (387, \x2A864886F71401028303)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80EA
Heuristics: | 12


Monitoring-RPC-Update-Interval

AttName: Monitoring-RPC-Update-Interval

LDAPName: | Monitoring-RPC-Update-Interval
Boot: | FALSE
Space: | ms
AttID: | 131164 (92, \x2A864886F71401025C)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80EB
Heuristics: | 12


Monitoring-RPC-Update-Units

AttName: Monitoring-RPC-Update-Units

LDAPName: | Monitoring-RPC-Update-Units
Boot: | FALSE
Space: | ms
AttID: | 131161 (89, \x2A864886F714010259)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80EC
Heuristics: | 12


Monitoring-Warning-Delay

AttName: Monitoring-Warning-Delay

LDAPName: | Monitoring-Warning-Delay
Boot: | FALSE
Space: | ms
AttID: | 131229 (157, \x2A864886F7140102811D)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80ED
Heuristics: | 12


Monitoring-Warning-Units

AttName: Monitoring-Warning-Units

LDAPName: | Monitoring-Warning-Units
Boot: | FALSE
Space: | ms
AttID: | 131128 (56, \x2A864886F714010238)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80EE
Heuristics: | 12


MTA-Local-Cred

AttName: MTA-Local-Cred

LDAPName: | MTA-Local-Cred
Boot: | FALSE
Space: | ms
AttID: | 131342 (270, \x2A864886F7140102820E)
SyntaxName: | String(IA5)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x80EF
Heuristics: | 12


MTA-Local-Desig

AttName: MTA-Local-Desig

LDAPName: | MTA-Local-Desig
Boot: | FALSE
Space: | ms
AttID: | 131343 (271, \x2A864886F7140102820F)
SyntaxName: | String(IA5)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | User
MapiID: | 0x80F0
Heuristics: | 4


Must-Contain

AttName: Must-Contain

LDAPName: | Must-Contain
Boot: | TRUE
Space: | ms
AttID: | 131096 (24, \x2A864886F714010218)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Object ID Type: | ATTID
Heuristics: | 4


N-Address

AttName: N-Address

LDAPName: | N-Address
Boot: | FALSE
Space: | ms
AttID: | 131354 (282, \x2A864886F7140102821A)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 50
Multi: | FALSE
Acl: | User
MapiID: | 0x80F1
Heuristics: | 12


N-Address-Type

AttName: N-Address-Type

LDAPName: | N-Address-Type
Boot: | FALSE
Space: | ms
AttID: | 131294 (222, \x2A864886F7140102815E)
SyntaxName: | Enumeration
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80F2
Heuristics: | 12


Network-Address

AttName: Network-Address

LDAPName: | Network-Address
Boot: | FALSE
Space: | ms
AttID: | 131531 (459, \x2A864886F7140102834B)
SyntaxName: | String(Teletex)
MinLen: | 0
MaxLen: | 256
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8170
Heuristics: | 12


Newsfeed-Type

AttName: Newsfeed-Type

LDAPName: | Newsfeed-Type
Boot: | FALSE
Space: | ms
AttID: | 131567 (495, \x2A864886F7140102836F)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8194
Heuristics: | 5


Newsgroup

AttName: Newsgroup

LDAPName: | Newsgroup
Boot: | FALSE
Space: | ms
AttID: | 131571 (499, \x2A864886F71401028373)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8198
Heuristics: | 13


Newsgroup-List

AttName: Newsgroup-List

LDAPName: | Newsgroup-List
Boot: | FALSE
Space: | ms
AttID: | 131569 (497, \x2A864886F71401028371)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8196
Heuristics: | 13


NNTP-Character-Set

AttName: NNTP-Character-Set

LDAPName: | NNTP-Character-Set
Boot: | FALSE
Space: | ms
AttID: | 131544 (472, \x2A864886F71401028358)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x817D
Heuristics: | 12


NNTP-Content-Format

AttName: NNTP-Content-Format

LDAPName: | NNTP-Content-Format
Boot: | FALSE
Space: | ms
AttID: | 131537 (465, \x2A864886F71401028351)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8176
Heuristics: | 12


NNTP-Distributions

AttName: NNTP-Distributions

LDAPName: | NNTP-Distributions
Boot: | FALSE
Space: | ms
AttID: | 131570 (498, \x2A864886F71401028372)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8197
Heuristics: | 13


NNTP-Distributions-Flag

AttName: NNTP-Distributions-Flag

LDAPName: | NNTP-Distributions-Flag
Boot: | FALSE
Space: | ms
AttID: | 131583 (511, \x2A864886F7140102837F)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81A4
Heuristics: | 13


NNTP-Newsfeeds

AttName: NNTP-Newsfeeds

LDAPName: | NNTP-Newsfeeds
Boot: | FALSE
Space: | ms
AttID: | 131585 (513, \x2A864886F71401028401)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-23
Acl: | Admin
MapiID: | 0x81A6
Heuristics: | 13


NT-Machine-Name

AttName: NT-Machine-Name

LDAPName: | NT-Machine-Name
Boot: | FALSE
Space: | ms
AttID: | 131526 (454, \x2A864886F71401028346)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 15
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80F3
Heuristics: | 12


NT-Security-Descriptor

AttName: NT-Security-Descriptor

LDAPName: | NT-Security-Descriptor
Boot: | TRUE
Space: | ms
AttID: | 131353 (281, \x2A864886F71401028219)
SyntaxName: | String(Octet)
MinLen: | 0
MaxLen: | 4096
Multi: | FALSE
MapiID: | 0x8013
Heuristics: | 12


Num-Of-Open-Retries

AttName: Num-Of-Open-Retries

LDAPName: | Num-Of-Open-Retries
Boot: | FALSE
Space: | ms
AttID: | 131220 (148, \x2A864886F71401028114)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80F4
Heuristics: | 12


Num-Of-Transfer-Retries

AttName: Num-Of-Transfer-Retries

LDAPName: | Num-Of-Transfer-Retries
Boot: | FALSE
Space: | ms
AttID: | 131206 (134, \x2A864886F71401028106)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80F5
Heuristics: | 12


Obj-Dist-Name

AttName: Obj-Dist-Name

LDAPName: | distinguishedName
Boot: | TRUE
Space: | ms
AttID: | 131123 (51, \x2A864886F714010233)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x803C
Heuristics: | 2


Obj-View-Containers

AttName: Obj-View-Containers

LDAPName: | Obj-View-Containers
Boot: | FALSE
Space: | ms
AttID: | 131617 (545, \x2A864886F71401028421)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
MapiID: | 0x81C7
Heuristics: | 13


Object-Class

AttName: Object-Class

LDAPName: | objectClass
Boot: | TRUE
Space: | x500
AttID: | 0 (0, \x550400)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
Object ID Type: | CLASSID
Heuristics: | 2


Object-Class-Category

AttName: Object-Class-Category

LDAPName: | Object-Class-Category
Boot: | TRUE
Space: | ms
AttID: | 131442 (370, \x2A864886F71401028272)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80F6
Heuristics: | 4


Object-Version

AttName: Object-Version

LDAPName: | Object-Version
Boot: | TRUE
Space: | ms
AttID: | 131148 (76, \x2A864886F71401024C)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x80F7
Heuristics: | 12


Off-Line-AB-Containers

AttName: Off-Line-AB-Containers

LDAPName: | Off-Line-AB-Containers
Boot: | FALSE
Space: | ms
AttID: | 131463 (391, \x2A864886F71401028307)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x80F8
Heuristics: | 12


Off-Line-AB-Schedule

AttName: Off-Line-AB-Schedule

LDAPName: | Off-Line-AB-Schedule
Boot: | FALSE
Space: | ms
AttID: | 131461 (389, \x2A864886F71401028305)
SyntaxName: | String(Octet)
MinLen: | 84
MaxLen: | 84
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80F9
Heuristics: | 12


Off-Line-AB-Server

AttName: Off-Line-AB-Server

LDAPName: | Off-Line-AB-Server
Boot: | FALSE
Space: | ms
AttID: | 131464 (392, \x2A864886F71401028308)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80FA
Heuristics: | 12


Off-Line-AB-Style

AttName: Off-Line-AB-Style

LDAPName: | Off-Line-AB-Style
Boot: | FALSE
Space: | ms
AttID: | 131462 (390, \x2A864886F71401028306)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80FB
Heuristics: | 12


OID-Type

AttName: OID-Type

LDAPName: | OID-Type
Boot: | FALSE
Space: | ms
AttID: | 131394 (322, \x2A864886F71401028242)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x80FC
Heuristics: | 12


OM-Object-Class

AttName: OM-Object-Class

LDAPName: | OM-Object-Class
Boot: | TRUE
Space: | ms
AttID: | 131290 (218, \x2A864886F7140102815A)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80FD
Heuristics: | 12


OM-Syntax

AttName: OM-Syntax

LDAPName: | OM-Syntax
Boot: | TRUE
Space: | ms
AttID: | 131303 (231, \x2A864886F71401028167)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x80FE
Heuristics: | 4


OOF-Reply-To-Originator

AttName: OOF-Reply-To-Originator

LDAPName: | OOF-Reply-To-Originator
Boot: | FALSE
Space: | ms
AttID: | 131510 (438, \x2A864886F71401028336)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x80FF
Heuristics: | 20


Open-Retry-Interval

AttName: Open-Retry-Interval

LDAPName: | Open-Retry-Interval
Boot: | FALSE
Space: | ms
AttID: | 131215 (143, \x2A864886F7140102810F)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8100
Heuristics: | 12


Organization-Name

AttName: Organization-Name

LDAPName: | o
Boot: | TRUE
Space: | x500
AttID: | 10 (10, \x55040A)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 64
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8101
Heuristics: | 18


Organizational-Unit-Name

AttName: Organizational-Unit-Name

LDAPName: | ou
Boot: | TRUE
Space: | x500
AttID: | 11 (11, \x55040B)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 64
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8102
Heuristics: | 18


Original-Display-Table

AttName: Original-Display-Table

LDAPName: | Original-Display-Table
Boot: | FALSE
Space: | ms
AttID: | 131517 (445, \x2A864886F7140102833D)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8103
Heuristics: | 12


Original-Display-Table-MSDOS

AttName: Original-Display-Table-MSDOS

LDAPName: | Original-Display-Table-MSDOS
Boot: | FALSE
Space: | ms
AttID: | 131286 (214, \x2A864886F71401028156)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8104
Heuristics: | 12


Outbound-Host

AttName: Outbound-Host

LDAPName: | Outbound-Host
Boot: | FALSE
Space: | ms
AttID: | 131560 (488, \x2A864886F71401028368)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x818D
Heuristics: | 13


Outbound-Host-Type

AttName: Outbound-Host-Type

LDAPName: | Outbound-Host-Type
Boot: | FALSE
Space: | ms
AttID: | 131594 (522, \x2A864886F7140102840A)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B0
Heuristics: | 13


Outbound-Newsfeed

AttName: Outbound-Newsfeed

LDAPName: | Outbound-Newsfeed
Boot: | FALSE
Space: | ms
AttID: | 131568 (496, \x2A864886F71401028370)
SyntaxName: | String(Unicode)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8195
Heuristics: | 13


Outbound-Sites

AttName: Outbound-Sites

LDAPName: | Outbound-Sites
Boot: | FALSE
Space: | ms
AttID: | 131072 (0, \x2A864886F714010200)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8105
Heuristics: | 12


Outgoing-Msg-Size-Limit

AttName: Outgoing-Msg-Size-Limit

LDAPName: | Outgoing-Msg-Size-Limit
Boot: | FALSE
Space: | ms
AttID: | 131562 (490, \x2A864886F7140102836A)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x818F
Heuristics: | 13


Override-NNTP-Content-Format

AttName: Override-NNTP-Content-Format

LDAPName: | Override-NNTP-Content-Format
Boot: | FALSE
Space: | ms
AttID: | 131616 (544, \x2A864886F71401028420)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81C6
Heuristics: | 13


OWA-Server

AttName: OWA-Server

LDAPName: | OWA-Server
Boot: | FALSE
Space: | ms
AttID: | 131680 (608, \x2A864886F71401028460)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C66
Heuristics: | 13


Owner

AttName: Owner

LDAPName: | owner
Boot: | FALSE
Space: | x500
AttID: | 32 (32, \x550420)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
LinkID: | link-22
Acl: | Admin
MapiID: | 0x800C
Heuristics: | 20


Owner-BL

AttName: Owner-BL

LDAPName: | Owner-BL
Boot: | FALSE
Space: | ms
AttID: | 131176 (104, \x2A864886F714010268)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | backlink-22
Acl: | System
MapiID: | 0x8024
Heuristics: | 12


P-Selector

AttName: P-Selector

LDAPName: | P-Selector
Boot: | FALSE
Space: | ms
AttID: | 131357 (285, \x2A864886F7140102821D)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 16
Multi: | FALSE
Acl: | User
MapiID: | 0x8106
Heuristics: | 12


P-Selector-Inbound

AttName: P-Selector-Inbound

LDAPName: | P-Selector-Inbound
Boot: | FALSE
Space: | ms
AttID: | 131124 (52, \x2A864886F714010234)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 16
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8107
Heuristics: | 12


Per-Msg-Dialog-Display-Table

AttName: Per-Msg-Dialog-Display-Table

LDAPName: | Per-Msg-Dialog-Display-Table
Boot: | FALSE
Space: | ms
AttID: | 131397 (325, \x2A864886F71401028245)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8108
Heuristics: | 12


Per-Recip-Dialog-Display-Table

AttName: Per-Recip-Dialog-Display-Table

LDAPName: | Per-Recip-Dialog-Display-Table
Boot: | FALSE
Space: | ms
AttID: | 131398 (326, \x2A864886F71401028246)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32768
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8109
Heuristics: | 12


Period-Rep-Sync-Times

AttName: Period-Rep-Sync-Times

LDAPName: | Period-Rep-Sync-Times
Boot: | FALSE
Space: | ms
AttID: | 131340 (268, \x2A864886F7140102820C)
SyntaxName: | String(Octet)
MinLen: | 84
MaxLen: | 84
Multi: | FALSE
Acl: | Admin
MapiID: | 0x810A
Heuristics: | 12


Period-Repl-Stagger

AttName: Period-Repl-Stagger

LDAPName: | Period-Repl-Stagger
Boot: | FALSE
Space: | ms
AttID: | 131336 (264, \x2A864886F71401028208)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x810B
Heuristics: | 12


Personal-Title

AttName: Personal-Title

LDAPName: | personalTitle
Boot: | FALSE
Space: | ms
AttID: | 131687 (615, \x2A864886F71401028467)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x8C6B
Heuristics: | 3


PF-Contacts

AttName: PF-Contacts

LDAPName: | PF-Contacts
Boot: | FALSE
Space: | ms
AttID: | 131147 (75, \x2A864886F71401024B)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8038
Heuristics: | 12


Physical-Delivery-Office-Name

AttName: Physical-Delivery-Office-Name

LDAPName: | physicalDeliveryOfficeName
Boot: | FALSE
Space: | x500
AttID: | 19 (19, \x550413)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A19
FastSearch: | 2
Heuristics: | 18


POP-Character-Set

AttName: POP-Character-Set

LDAPName: | POP-Character-Set
Boot: | FALSE
Space: | ms
AttID: | 131540 (468, \x2A864886F71401028354)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8179
Heuristics: | 12


POP-Content-Format

AttName: POP-Content-Format

LDAPName: | POP-Content-Format
Boot: | FALSE
Space: | ms
AttID: | 131538 (466, \x2A864886F71401028352)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8177
Heuristics: | 12


Port-Number

AttName: Port-Number

LDAPName: | Port-Number
Boot: | FALSE
Space: | ms
AttID: | 131599 (527, \x2A864886F7140102840F)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 65535
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B5
Heuristics: | 13


Poss-Superiors

AttName: Poss-Superiors

LDAPName: | Poss-Superiors
Boot: | TRUE
Space: | ms
AttID: | 131080 (8, \x2A864886F714010208)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Object ID Type: | CLASSID
Heuristics: | 12


Post-Office-Box

AttName: Post-Office-Box

LDAPName: | postOfficeBox
Boot: | FALSE
Space: | x500
AttID: | 18 (18, \x550412)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 40
Multi: | TRUE
Acl: | Admin
MapiID: | 0x3A2B
Heuristics: | 18


Postal-Address

AttName: Postal-Address

LDAPName: | Postal-Address
Boot: | FALSE
Space: | x500
AttID: | 16 (16, \x550410)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | Admin
MapiID: | 0x810C
Heuristics: | 18


Postal-Code

AttName: Postal-Code

LDAPName: | postalCode
Boot: | FALSE
Space: | x500
AttID: | 17 (17, \x550411)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 40
Multi: | FALSE
Acl: | User
MapiID: | 0x3A2A
Heuristics: | 18


Preferred-Delivery-Method

AttName: Preferred-Delivery-Method

LDAPName: | preferredDeliveryMethod
Boot: | FALSE
Space: | x500
AttID: | 28 (28, \x55041C)
SyntaxName: | Enumeration
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x810D
Heuristics: | 12


Presentation-Address

AttName: Presentation-Address

LDAPName: | presentationAddress
Boot: | TRUE
Space: | x500
AttID: | 29 (29, \x55041D)
SyntaxName: | Object(Presentation-Address)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
Heuristics: | 4


Preserve-Internet-Content

AttName: Preserve-Internet-Content

LDAPName: | Preserve-Internet-Content
Boot: | FALSE
Space: | ms
AttID: | 131628 (556, \x2A864886F7140102842C)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C22
Heuristics: | 13


PRMD

AttName: PRMD

LDAPName: | PRMD
Boot: | FALSE
Space: | ms
AttID: | 131296 (224, \x2A864886F71401028160)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 16
Multi: | FALSE
Acl: | Admin
MapiID: | 0x810E
Heuristics: | 12


Promo-Expiration

AttName: Promo-Expiration

LDAPName: | Promo-Expiration
Boot: | FALSE
Space: | ms
AttID: | 131612 (540, \x2A864886F7140102841C)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x81C2
Heuristics: | 13


Protocol-Settings

AttName: Protocol-Settings

LDAPName: | Protocol-Settings
Boot: | FALSE
Space: | ms
AttID: | 131600 (528, \x2A864886F71401028410)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | TRUE
Acl: | Admin
MapiID: | 0x81B6
Heuristics: | 13


Proxy-Addresses

AttName: Proxy-Addresses

LDAPName: | Proxy-Addresses
Boot: | TRUE
Space: | ms
AttID: | 131282 (210, \x2A864886F71401028152)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 1123
Multi: | TRUE
Acl: | Admin
MapiID: | 0x800F
FastSearch: | 2
Heuristics: | 18


Proxy-Generation-Enabled

AttName: Proxy-Generation-Enabled

LDAPName: | Proxy-Generation-Enabled
Boot: | FALSE
Space: | ms
AttID: | 131595 (523, \x2A864886F7140102840B)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B1
Heuristics: | 13


Proxy-Generator-DLL

AttName: Proxy-Generator-DLL

LDAPName: | Proxy-Generator-DLL
Boot: | FALSE
Space: | ms
AttID: | 131400 (328, \x2A864886F71401028248)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 255
Multi: | FALSE
Acl: | Admin
MapiID: | 0x810F
Heuristics: | 4


Public-Delegates

AttName: Public-Delegates

LDAPName: | Public-Delegates
Boot: | FALSE
Space: | ms
AttID: | 131310 (238, \x2A864886F7140102816E)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-7
Acl: | User
MapiID: | 0x8015
Heuristics: | 20


Public-Delegates-BL

AttName: Public-Delegates-BL

LDAPName: | Public-Delegates-BL
Boot: | FALSE
Space: | ms
AttID: | 131367 (295, \x2A864886F71401028227)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-7
Acl: | System
MapiID: | 0x8110
Heuristics: | 12


Quota-Notification-Schedule

AttName: Quota-Notification-Schedule

LDAPName: | Quota-Notification-Schedule
Boot: | FALSE
Space: | ms
AttID: | 131170 (98, \x2A864886F714010262)
SyntaxName: | String(Octet)
MinLen: | 84
MaxLen: | 84
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8111
Heuristics: | 12


Quota-Notification-Style

AttName: Quota-Notification-Style

LDAPName: | Quota-Notification-Style
Boot: | FALSE
Space: | ms
AttID: | 131460 (388, \x2A864886F71401028304)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8112
Heuristics: | 12


Range-Lower

AttName: Range-Lower

LDAPName: | Range-Lower
Boot: | TRUE
Space: | ms
AttID: | 131106 (34, \x2A864886F714010222)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8113
Heuristics: | 12


Range-Upper

AttName: Range-Upper

LDAPName: | Range-Upper
Boot: | TRUE
Space: | ms
AttID: | 131107 (35, \x2A864886F714010223)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8114
Heuristics: | 12


RAS-Account

AttName: RAS-Account

LDAPName: | RAS-Account
Boot: | FALSE
Space: | ms
AttID: | 131591 (519, \x2A864886F71401028407)
SyntaxName: | String(Unicode)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81AD
Heuristics: | 13


RAS-Callback-Number

AttName: RAS-Callback-Number

LDAPName: | RAS-Callback-Number
Boot: | FALSE
Space: | ms
AttID: | 131387 (315, \x2A864886F7140102823B)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 48
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8115
Heuristics: | 12


RAS-Password

AttName: RAS-Password

LDAPName: | RAS-Password
Boot: | FALSE
Space: | ms
AttID: | 131592 (520, \x2A864886F71401028408)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81AE
Heuristics: | 13


RAS-Phone-Number

AttName: RAS-Phone-Number

LDAPName: | RAS-Phone-Number
Boot: | FALSE
Space: | ms
AttID: | 131386 (314, \x2A864886F7140102823A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8116
Heuristics: | 12


RAS-Phonebook-Entry-Name

AttName: RAS-Phonebook-Entry-Name

LDAPName: | RAS-Phonebook-Entry-Name
Boot: | FALSE
Space: | ms
AttID: | 131385 (313, \x2A864886F71401028239)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8117
Heuristics: | 12


RAS-Remote-SRVR-Name

AttName: RAS-Remote-SRVR-Name

LDAPName: | RAS-Remote-SRVR-Name
Boot: | FALSE
Space: | ms
AttID: | 131150 (78, \x2A864886F71401024E)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 15
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8118
Heuristics: | 12


RDN-Att-ID

AttName: RDN-Att-ID

LDAPName: | RDN-Att-ID
Boot: | TRUE
Space: | ms
AttID: | 131098 (26, \x2A864886F71401021A)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
Object ID Type: | ATTID
Heuristics: | 4


Ref-Full-Replicas

AttName: Ref-Full-Replicas

LDAPName: | Ref-Full-Replicas
Boot: | TRUE
Space: | ms
AttID: | 131137 (65, \x2A864886F714010241)
SyntaxName: | Object(Access-Point)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Heuristics: | 12


Ref-Master-DSA

AttName: Ref-Master-DSA

LDAPName: | Ref-Master-DSA
Boot: | TRUE
Space: | ms
AttID: | 131138 (66, \x2A864886F714010242)
SyntaxName: | Object(Access-Point)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
Heuristics: | 4


Referral-List

AttName: Referral-List

LDAPName: | Referral-List
Boot: | FALSE
Space: | ms
AttID: | 131582 (510, \x2A864886F7140102837E)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | TRUE
Acl: | Admin
MapiID: | 0x81A3
Heuristics: | 12


Registered-Address

AttName: Registered-Address

LDAPName: | registeredAddress
Boot: | FALSE
Space: | x500
AttID: | 26 (26, \x55041A)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 4096
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8119
Heuristics: | 12


Remote-Bridge-Head

AttName: Remote-Bridge-Head

LDAPName: | Remote-Bridge-Head
Boot: | FALSE
Space: | ms
AttID: | 131263 (191, \x2A864886F7140102813F)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x811A
Heuristics: | 12


Remote-Bridge-Head-Address

AttName: Remote-Bridge-Head-Address

LDAPName: | Remote-Bridge-Head-Address
Boot: | FALSE
Space: | ms
AttID: | 131166 (94, \x2A864886F71401025E)
SyntaxName: | String(Teletex)
MinLen: | 0
MaxLen: | 1118
Multi: | FALSE
Acl: | Admin
MapiID: | 0x811B
Heuristics: | 12


Remote-Out-BH-Server

AttName: Remote-Out-BH-Server

LDAPName: | Remote-Out-BH-Server
Boot: | FALSE
Space: | ms
AttID: | 131382 (310, \x2A864886F71401028236)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x811C
Heuristics: | 12


Remote-Site

AttName: Remote-Site

LDAPName: | Remote-Site
Boot: | FALSE
Space: | ms
AttID: | 131099 (27, \x2A864886F71401021B)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x811D
Heuristics: | 12


Replicated-Object-Version

AttName: Replicated-Object-Version

LDAPName: | replicatedObjectVersion
Boot: | FALSE
Space: | ms
AttID: | 131676 (604, \x2A864886F7140102845C)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C62
Heuristics: | 5


Replication-Mail-Msg-Size

AttName: Replication-Mail-Msg-Size

LDAPName: | Replication-Mail-Msg-Size
Boot: | FALSE
Space: | ms
AttID: | 131175 (103, \x2A864886F714010267)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8168
Heuristics: | 12


Replication-Sensitivity

AttName: Replication-Sensitivity

LDAPName: | Replication-Sensitivity
Boot: | FALSE
Space: | ms
AttID: | 131295 (223, \x2A864886F7140102815F)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 100
Multi: | FALSE
Acl: | Admin
MapiID: | 0x811E
Heuristics: | 12


Replication-Stagger

AttName: Replication-Stagger

LDAPName: | Replication-Stagger
Boot: | FALSE
Space: | ms
AttID: | 131421 (349, \x2A864886F7140102825D)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x811F
Heuristics: | 12


Report-To-Originator

AttName: Report-To-Originator

LDAPName: | Report-To-Originator
Boot: | FALSE
Space: | ms
AttID: | 131278 (206, \x2A864886F7140102814E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x8120
Heuristics: | 20


Report-To-Owner

AttName: Report-To-Owner

LDAPName: | Report-To-Owner
Boot: | FALSE
Space: | ms
AttID: | 131279 (207, \x2A864886F7140102814F)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x8121
Heuristics: | 20


Reports

AttName: Reports

LDAPName: | Reports
Boot: | FALSE
Space: | ms
AttID: | 131508 (436, \x2A864886F71401028334)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-21
Acl: | System
MapiID: | 0x800E
Heuristics: | 18


Reps-From

AttName: Reps-From

LDAPName: | Reps-From
Boot: | TRUE
Space: | ms
AttID: | 131163 (91, \x2A864886F71401025B)
SyntaxName: | Object(Replica-Link)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
Heuristics: | 12


Reps-To

AttName: Reps-To

LDAPName: | Reps-To
Boot: | TRUE
Space: | ms
AttID: | 131155 (83, \x2A864886F714010253)
SyntaxName: | Object(Replica-Link)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
Heuristics: | 12


Reps-To-Ext

AttName: Reps-To-Ext

LDAPName: | Reps-To-Ext
Boot: | FALSE
Space: | ms
AttID: | 131115 (43, \x2A864886F71401022B)
SyntaxName: | Object(Replica-Link)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Heuristics: | 12


Req-Seq

AttName: Req-Seq

LDAPName: | Req-Seq
Boot: | FALSE
Space: | ms
AttID: | 131245 (173, \x2A864886F7140102812D)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8122
Heuristics: | 12


Require-SSL

AttName: Require-SSL

LDAPName: | Require-SSL
Boot: | FALSE
Space: | ms
AttID: | 131632 (560, \x2A864886F71401028430)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C25
Heuristics: | 13


Responsible-Local-DXA

AttName: Responsible-Local-DXA

LDAPName: | Responsible-Local-DXA
Boot: | FALSE
Space: | ms
AttID: | 131370 (298, \x2A864886F7140102822A)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
LinkID: | Link-8
Acl: | Admin
MapiID: | 0x8123
Heuristics: | 12


Return-Exact-Msg-Size

AttName: Return-Exact-Msg-Size

LDAPName: | Return-Exact-Msg-Size
Boot: | FALSE
Space: | ms
AttID: | 131666 (594, \x2A864886F71401028452)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C52
Heuristics: | 13


Rid-Server

AttName: Rid-Server

LDAPName: | Rid-Server
Boot: | FALSE
Space: | ms
AttID: | 131418 (346, \x2A864886F7140102825A)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8124
Heuristics: | 12


Role-Occupant

AttName: Role-Occupant

LDAPName: | roleOccupant
Boot: | FALSE
Space: | x500
AttID: | 33 (33, \x550421)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8125
Heuristics: | 4


Root-Newsgroups-Folder-ID

AttName: Root-Newsgroups-Folder-ID

LDAPName: | Root-Newsgroups-Folder-ID
Boot: | FALSE
Space: | ms
AttID: | 131596 (524, \x2A864886F7140102840C)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81B2
Heuristics: | 13


Routing-List

AttName: Routing-List

LDAPName: | Routing-List
Boot: | FALSE
Space: | ms
AttID: | 131426 (354, \x2A864886F71401028262)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 2243
Multi: | TRUE
LinkID: | Link-1003
Acl: | Admin
MapiID: | 0x8126
Heuristics: | 12


RTS-Checkpoint-Size

AttName: RTS-Checkpoint-Size

LDAPName: | RTS-Checkpoint-Size
Boot: | FALSE
Space: | ms
AttID: | 131224 (152, \x2A864886F71401028118)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 100
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8127
Heuristics: | 12


RTS-Recovery-Timeout

AttName: RTS-Recovery-Timeout

LDAPName: | RTS-Recovery-Timeout
Boot: | FALSE
Space: | ms
AttID: | 131223 (151, \x2A864886F71401028117)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8128
Heuristics: | 12


RTS-Window-Size

AttName: RTS-Window-Size

LDAPName: | RTS-Window-Size
Boot: | FALSE
Space: | ms
AttID: | 131225 (153, \x2A864886F71401028119)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 10
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8129
Heuristics: | 12


Runs-On

AttName: Runs-On

LDAPName: | Runs-On
Boot: | FALSE
Space: | ms
AttID: | 131257 (185, \x2A864886F71401028139)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x812A
Heuristics: | 12


S-Selector

AttName: S-Selector

LDAPName: | S-Selector
Boot: | FALSE
Space: | ms
AttID: | 131356 (284, \x2A864886F7140102821C)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 16
Multi: | FALSE
Acl: | User
MapiID: | 0x812B
Heuristics: | 12


S-Selector-Inbound

AttName: S-Selector-Inbound

LDAPName: | S-Selector-Inbound
Boot: | FALSE
Space: | ms
AttID: | 131118 (46, \x2A864886F71401022E)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 16
Multi: | FALSE
Acl: | Admin
MapiID: | 0x812C
Heuristics: | 12


Schema-Flags

AttName: Schema-Flags

LDAPName: | Schema-Flags
Boot: | FALSE
Space: | ms
AttID: | 131534 (462, \x2A864886F7140102834E)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8173
Heuristics: | 12


Schema-Version

AttName: Schema-Version

LDAPName: | Schema-Version
Boot: | FALSE
Space: | ms
AttID: | 131543 (471, \x2A864886F71401028357)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 1427
Multi: | TRUE
Acl: | Admin
MapiID: | 0x817C
Heuristics: | 12


Search-Flags

AttName: Search-Flags

LDAPName: | Search-Flags
Boot: | TRUE
Space: | ms
AttID: | 131406 (334, \x2A864886F7140102824E)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x812D
Heuristics: | 12


Search-Guide

AttName: Search-Guide

LDAPName: | enhancedSearchGuide
Boot: | FALSE
Space: | x500
AttID: | 14 (14, \x55040E)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
MapiID: | 0x812E
Heuristics: | 12


Security-Policy

AttName: Security-Policy

LDAPName: | Security-Policy
Boot: | FALSE
Space: | ms
AttID: | 131661 (589, \x2A864886F7140102844D)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32767
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C47
Heuristics: | 13


Security-Protocol

AttName: Security-Protocol

LDAPName: | Security-Protocol
Boot: | FALSE
Space: | ms
AttID: | 131154 (82, \x2A864886F714010252)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 1024
Multi: | TRUE
Acl: | User
MapiID: | 0x8037
Heuristics: | 12


See-Also

AttName: See-Also

LDAPName: | seeAlso
Boot: | FALSE
Space: | x500
AttID: | 34 (34, \x550422)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x812F
Heuristics: | 2


Send-EMail-Message

AttName: Send-EMail-Message

LDAPName: | Send-EMail-Message
Boot: | FALSE
Space: | ms
AttID: | 131638 (566, \x2A864886F71401028436)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C31
Heuristics: | 13


Send-TNEF

AttName: Send-TNEF

LDAPName: | Send-TNEF
Boot: | FALSE
Space: | ms
AttID: | 131564 (492, \x2A864886F7140102836C)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8191
Heuristics: | 3


Serial-Number

AttName: Serial-Number

LDAPName: | serialNumber
Boot: | FALSE
Space: | x500
AttID: | 5 (5, \x550405)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 64
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8130
Heuristics: | 12


Service-Action-First

AttName: Service-Action-First

LDAPName: | Service-Action-First
Boot: | FALSE
Space: | ms
AttID: | 131233 (161, \x2A864886F71401028121)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8131
Heuristics: | 12


Service-Action-Other

AttName: Service-Action-Other

LDAPName: | Service-Action-Other
Boot: | FALSE
Space: | ms
AttID: | 131131 (59, \x2A864886F71401023B)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8132
Heuristics: | 12


Service-Action-Second

AttName: Service-Action-Second

LDAPName: | Service-Action-Second
Boot: | FALSE
Space: | ms
AttID: | 131132 (60, \x2A864886F71401023C)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 2
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8133
Heuristics: | 12


Service-Restart-Delay

AttName: Service-Restart-Delay

LDAPName: | Service-Restart-Delay
Boot: | FALSE
Space: | ms
AttID: | 131234 (162, \x2A864886F71401028122)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8134
Heuristics: | 12


Service-Restart-Message

AttName: Service-Restart-Message

LDAPName: | Service-Restart-Message
Boot: | FALSE
Space: | ms
AttID: | 131130 (58, \x2A864886F71401023A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 120
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8135
Heuristics: | 12


Session-Disconnect-Timer

AttName: Session-Disconnect-Timer

LDAPName: | Session-Disconnect-Timer
Boot: | FALSE
Space: | ms
AttID: | 131226 (154, \x2A864886F7140102811A)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8136
Heuristics: | 12


Site-Affinity

AttName: Site-Affinity

LDAPName: | Site-Affinity
Boot: | FALSE
Space: | ms
AttID: | 131506 (434, \x2A864886F71401028332)
SyntaxName: | String(Teletex)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8137
Heuristics: | 12


Site-Folder-GUID

AttName: Site-Folder-GUID

LDAPName: | Site-Folder-GUID
Boot: | FALSE
Space: | ms
AttID: | 131528 (456, \x2A864886F71401028348)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8166
Heuristics: | 12


Site-Folder-Server

AttName: Site-Folder-Server

LDAPName: | Site-Folder-Server
Boot: | FALSE
Space: | ms
AttID: | 131529 (457, \x2A864886F71401028349)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8167
Heuristics: | 12


Site-Proxy-Space

AttName: Site-Proxy-Space

LDAPName: | Site-Proxy-Space
Boot: | FALSE
Space: | ms
AttID: | 131457 (385, \x2A864886F71401028301)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1123
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8138
Heuristics: | 12


SMIME-Alg-List-NA

AttName: SMIME-Alg-List-NA

LDAPName: | SMIME-Alg-List-NA
Boot: | FALSE
Space: | ms
AttID: | 131640 (568, \x2A864886F71401028438)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C33
Heuristics: | 13


SMIME-Alg-List-Other

AttName: SMIME-Alg-List-Other

LDAPName: | SMIME-Alg-List-Other
Boot: | FALSE
Space: | ms
AttID: | 131641 (569, \x2A864886F71401028439)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C34
Heuristics: | 13


SMIME-Alg-Selected-NA

AttName: SMIME-Alg-Selected-NA

LDAPName: | SMIME-Alg-Selected-NA
Boot: | FALSE
Space: | ms
AttID: | 131642 (570, \x2A864886F7140102843A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C35
Heuristics: | 13


SMIME-Alg-Selected-Other

AttName: SMIME-Alg-Selected-Other

LDAPName: | SMIME-Alg-Selected-Other
Boot: | FALSE
Space: | ms
AttID: | 131643 (571, \x2A864886F7140102843B)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C36
Heuristics: | 13


Space-Last-Computed

AttName: Space-Last-Computed

LDAPName: | Space-Last-Computed
Boot: | FALSE
Space: | ms
AttID: | 131458 (386, \x2A864886F71401028302)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8139
Heuristics: | 12


State-Or-Province-Name

AttName: State-Or-Province-Name

LDAPName: | st
Boot: | FALSE
Space: | x500
AttID: | 8 (8, \x550408)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A28
Heuristics: | 18


Street-Address

AttName: Street-Address

LDAPName: | street
Boot: | FALSE
Space: | x500
AttID: | 9 (9, \x550409)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x813A
Heuristics: | 12


Sub-Class-Of

AttName: Sub-Class-Of

LDAPName: | Sub-Class-Of
Boot: | TRUE
Space: | ms
AttID: | 131093 (21, \x2A864886F714010215)
SyntaxName: | String(Object-Identifier)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
Object ID Type: | CLASSID
Heuristics: | 4


Sub-Refs

AttName: Sub-Refs

LDAPName: | Sub-Refs
Boot: | TRUE
Space: | ms
AttID: | 131079 (7, \x2A864886F714010207)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | System
MapiID: | 0x813B
Heuristics: | 12


Sub-Site

AttName: Sub-Site

LDAPName: | Sub-Site
Boot: | FALSE
Space: | ms
AttID: | 131542 (470, \x2A864886F71401028356)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x817B
Heuristics: | 12


Submission-Cont-Length

AttName: Submission-Cont-Length

LDAPName: | Submission-Cont-Length
Boot: | FALSE
Space: | ms
AttID: | 131352 (280, \x2A864886F71401028218)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x813C
Heuristics: | 20


Support-SMIME-Signatures

AttName: Support-SMIME-Signatures

LDAPName: | Support-SMIME-Signatures
Boot: | FALSE
Space: | ms
AttID: | 131662 (590, \x2A864886F7140102844E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C48
Heuristics: | 13


Supported-Algorithms

AttName: Supported-Algorithms

LDAPName: | supportedAlgorithms
Boot: | FALSE
Space: | ms
AttID: | 131669 (597, \x2A864886F71401028455)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C55
Heuristics: | 13


Supported-Application-Context

AttName: Supported-Application-Context

LDAPName: | supportedApplicationContext
Boot: | FALSE
Space: | x500
AttID: | 30 (30, \x55041E)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x813D
Heuristics: | 12


Supporting-Stack

AttName: Supporting-Stack

LDAPName: | Supporting-Stack
Boot: | FALSE
Space: | ms
AttID: | 131100 (28, \x2A864886F71401021C)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-14
Acl: | Admin
MapiID: | 0x813E
Heuristics: | 12


Supporting-Stack-BL

AttName: Supporting-Stack-BL

LDAPName: | Supporting-Stack-BL
Boot: | FALSE
Space: | ms
AttID: | 131429 (357, \x2A864886F71401028265)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-14
Acl: | System
MapiID: | 0x813F
Heuristics: | 12


Surname

AttName: Surname

LDAPName: | sn
Boot: | FALSE
Space: | x500
AttID: | 4 (4, \x550404)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A11
FastSearch: | 2
Heuristics: | 18


T-Selector

AttName: T-Selector

LDAPName: | T-Selector
Boot: | FALSE
Space: | ms
AttID: | 131355 (283, \x2A864886F7140102821B)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | User
MapiID: | 0x8140
Heuristics: | 12


T-Selector-Inbound

AttName: T-Selector-Inbound

LDAPName: | T-Selector-Inbound
Boot: | FALSE
Space: | ms
AttID: | 131077 (5, \x2A864886F714010205)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8141
Heuristics: | 12


Tagged-X509-Cert

AttName: Tagged-X509-Cert

LDAPName: | taggedCertificate
Boot: | FALSE
Space: | ms
AttID: | 131686 (614, \x2A864886F71401028466)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | User
MapiID: | 0x3A70
Heuristics: | 3


Target-Address

AttName: Target-Address

LDAPName: | Target-Address
Boot: | FALSE
Space: | ms
AttID: | 131424 (352, \x2A864886F71401028260)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 1123
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8011
Heuristics: | 18


Target-MTAs

AttName: Target-MTAs

LDAPName: | Target-MTAs
Boot: | FALSE
Space: | ms
AttID: | 131331 (259, \x2A864886F71401028203)
SyntaxName: | String(Teletex)
MinLen: | 1
MaxLen: | 36
Multi: | TRUE
Acl: | User
MapiID: | 0x8142
Heuristics: | 12


Telephone-Assistant

AttName: Telephone-Assistant

LDAPName: | Telephone-Assistant
Boot: | FALSE
Space: | ms
AttID: | 131151 (79, \x2A864886F71401024F)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A2E
Heuristics: | 20


Telephone-Fax

AttName: Telephone-Fax

LDAPName: | facsimileTelephoneNumber
Boot: | FALSE
Space: | ms
AttID: | 131114 (42, \x2A864886F71401022A)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A23
Heuristics: | 18


Telephone-Home

AttName: Telephone-Home

LDAPName: | homephone
Boot: | FALSE
Space: | ms
AttID: | 131149 (77, \x2A864886F71401024D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A09
Heuristics: | 18


Telephone-Home-Fax

AttName: Telephone-Home-Fax

LDAPName: | homeFax
Boot: | FALSE
Space: | ms
AttID: | 131681 (609, \x2A864886F71401028461)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | User
MapiID: | 0x3A25
Heuristics: | 21


Telephone-Home2

AttName: Telephone-Home2

LDAPName: | Telephone-Home2
Boot: | FALSE
Space: | ms
AttID: | 131349 (277, \x2A864886F71401028215)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A2F
Heuristics: | 20


Telephone-Mobile

AttName: Telephone-Mobile

LDAPName: | mobile
Boot: | FALSE
Space: | ms
AttID: | 131076 (4, \x2A864886F714010204)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A1C
Heuristics: | 18


Telephone-Number

AttName: Telephone-Number

LDAPName: | Telephone-Number
Boot: | FALSE
Space: | x500
AttID: | 20 (20, \x550414)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 32
Multi: | TRUE
Acl: | User
MapiID: | 0x8012
Heuristics: | 18


Telephone-Office1

AttName: Telephone-Office1

LDAPName: | telephoneNumber
Boot: | FALSE
Space: | ms
AttID: | 131190 (118, \x2A864886F714010276)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A08
Heuristics: | 18


Telephone-Office2

AttName: Telephone-Office2

LDAPName: | Telephone-Office2
Boot: | FALSE
Space: | ms
AttID: | 131090 (18, \x2A864886F714010212)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A1B
Heuristics: | 18


Telephone-Pager

AttName: Telephone-Pager

LDAPName: | pager
Boot: | FALSE
Space: | ms
AttID: | 131334 (262, \x2A864886F71401028206)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x3A21
Heuristics: | 18


Telephone-Personal-Mobile

AttName: Telephone-Personal-Mobile

LDAPName: | personalMobile
Boot: | FALSE
Space: | ms
AttID: | 131683 (611, \x2A864886F71401028463)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | User
MapiID: | 0x3A1D
Heuristics: | 21


Telephone-Personal-Pager

AttName: Telephone-Personal-Pager

LDAPName: | personalPager
Boot: | FALSE
Space: | ms
AttID: | 131684 (612, \x2A864886F71401028464)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | User
MapiID: | 0x8C68
Heuristics: | 21


Teletex-Terminal-Identifier

AttName: Teletex-Terminal-Identifier

LDAPName: | teletexTerminalIdentifier
Boot: | FALSE
Space: | x500
AttID: | 22 (22, \x550416)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8143
Heuristics: | 18


Telex-Number

AttName: Telex-Number

LDAPName: | telexNumber
Boot: | FALSE
Space: | x500
AttID: | 21 (21, \x550415)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 32
Multi: | TRUE
Acl: | User
MapiID: | 0x3A2C
Heuristics: | 18


Temp-Assoc-Threshold

AttName: Temp-Assoc-Threshold

LDAPName: | Temp-Assoc-Threshold
Boot: | FALSE
Space: | ms
AttID: | 131401 (329, \x2A864886F71401028249)
SyntaxName: | Integer
MinLen: | 1
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8144
Heuristics: | 12


Text-Country

AttName: Text-Country

LDAPName: | co
Boot: | FALSE
Space: | ms
AttID: | 131203 (131, \x2A864886F71401028103)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | User
MapiID: | 0x3A26
Heuristics: | 18


Title

AttName: Title

LDAPName: | title
Boot: | FALSE
Space: | x500
AttID: | 12 (12, \x55040C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | Admin
MapiID: | 0x3A17
Heuristics: | 18


Tombstone-Lifetime

AttName: Tombstone-Lifetime

LDAPName: | Tombstone-Lifetime
Boot: | FALSE
Space: | ms
AttID: | 131126 (54, \x2A864886F714010236)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8145
Heuristics: | 12


Tracking-Log-Path-Name

AttName: Tracking-Log-Path-Name

LDAPName: | Tracking-Log-Path-Name
Boot: | FALSE
Space: | ms
AttID: | 131419 (347, \x2A864886F7140102825B)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8146
Heuristics: | 12


Trans-Retry-Mins

AttName: Trans-Retry-Mins

LDAPName: | Trans-Retry-Mins
Boot: | FALSE
Space: | ms
AttID: | 131291 (219, \x2A864886F7140102815B)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x8147
Heuristics: | 4


Trans-Timeout-Mins

AttName: Trans-Timeout-Mins

LDAPName: | Trans-Timeout-Mins
Boot: | FALSE
Space: | ms
AttID: | 131292 (220, \x2A864886F7140102815C)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x8148
Heuristics: | 4


Transfer-Retry-Interval

AttName: Transfer-Retry-Interval

LDAPName: | Transfer-Retry-Interval
Boot: | FALSE
Space: | ms
AttID: | 131205 (133, \x2A864886F71401028105)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8149
Heuristics: | 12


Transfer-Timeout-Non-Urgent

AttName: Transfer-Timeout-Non-Urgent

LDAPName: | Transfer-Timeout-Non-Urgent
Boot: | FALSE
Space: | ms
AttID: | 131208 (136, \x2A864886F71401028108)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x814A
Heuristics: | 12


Transfer-Timeout-Normal

AttName: Transfer-Timeout-Normal

LDAPName: | Transfer-Timeout-Normal
Boot: | FALSE
Space: | ms
AttID: | 131209 (137, \x2A864886F71401028109)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x814B
Heuristics: | 12


Transfer-Timeout-Urgent

AttName: Transfer-Timeout-Urgent

LDAPName: | Transfer-Timeout-Urgent
Boot: | FALSE
Space: | ms
AttID: | 131214 (142, \x2A864886F7140102810E)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x814C
Heuristics: | 12


Translation-Table-Used

AttName: Translation-Table-Used

LDAPName: | Translation-Table-Used
Boot: | FALSE
Space: | ms
AttID: | 131468 (396, \x2A864886F7140102830C)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x814D
Heuristics: | 12


Transport-Expedited-Data

AttName: Transport-Expedited-Data

LDAPName: | Transport-Expedited-Data
Boot: | FALSE
Space: | ms
AttID: | 131222 (150, \x2A864886F71401028116)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x814E
Heuristics: | 12


Trust-Level

AttName: Trust-Level

LDAPName: | Trust-Level
Boot: | FALSE
Space: | ms
AttID: | 131142 (70, \x2A864886F714010246)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 100
Multi: | FALSE
Acl: | Admin
MapiID: | 0x814F
Heuristics: | 12


Turn-Request-Threshold

AttName: Turn-Request-Threshold

LDAPName: | Turn-Request-Threshold
Boot: | FALSE
Space: | ms
AttID: | 131110 (38, \x2A864886F714010226)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8150
Heuristics: | 12


Two-Way-Alternate-Facility

AttName: Two-Way-Alternate-Facility

LDAPName: | Two-Way-Alternate-Facility
Boot: | FALSE
Space: | ms
AttID: | 131112 (40, \x2A864886F714010228)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8151
Heuristics: | 12


Type

AttName: Type

LDAPName: | Type
Boot: | FALSE
Space: | ms
AttID: | 131645 (573, \x2A864886F7140102843D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | System
MapiID: | 0x8C38
Heuristics: | 13


Unauth-Orig

AttName: Unauth-Orig

LDAPName: | Unauth-Orig
Boot: | FALSE
Space: | ms
AttID: | 131293 (221, \x2A864886F7140102815D)
SyntaxName: | Object(OR-Name)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Link-4
Acl: | User
Heuristics: | 20


Unauth-Orig-BL

AttName: Unauth-Orig-BL

LDAPName: | Unauth-Orig-BL
Boot: | FALSE
Space: | ms
AttID: | 131364 (292, \x2A864886F71401028224)
SyntaxName: | Object(DS-DN)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
LinkID: | Backlink-4
Acl: | System
MapiID: | 0x8152
Heuristics: | 12


Use-Server-Values

AttName: Use-Server-Values

LDAPName: | Use-Server-Values
Boot: | FALSE
Space: | ms
AttID: | 131545 (473, \x2A864886F71401028359)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x817E
Heuristics: | 12


Use-Site-Values

AttName: Use-Site-Values

LDAPName: | Use-Site-Values
Boot: | FALSE
Space: | ms
AttID: | 131550 (478, \x2A864886F7140102835E)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8183
Heuristics: | 13


Usenet-Site-Name

AttName: Usenet-Site-Name

LDAPName: | Usenet-Site-Name
Boot: | FALSE
Space: | ms
AttID: | 131556 (484, \x2A864886F71401028364)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8189
Heuristics: | 13


User-Cert

AttName: User-Cert

LDAPName: | User-Cert
Boot: | FALSE
Space: | x500
AttID: | 36 (36, \x550424)
SyntaxName: | String(Octet)
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | User
MapiID: | 0x3A22
Heuristics: | 18


User-Password

AttName: User-Password

LDAPName: | userPassword
Boot: | FALSE
Space: | x500
AttID: | 35 (35, \x550423)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 128
Multi: | TRUE
Acl: | User
MapiID: | 0x8153
Heuristics: | 4


USN-Changed

AttName: USN-Changed

LDAPName: | USN-Changed
Boot: | TRUE
Space: | ms
AttID: | 131192 (120, \x2A864886F714010278)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x8029
FastSearch: | 1
Heuristics: | 12


USN-Created

AttName: USN-Created

LDAPName: | USN-Created
Boot: | TRUE
Space: | ms
AttID: | 131091 (19, \x2A864886F714010213)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x8154
Heuristics: | 12


USN-DSA-Last-Obj-Removed

AttName: USN-DSA-Last-Obj-Removed

LDAPName: | USN-DSA-Last-Obj-Removed
Boot: | FALSE
Space: | ms
AttID: | 131339 (267, \x2A864886F7140102820B)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x8155
Heuristics: | 12


USN-Intersite

AttName: USN-Intersite

LDAPName: | USN-Intersite
Boot: | FALSE
Space: | ms
AttID: | 131541 (469, \x2A864886F71401028355)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x817A
FastSearch: | 1
Heuristics: | 12


USN-Last-Obj-Rem

AttName: USN-Last-Obj-Rem

LDAPName: | USN-Last-Obj-Rem
Boot: | TRUE
Space: | ms
AttID: | 131193 (121, \x2A864886F714010279)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x8156
Heuristics: | 12


USN-Source

AttName: USN-Source

LDAPName: | USN-Source
Boot: | TRUE
Space: | ms
AttID: | 131446 (374, \x2A864886F71401028276)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x8157
Heuristics: | 12


View-Container-1

AttName: View-Container-1

LDAPName: | View-Container-1
Boot: | FALSE
Space: | ms
AttID: | 131609 (537, \x2A864886F71401028419)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81BF
Heuristics: | 13


View-Container-2

AttName: View-Container-2

LDAPName: | View-Container-2
Boot: | FALSE
Space: | ms
AttID: | 131610 (538, \x2A864886F7140102841A)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81C0
Heuristics: | 13


View-Container-3

AttName: View-Container-3

LDAPName: | View-Container-3
Boot: | FALSE
Space: | ms
AttID: | 131611 (539, \x2A864886F7140102841B)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81C1
Heuristics: | 13


View-Definition

AttName: View-Definition

LDAPName: | View-Definition
Boot: | FALSE
Space: | ms
AttID: | 131621 (549, \x2A864886F71401028425)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 2048
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C1B
Heuristics: | 12


View-Flags

AttName: View-Flags

LDAPName: | View-Flags
Boot: | FALSE
Space: | ms
AttID: | 131618 (546, \x2A864886F71401028422)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C18
Heuristics: | 12


View-Site

AttName: View-Site

LDAPName: | View-Site
Boot: | FALSE
Space: | ms
AttID: | 131608 (536, \x2A864886F71401028418)
SyntaxName: | String(Unicode)
MinLen: | 0
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81BE
Heuristics: | 13


Voice-Mail-Flags

AttName: Voice-Mail-Flags

LDAPName: | Voice-Mail-Flags
Boot: | FALSE
Space: | ms
AttID: | 131653 (581, \x2A864886F71401028445)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C40
Heuristics: | 13


Voice-Mail-Greetings

AttName: Voice-Mail-Greetings

LDAPName: | Voice-Mail-Greetings
Boot: | FALSE
Space: | ms
AttID: | 131652 (580, \x2A864886F71401028444)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | TRUE
Acl: | User
MapiID: | 0x8C3F
Heuristics: | 13


Voice-Mail-Password

AttName: Voice-Mail-Password

LDAPName: | Voice-Mail-Password
Boot: | FALSE
Space: | ms
AttID: | 131650 (578, \x2A864886F71401028442)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x8C3D
Heuristics: | 13


Voice-Mail-Recorded-Name

AttName: Voice-Mail-Recorded-Name

LDAPName: | Voice-Mail-Recorded-Name
Boot: | FALSE
Space: | ms
AttID: | 131651 (579, \x2A864886F71401028443)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x8C3E
Heuristics: | 13


Voice-Mail-Recording-Length

AttName: Voice-Mail-Recording-Length

LDAPName: | Voice-Mail-Recording-Length
Boot: | FALSE
Space: | ms
AttID: | 131657 (585, \x2A864886F71401028449)
SyntaxName: | integer
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8C43
Heuristics: | 13


Voice-Mail-Speed

AttName: Voice-Mail-Speed

LDAPName: | Voice-Mail-Speed
Boot: | FALSE
Space: | ms
AttID: | 131655 (583, \x2A864886F71401028447)
SyntaxName: | integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C42
Heuristics: | 13


Voice-Mail-System-GUID

AttName: Voice-Mail-System-GUID

LDAPName: | Voice-Mail-System-GUID
Boot: | FALSE
Space: | ms
AttID: | 131648 (576, \x2A864886F71401028440)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C3B
Heuristics: | 13


Voice-Mail-User-ID

AttName: Voice-Mail-User-ID

LDAPName: | Voice-Mail-User-ID
Boot: | FALSE
Space: | ms
AttID: | 131649 (577, \x2A864886F71401028441)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 64
Multi: | FALSE
Acl: | User
MapiID: | 0x8C3C
Heuristics: | 13


Voice-Mail-Volume

AttName: Voice-Mail-Volume

LDAPName: | Voice-Mail-Volume
Boot: | FALSE
Space: | ms
AttID: | 131654 (582, \x2A864886F71401028446)
SyntaxName: | Integer
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8C41
Heuristics: | 13


When-Changed

AttName: When-Changed

LDAPName: | modifyTimestamp
Boot: | TRUE
Space: | ms
AttID: | 131075 (3, \x2A864886F714010203)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x3008
Heuristics: | 12


When-Created

AttName: When-Created

LDAPName: | createTimestamp
Boot: | TRUE
Space: | ms
AttID: | 131074 (2, \x2A864886F714010202)
SyntaxName: | String(UTC-Time)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | System
MapiID: | 0x3007
Heuristics: | 12


WWW-Home-Page

AttName: WWW-Home-Page

LDAPName: | url
Boot: | FALSE
Space: | ms
AttID: | 131536 (464, \x2A864886F71401028350)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 2048
Multi: | FALSE
Acl: | User
MapiID: | 0x8175
Heuristics: | 18


X121-Address

AttName: X121-Address

LDAPName: | x121Address
Boot: | FALSE
Space: | x500
AttID: | 24 (24, \x550418)
SyntaxName: | String(Numeric)
MinLen: | 1
MaxLen: | 15
Multi: | TRUE
Acl: | Admin
MapiID: | 0x8158
Heuristics: | 18


X25-Call-User-Data-Incoming

AttName: X25-Call-User-Data-Incoming

LDAPName: | X25-Call-User-Data-Incoming
Boot: | FALSE
Space: | ms
AttID: | 131388 (316, \x2A864886F7140102823C)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8159
Heuristics: | 12


X25-Call-User-Data-Outgoing

AttName: X25-Call-User-Data-Outgoing

LDAPName: | X25-Call-User-Data-Outgoing
Boot: | FALSE
Space: | ms
AttID: | 131389 (317, \x2A864886F7140102823D)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 128
Multi: | FALSE
Acl: | Admin
MapiID: | 0x815A
Heuristics: | 12


X25-Facilities-Data-Incoming

AttName: X25-Facilities-Data-Incoming

LDAPName: | X25-Facilities-Data-Incoming
Boot: | FALSE
Space: | ms
AttID: | 131390 (318, \x2A864886F7140102823E)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 109
Multi: | FALSE
Acl: | Admin
MapiID: | 0x815B
Heuristics: | 12


X25-Facilities-Data-Outgoing

AttName: X25-Facilities-Data-Outgoing

LDAPName: | X25-Facilities-Data-Outgoing
Boot: | FALSE
Space: | ms
AttID: | 131391 (319, \x2A864886F7140102823F)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 109
Multi: | FALSE
Acl: | Admin
MapiID: | 0x815C
Heuristics: | 12


X25-Leased-Line-Port

AttName: X25-Leased-Line-Port

LDAPName: | X25-Leased-Line-Port
Boot: | FALSE
Space: | ms
AttID: | 131393 (321, \x2A864886F71401028241)
SyntaxName: | String(Octet)
MinLen: | 1
MaxLen: | 3
Multi: | FALSE
Acl: | Admin
MapiID: | 0x815D
Heuristics: | 4


X25-Leased-or-Switched

AttName: X25-Leased-or-Switched

LDAPName: | X25-Leased-or-Switched
Boot: | FALSE
Space: | ms
AttID: | 131444 (372, \x2A864886F71401028274)
SyntaxName: | Boolean
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | Admin
MapiID: | 0x815E
Heuristics: | 12


X25-Remote-MTA-Phone

AttName: X25-Remote-MTA-Phone

LDAPName: | X25-Remote-MTA-Phone
Boot: | FALSE
Space: | ms
AttID: | 131445 (373, \x2A864886F71401028275)
SyntaxName: | String(Printable)
MinLen: | 1
MaxLen: | 55
Multi: | FALSE
Acl: | Admin
MapiID: | 0x815F
Heuristics: | 12


X400-Attachment-Type

AttName: X400-Attachment-Type

LDAPName: | X400-Attachment-Type
Boot: | FALSE
Space: | ms
AttID: | 131171 (99, \x2A864886F714010263)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
Acl: | User
MapiID: | 0x8160
Heuristics: | 12


X400-Selector-Syntax

AttName: X400-Selector-Syntax

LDAPName: | X400-Selector-Syntax
Boot: | FALSE
Space: | ms
AttID: | 131515 (443, \x2A864886F7140102833B)
SyntaxName: | Enumeration
MinLen: | 0
MaxLen: | 1
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8161
Heuristics: | 12


X500-Access-Control-List

AttName: X500-Access-Control-List

LDAPName: | X500-Access-Control-List
Boot: | TRUE
Space: | ms
AttID: | 131505 (433, \x2A864886F71401028331)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | FALSE
MapiID: | 0x8162
Heuristics: | 12


X500-NC

AttName: X500-NC

LDAPName: | dnQualifier
Boot: | FALSE
Space: | ms
AttID: | 131581 (509, \x2A864886F7140102837D)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 1024
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81A2
Heuristics: | 13


X500-RDN

AttName: X500-RDN

LDAPName: | X500-RDN
Boot: | FALSE
Space: | ms
AttID: | 131580 (508, \x2A864886F7140102837C)
SyntaxName: | String(Unicode)
MinLen: | 1
MaxLen: | 256
Multi: | FALSE
Acl: | Admin
MapiID: | 0x81A1
Heuristics: | 13


X509-Cert

AttName: X509-Cert

LDAPName: | userCertificate
Boot: | FALSE
Space: | ms
AttID: | 131533 (461, \x2A864886F7140102834D)
SyntaxName: | String(Octet)
MinLen: | (none)
MaxLen: | (none)
Multi: | TRUE
Acl: | User
MapiID: | 0x8C6A
Heuristics: | 18


XMIT-Timeout-Non-Urgent

AttName: XMIT-Timeout-Non-Urgent

LDAPName: | XMIT-Timeout-Non-Urgent
Boot: | FALSE
Space: | ms
AttID: | 131156 (84, \x2A864886F714010254)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8163
Heuristics: | 12


XMIT-Timeout-Normal

AttName: XMIT-Timeout-Normal

LDAPName: | XMIT-Timeout-Normal
Boot: | FALSE
Space: | ms
AttID: | 131139 (67, \x2A864886F714010243)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8164
Heuristics: | 12


XMIT-Timeout-Urgent

AttName: XMIT-Timeout-Urgent

LDAPName: | XMIT-Timeout-Urgent
Boot: | FALSE
Space: | ms
AttID: | 131125 (53, \x2A864886F714010235)
SyntaxName: | Integer
MinLen: | 0
MaxLen: | 32767
Multi: | FALSE
Acl: | Admin
MapiID: | 0x8165
Heuristics: | 12


Interfaces

Most Microsoft Exchange Server interfaces are available through the MAPI extensibility mechanism for objects. To access an object with an interface other than a standard MAPI interface, you typically call the MAPI IMAPIProp::OpenProperty method and pass the appropriate property.

For example, you can obtain a stream interface on a message property such as PR_BODY. Call OpenProperty and specify the MAPI PR_BODY property and the Win32 IStream interface.

The Microsoft Exchange Server SDK contains the following functions that obtain a pointer to an interface:

  • HrFolderACLsOpen This function gets a pointer to an IExchangeFolderACLs interface object.
  • HrFolderRulesOpen This function gets a pointer to an IExchangeFolderRules interface object.

For additional information on getting a pointer to an interface, see Obtaining Microsoft Exchange Server Interfaces.


Microsoft Exchange Server Interfaces

The Microsoft Exchange Server interface inheritance hierarchy is simple and straightforward. All Microsoft Exchange Server objects inherit directly from the Win32 IUnknown interface.

For complete information on the IUnknown methods AddRef, QueryInterface, and Release, see the Win32 Programmer's Reference.


Microsoft Exchange Server Interfaces and Methods

Microsoft Exchange Server interfaces, header files, and methods are as follows:

IExchangeExportChanges (EDKMDB.H)
Config
GetLastError
Synchronize
UpdateState
IExchangeFavorites (EDKMDB.H)
AddFavorites
DelFavorites
GetLastError
IExchangeFolderACLs (ACLCLS.H)
HrDelete
HrGet
HrInsert
HrModify
HrSeek
HrTell
IExchangeFolderRules (RULECLS.H)
HrDelete
HrDisable
HrEnable
HrGet
HrInsert
HrSeek
HrTell
IExchangeImportContentsChanges (EDKMDB.H)
Config
GetLastError
ImportMessageChange
ImportMessageDeletion
ImportMessageMove
ImportPerUserReadStateChange
UpdateState
IExchangeImportHierarchyChanges (EDKMDB.H)
Config
GetLastError
ImportFolderChange
ImportFolderDeletion
UpdateState
IExchangeManageStore (EDKMDB.H)
CreateStoreEntryID
EntryIDFromSourceKey
GetMailboxTable
GetPublicFolderTable
GetRights
IExchangeModifyTable (EDKMDB.H)
GetLastError
GetTable
ModifyTable
IExchangeRuleAction (EDKMDB.H)
ActionCount
GetAction
IExchangeRuleExt (EXCHCLI.H)
Command
GetCommand
Install
QueryCommandDisplayName
QueryRelease
IExchangeRuleExtCallback (EXCHCLI.H)


Calling Microsoft Exchange Server Methods Using C

The Microsoft Exchange Server interfaces are documented using C++ conventions. If you need to call a Microsoft Exchange Server object from a C program, you must supply a pointer to the calling object as an additional, initial argument to the method. See the MAPI Programmer's Reference for more information.


IExchangeExportChanges

The IExchangeExportChanges interface supports the exporting of incremental changes from an information store.

Quick Info

Header file: | EDKMDB.H
Exposed by: | Information store (not personal folder store (PST) or offline folder store (OST)) objects
Corresponding pointer type: | LPEXCHANGEEXPORTCHANGES

Vtable Order

GetLastError

Config

Synchronize

UpdateState

Remarks

To obtain this interface, the controlling process (agent) must open the information store and call the MAPI IMAPIProp::OpenProperty method on either the PR_CONTENTS_SYNCHRONIZER property (to synchronize the contents of a folder) or the PR_HIERARCHY_SYNCHRONIZER property (to synchronize the hierarchy of a folder).

When calling the OpenProperty method, pass the value IID_IExchangeExportChanges in the lpiid parameter.

For additional information on this interface, see About Incremental Change Synchronization.


IExchangeExportChanges::Config

The Config method initializes the synchronization process (synchronizer) in preparation to export changes to the collection process (collector).

HRESULT Config(
  LPSTREAM lpStream,
  ULONG ulFlags,
  LPUNKNOWN lpCollector,
  LPSRestriction lpRestriction,
  LPSPropTagArray lpIncludeProps,
  LPSPropTagArray lpExcludeProps,
  ULONG ulBufferSize
);

Parameters

lpStream
Input parameter. Points to a Win32 IStream interface, which contains the current synchronization state. The state information is binary and specific to this synchronization/collection session.
ulFlags
Input parameter. Defined flags that control the synchronizer:
SYNC_UNICODE
Specifies that text is Unicode. If this flag is not set, the text is returned as the type of text in the client's code page.
SYNC_NO_DELETIONS
Specifies that the synchronizer does not export deletions.
SYNC_READ_STATE
Specifies that the synchronizer exports the MAPI PR_CONTENT_UNREAD property for folders and the MAPI PR_MESSAGE_FLAGS property for messages. This flag only makes sense for information stores that maintain a per-user read state.
SYNC_ASSOCIATED
Specifes that the synchronizer only exports folder associated information (FAI) messages. Typically, FAI messages represent forms and views.
SYNC_NORMAL
Specifies that the synchronizer only exports non-FAI messages.
lpCollector
Input parameter. Points to a Win32 IUnknown interface object that support either the IExchangeImportHierarchyChanges interface or the IExchangeImportContentsChanges interface. This parameter cannot be NULL.
lpRestriction
Input parameter. Set this parameter to NULL.
lpIncludeProps
Input parameter. Points to a SPropTagArray structure, which can contain the MAPI PR_MESSAGE_SIZE or MAPI PR_ENTRYID properties (it can contain both of these properties). These properties are exported in addition to the properties that are normally exported.
lpExcludeProps
Input parameter. Points to a SPropTagArray structure, which contains an array of property tags. These properties are excluded from the properties that are normally exported.
ulBufferSize
Input parameter. Specifies the size, in bytes, of the bufffer that the synchronizer uses to receive information from the collector. If this parameter is zero, Config uses the default buffer size. Microsoft recommends using the default buffer size.

Return Values

See Return Values. In addition, Config can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.
SYNC_E_UNKNOWN_FLAGS
One of the flags was not valid.

Remarks

The Config method is called once by the agent to initialize the synchronizer.

If neither the SYNC_ASSOCIATED nor the SYNC_NORMAL flag is set, no folder contents are synchronized.

See Also

IExchangeExportChanges


IExchangeExportChanges::GetLastError

The GetLastError method retrieves information about the most recent error during importing the incremental message changes.

HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult
Input parameter. An error returned by one of the other IExchangeImportContentsChanges methods.
ulFlags
Input parameter. Defined flag that controls the format of the error report:
SYNC_UNICODE
Specifies that text is Unicode. If this flag is not set, the text is returned as the type of text in the clients' code page.
lppMAPIError
Output parameter. Points to the address of a MAPI MAPIERROR structure, which contains information on the last error.

Return Values

See Return Values.

In addition, GetLastError can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

See Also

IExchangeExportChanges


IExchangeExportChanges::Synchronize

The Synchronize method exports a single incremental change from the synchronizer to the collector.

HRESULT Synchronize(
  ULONG FAR * pulSteps,
  ULONG FAR * pulProgress
);

Parameters

pulSteps
Output parameter. Points to a ULONG that holds the total number of steps needed to synchronize.
pulProgress
Output parameter. Points to a ULONG that holds the number of incremental changes that have been made.

Return Values

See Return Values.

In addition, Synchronize can return one of the following values:

SUCCESS_SUCCESS
Synchronization is complete.
SYNC_W_PROGRESS
Synchronization is in progress.

Remarks

The Synchronize method exports the incremental changes in small, atomic steps. After any Synchronize call, the agent can interrupt the process, update and save the state of the process with IExchangeExportChanges::UpdateState, close the Win32 IStream interface that was opened with IExchangeExportChanges::Config, and resume the process later.

See Also

IExchangeExportChanges, IExchangeExportChanges::Config, IExchangeExportChanges::UpdateState


IExchangeExportChanges::UpdateState

The UpdateState method updates the status of exporting the incremental changes.

HRESULT UpdateState(
  LPSTREAM lpStream
);

Parameters

lpStream
Input parameter. Points to a Win32 IStream interface, which contains the current synchronization state. If this parameter is NULL, the agent uses the IStream interface from IExchangeExportChanges::Config.

The agent must use a different IStream interface if it is going to shut down and resume later, or if it is checkpointing the progress of the incremental change synchronization.

Return Values

See Return Values.

In addition, UpdateState can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.

See Also

IExchangeExportChanges


IExchangeFavorites

The IExchangeFavorites interface supports the addition and deletion of public information store folders in a user's Favorites folder.

Quick Info

Header file: | EDKMDB.H
Exposed by: |
Corresponding pointer type: | LPEXCHANGEFAVORITES

Vtable Order

GetLastError

AddFavorites

DelFavorites

Remarks

To get a pointer to the IExchangeFavorites interface, call the MAPI IMAPIProp::GetProps method with the PR_IPM_FAVORITES_ENTRYID property and then the MAPI IMsgStore::OpenEntry method with that entry identifier.

When calling the OpenEntry method, pass the value IID_IExchangeFavorites in the lpInterface parameter.

For additional information on this interface, see Working with the Favorites Folder.


IExchangeFavorites::AddFavorites

The AddFavorites method adds one or more public folders to a user's Favorites folder.

HRESULT AddFavorites(
  LPENTRYLIST lpEntryList
);

Parameters

lpEntryList
Input parameter. Points to a MAPI ENTRYLIST structure, which contains the list of public folders to add to the Favorites folder.

Return Values

See Return Values.

In addition, AddFavorites can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters (folders) was not valid.

Remarks

The AddFavorites method exits without processing the rest of the list and returns SYNC_E_INVALID_PARAMETER if one of the folders in the entry list is not a public folder that can be added to the user's Favorites folder.

See Also

IExchangeFavorites, IExchangeFavorites::DelFavorites


IExchangeFavorites::DelFavorites

The DelFavorites method removes one or more folders from a user's Favorites folder.

HRESULT DelFavorites(
  LPENTRYLIST lpEntryList
);

Parameters

lpEntryList
Input parameter. Points to a MAPI ENTRYLIST structure, which contains the list of folders to remove to the Favorites folder. Note that this list contains the entry identifiers of the folders in the Favorites folder, not the entry identifiers of the public folders.

Return Values

See Return Values.

In addition, DelFavorites can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters (folders) was not valid.

Remarks

The DelFavorites method exits without processing the rest of the list and returns SYNC_E_INVALID_PARAMETER if one of the folders in the entry list is not a folder that can be removed from the user's Favorites folder.

See Also

IExchangeFavorites, IExchangeFavorites::AddFavorites


IExchangeFavorites::GetLastError

The GetLastError method obtains further information about an error condition.

HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult
Input parameter. The error that was received.
ulFlags
Input parameter. Defined flag that controls the type of text returned in lppMAPIError:
MAPI_UNICODE
Specifies that text is Unicode. If this flag is not set, the text is returned as the type of text in the clients' code page.
lppMAPIError
Output parameter. Points to the address of a MAPI MAPIERROR structure, which contains information on the last error.

Return Values

See Return Values.

In addition, GetLastError can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

See Also

IExchangeFavorites


IExchangeFolderACLs

The IExchangeFolderACLs interface supports modifying a public folder's Access Control List (ACL).

Quick Info

Header file: | ACLCLS.H
Exposed by: |
Corresponding pointer type: | LPFOLDERACLS

Vtable Order

HrDelete

HrGet

HrInsert

HrModify

HrSeek

HrTell

Remarks

To get a pointer to this interface, call the HrFolderACLsOpen function.

For additional information on this interface, see Manipulating ACLs.


IExchangeFolderACLs::HrDelete

The HrDelete method removes the current member of the ACL.

HRESULT HrDelete( )

Parameters

None.

Return Values

See Return Values.

In addition, HrDelete returns E_FAIL if one of the following conditions occurs:

An attempt was made to delete the default rights of the folder.
The current cursor position, as returned by the HrTell method, is ACL_POS_DEFAULT.
An attempt was made to delete the owner of the folder.
The current cursor position, as returned by the HrTell method, is ACL_POS_CREATOR.
An attempt was made to delete a member when the cursor is at the end of the ACL table (no current member).
The current cursor position, as returned by the HrTell method, is ACL_PAST_END.

Remarks

Microsoft Exchange Server reserves the first two members of every ACL for the default access rights of the list and the creator of the list. You cannot delete the access rights member or the creator member of an ACL. You cannot insert a member before the access rights member or the creator member of an ACL.

For more information, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs


IExchangeFolderACLs::HrGet

The HrGet method retrieves the access rights for the current member of the ACL and advances the cursor to the next member of the ACL.

HRESULT HrGet(
  LPLONG lplRights,
  LPSTR FAR * lppszDisplayName,
  ULONG FAR * lpcbentryid,
  LPENTRYID FAR * lppentyrid
);

Parameters

lplRights
Output parameter. Points to a LONG variable to hold the ACL rights:
frightsReadAny
The user can read any message in the folder.
frightsCreate
The user can create a message in the folder.
frightsEditOwned
The user can edit any message that they own in the folder.
frightsDeleteOwned
The user can delete any message that they own in the folder.
frightsEditAny
The user can edit any message in the folder.
frightsDeleteAny
The user can delete any message in the folder.
frightsCreateSubfolder
The user can create a subfolder in the folder.
frightsOwner
The user owns the folder.
frightsContact
The user is the contact person for the folder. Note: This is not part of rightsAll.
rightsNone
The user has no rights in the folder
rightsReadOnly
The user can only read messages in the folder. Equivalent to frightsReadAny.
rightsReadWrite
The user can read or edit any message in the folder. Equivalent to frightsReadAny | frightsEditAny.
rightsAll
The user has all rights on the folder.
lppszDisplayName
Output parameter. Points to a string containing the display name of the current member of the ACL.
lpcbentryid
Output parameter. Points to the size, in bytes, of the ENTRYID where lppentyrid points.
lppentyrid
Output parameter. Points to a MAPI ENTRYID structure that contains the entry identifier of the current member of the ACL.

Return Values

See Return Values.

Remarks

The calling routine must allocate and release the space for the LONG variable where lplRights points and for the ENTRYID structure where lpcbentryid points.

For more information, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs


IExchangeFolderACLs::HrInsert

The HrInsert method inserts a user as a new member of the ACL with a set of access rights.

HRESULT HrInsert(
  LONG lRights,
  LPSTR lpszDisplayName,
  ULONG cbentryid,
  LPENTRYID lpentryid,
  LPLONG lplRights
);

Parameters

lRights
Input parameter. Points to the access rights that are requested for the new member.
frightsReadAny
The user can read any message in the folder.
frightsCreate
The user can create a message in the folder.
frightsEditOwned
The user can edit any message that they own in the folder.
frightsDeleteOwned
The user can delete any message that they own in the folder.
frightsEditAny
The user can edit any message in the folder.
frightsDeleteAny
The user can delete any message in the folder.
frightsCreateSubfolder
The user can create a subfolder in the folder.
frightsOwner
The user owns the folder.
frightsContact
The user is the contact person for the folder. Note: This is not part of rightsAll.
rightsNone
The user has no rights in the folder
rightsReadOnly
The user can only read messages in the folder. Equivalent to frightsReadAny.
rightsReadWrite
The user can read or edit any message in the folder. Equivalent to frightsReadAny | frightsEditAny.
rightsAll
The user has all rights on the folder.
lpszDisplayName
Input parameter. Points to a string containing the display name of the new member.
cbentryid
Input parameter. The size, in bytes, of the entry id where lpentryid points.
lpentryid
Input parameter. Points to a MAPI ENTRYID structure containing the address book entry identifier of the user for whom the ACL entry is being created.
lplRights
Output parameter. Points to a LONG value containing the rights granted to the new member of the ACL.

Return Values

See Return Values.

In addition, HrInsert returns E_FAIL if one of the following conditions occur:

An attempt was made to insert a new member before the default rights of the folder.
The current cursor position, as returned by the HrTell method, is ACL_POS_DEFAULT.
An attempt was made to insert a new member before the owner of the folder.
The current cursor position, as returned by the HrTell method, is ACL_POS_CREATOR.
An attempt was made to insert a new member who is already a member of the ACL.
The member identified by the lppentryid parameter is the same as a member identified by looping through the ACL, beginning at ACL_POS_CREATOR by using the HrSeek method, examining the current member using the HrGet method's lppentryid output parameter, until a matching member is found (if the member isn't in the list, the HrTell method returns ACL_PAST_END).

Remarks

If HrInsert returns NOERROR, the new user is inserted into the current position in the ACL, and the current position is advanced. Microsoft Exchange Server reserves the first two members of every ACL for the default access rights of the list and the creator of the list. You can neither insert a member before these two members nor delete either member.

Rights that are granted may not be the same as the rights that were requested because some rights may not be allowed and the Microsoft Exchange Server information store often sets extra bits.

New members have only default rights on the folder. To change that, use the HrModify method.

To obtain the entry identifier for the lpentryid parameter, use the MAPI IAdrBook::ResolveName method.

For more information, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs


IExchangeFolderACLs::HrModify

The HrModify method sets the access rights for the current member of the ACL.

HRESULT HrModify(
  LONG lRights,
  LPLONG lplRights
);

Parameters

lRights
Input parameter. The rights that are requested for the current member of the ACL:
frightsReadAny
The user can read any message in the folder.
frightsCreate
The user can create a message in the folder.
frightsEditOwned
The user can edit any message that they own in the folder.
frightsDeleteOwned
The user can delete any message that they own in the folder.
frightsEditAny
The user can edit any message in the folder.
frightsDeleteAny
The user can delete any message in the folder.
frightsCreateSubfolder
The user can create a subfolder in the folder.
frightsOwner
The user owns the folder.
frightsContact
The user is the contact person for the folder. Note: This is not part of rightsAll.
rightsNone
The user has no rights in the folder.
rightsReadOnly
The user can only read messages in the folder. Equivalent to frightsReadAny.
rightsReadWrite
The user can read or edit any message in the folder. Equivalent to frightsReadAny | frightsEditAny.
rightsAll
The user has all rights on the folder.
lplRights
Input and output parameter. Points to a LONG value containing the rights granted to the current member of the ACL. If you aren't concerned about whether the granted rights are the same as the requested rights, set this value to NULL.

Return Values

See Return Values.

Remarks

Rights that are granted may not be the same as the rights that were requested because some rights may not be allowed and the Microsoft Exchange Server information store often sets extra bits.

You can change the default rights given to all new members of the folder when they are added to the ACL by using this method and setting the rights of the default rights member of the ACL. Use the HrSeek method with the ACL_POS_DEFAULT argument to select the default rights member of the ACL.

The owner of the folder initially has only default rights on the folder. Use the HrSeek method with the ACL_POS_CREATOR argument to select the owner of the ACL.

For more information, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs


IExchangeFolderACLs::HrSeek

The HrSeek method sets the current cursor position.

HRESULT HrSeek(
  LONG lPos
);

Parameters

lPos
Input parameter. The cursor position to be set. The following positions are defined:
ACL_POS_DEFAULT
The default rights of the folder.
ACL_POS_CREATOR
The owner of the folder.

Return Values

See Return Values.

In addition, HrSeek fails with E_INVALIDARG if lPos is less than ACL_PAST_END.

Remarks

For more information on ACLs, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs


IExchangeFolderACLs::HrTell

The HrTell method retrieves the current cursor position.

HRESULT HrTell(
  LPLONG lplPos
);

Parameters

lplPos
Output parameter. The current cursor position. The following cursor positions are defined:
ACL_POS_DEFAULT
The default rights on the folder.
ACL_POS_CREATOR
The owner of the folder.
ACL_PAST_END
You've reached the end of the ACL.

Return Values

See Return Values.

Remarks

For more information, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs


IExchangeFolderRules

The IExchangeFolderRules interface supports modifying a folder's rules.

Quick Info

Header file: | RULECLS.H
Exposed by: |
Corresponding pointer type: | LPFOLDERRULES

Vtable Order

HrDelete

HrDisable

HrEnable

HrGet

HrInsert

HrSeek

HrTell

Remarks

For additional information on this interface, see Creating a Rule. To obtain this interface, call the HrFolderRulesOpen function.


IExchangeFolderRules::HrDelete

The HrDelete method removes the current rule from the folder.

HRESULT HrDelete(
  VOID
);

Parameters

None.

Return Values

See Return Values.

Also, HrDelete returns E_FAIL if one of the following conditions occurs:

An attempt was made to delete a rule when the cursor is at the end of the rules table (no current member).
The current cursor position, as returned by the HrTell method, is RULE_PAST_END.

In addition, when creating, modifying, or deleting rules, the MAPI_W_PARTIAL_SUCCESS error is returned if at least one rule operation (create, modify, or delete) is successful, but not all the operations are successful. A rule operation fails under the following circumstances:

  1. The rule condition is invalid.
  2. The rule action is missing or invalid.
  3. A non-string property type has been given for a rule provider name or a rule name.
  4. A rule property is invalid.

Remarks

If you only want to disable the rule, use the HrDisable method. You can then later enable the rule with the HrEnable method.

For more information, see RULEEDIT: Manipulating Rules.

See Also

IExchangeFolderRules


IExchangeFolderRules::HrDisable

The HrDisable method disables the current rule on the folder.

HRESULT HrDisable(
  VOID
);

Parameters

None.

Return Values

See Return Values.

In addition, HrDisable returns E_FAIL if one of the following conditions occurs:

An attempt was made to disable a rule when the cursor is at the end of the rules table (no current member).
The current cursor position, as returned by the HrTell method, is RULE_PAST_END.

Remarks

You can enable the rule with the HrEnable method. If you want to delete the rule, use the HrDelete method.

For more information, see RULEEDIT: Manipulating Rules.

See Also

IExchangeFolderRules


IExchangeFolderRules::HrEnable

The HrEnable method enables the current rule on a folder.

HRESULT HrEnable(
  VOID
);

Parameters

None.

Return Values

See Return Values.

In addition, HrEnable returns E_FAIL if one of the following conditions occurs:

An attempt was made to enable a rule when the cursor is at the end of the rules table (no current member).

The current cursor position, as returned by the HrTell method, is RULE_PAST_END.

Remarks

Use the HrEnable method to enable a rule that was previously disabled by the HrDisable method. HrEnable does not return an error if the rule is not disabled. Use the HrGet method to obtain the status of the rule.

For additional information, see RULEEDIT: Manipulating Rules

See Also

IExchangeFolderRules


IExchangeFolderRules::HrGet

The HrGet method retrieves the current rule on the folder.

HRESULT HrGet(
  LPLONG lplState,
  LPSRestriction FAR * lppRestriction,
  LPACTIONS FAR * lppActions,
  LPLONG lplLevel,
  LPSTR FAR * lppszName
);

Parameters

lplState
Output parameter. Points to a LONG value containing the rule state.
lppRestriction
Output parameter. Points to a MAPI SRestriction structure containing the conditions for the rule.
lppActions
Output parameter. Points to an ACTIONS structure containing the actions for the rule.
lplLevel
Output parameter. Points to a LONG value containing the nesting level of the rule.
lppszName
Output parameter. Points to a string containing the name of the rule.

Return Values

See Return Values.

In addition, HrGet returns E_FAIL if one of the following conditions occurs:

An attempt was made to retrieve a rule when the cursor is at the end of the rules table (no current member).
The current cursor position, as returned by the HrTell method, is RULE_PAST_END.

Remarks

The calling program must allocate space for the variables where the lplState and lplLevel parameters point.

For additional information, see RULEEDIT: Manipulating Rules.

See Also

ACTIONS, IExchangeFolderRules


IExchangeFolderRules::HrInsert

The HrInsert method inserts a new rule into the set of rules for the folder.

HRESULT HrInsert(
  LONG lState,
  LPSRestriction lpRestriction,
  LPACTIONS lpActions,
  LONG lLevel,
  LPSTR lpszName
);

Parameters

lState
Input parameter. Points to a LONG value containing the rule state.
lpRestriction
Input parameter. Points to a MAPI SRestriction structure containing the conditions for the rule.
lpActions
Input parameter. Points to an ACTIONS structure containing the actions for the rule.
lLevel
Input parameter. Points to a LONG value containing the nesting level of the rule.
lpszName
Input parameter. Points to a string containing the name of the rule.

Return Values

See Return Values.

When creating, modifying, or deleting rules, the MAPI_W_PARTIAL_SUCCESS error is returned if at least one rule operation (create, modify, or delete) is successful, but not all the operations are successful. A rule operation fails under the following circumstances:

  1. The rule condition is invalid.
  2. The rule action is missing or invalid.
  3. A non-string property type has been given for a rule provider name or a rule name.
  4. A rule property is invalid.

Remarks

For additional information, see RULEEDIT: Manipulating Rules.

See Also

ACTIONS, IExchangeFolderRules


IExchangeFolderRules::HrSeek

The HrSeek method sets the current cursor position.

HRESULT HrSeek(
  LONG lpos
);

Parameters

lpos
Input parameter. The cursor position to be set.

Return Values

See Return Values.

In addition, HrSeek fails with E_INVALIDARG if lPos is less than ACL_PAST_END.

Remarks

For additional information, see RULEEDIT: Manipulating Rules.

See Also

IExchangeFolderRules


IExchangeFolderRules::HrTell

The HrTell method retrieves the current cursor position.

HRESULT HrTell(
  LPLONG lplPos
);

Parameters

lplPos
Output parameter. The current cursor position. The following cursor position is defined:
RULE_PAST_END
The end of the rules has been reached.

Return Values

See Return Values.

Remarks

For additional information, see RULEEDIT: Manipulating Rules.

See Also

IExchangeFolderRules


IExchangeImportContentsChanges

The IExchangeImportContentsChanges interface supports the importing of message (contents) changes into an information store. In an ICS application, this interface is used in conjunction with the IExchangeImportHierarchyChanges interface by the collector.

Quick Info

Header file: | EDKMDB.H
Exposed by: | Information store (not personal folder store (PST) or offline folder store (OST)) objects
Corresponding pointer type: | LPEXCHANGEIMPORTCONTENTSCHANGES

Vtable Order

GetLastError

Config

UpdateState

ImportMessageChange

ImportMessageDeletion

ImportPerUserReadStateChange

ImportMessageMove

Remarks

To obtain this interface, the agent must open the information store and call the MAPI IMAPIProp::OpenProperty method on the PR_COLLECTOR property of the object.

When calling the OpenProperty method, pass the value IID_IExchangeImportContentsChanges in the lpiid parameter.

For additional information on this interface, see About Incremental Change Synchronization.


IExchangeImportContentsChanges::Config

The Config method initializes the collector in preparation to import changes from the synchronizer.

HRESULT Config(
  LPSTREAM * lpStream,
  ULONG ulFlags
);

Parameters

lpStream
Input parameter. Points to an open Win32 IStream interface. For unidirectional synchronization, this parameter is usually NULL.
ulFlags
Input parameter. Set this parameter to NULL, as this parameter is ignored.

Return Values

See Return Values.

In addition, Config can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.
SYNC_E_UNKNOWN_FLAGS
One of the flags was not valid.

Remarks

The agent calls this method once to initialize the collector. Some collectors can use the Win32 IStream interface where the lpStream parameter points to maintain a cross-reference of source keys and their corresponding internal identifiers. Maintaining this cross-reference enables more efficient deletions when an object is created and deleted before synchronization occurs.

See Also

IExchangeImportContentsChanges


IExchangeImportContentsChanges::GetLastError

The GetLastError method retrieves information about the most recent error during importing the incremental message changes.

HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult
Input parameter. An error returned by one of the other IExchangeImportContentsChanges methods.
ulFlags
Input parameter. Defined flag that controls the format of the error report:
SYNC_UNICODE
Specifies that text is Unicode. If this flag is not set, the text is returned as the type of text in the clients' code page.
lppMAPIError
Points to the address of a MAPI MAPIERROR structure, which contains information on the last error.

Return Values

See Return Values.

In addition, GetLastError can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

See Also

IExchangeImportContentsChanges


IExchangeImportContentsChanges::ImportMessageChange

The ImportMessageChange method accepts a message change notification from the synchronizer.

HRESULT ImportMessageChange(
  ULONG cValue,
  LPSPropValue lpPropArray,
  ULONG ulFlags,
  LPMESSAGE * lppMessage
);

Parameters

cValue
Input parameter. The number of MAPI SPropValue array elements in lpPropArray.
lpPropArray
Input parameter. Points to an array of SPropValue structures, each of which contains a property tag and its value.

The array must contain at least the PR_SOURCE_KEY, PR_CHANGE_KEY, and PR_PREDECESSOR_CHANGE_LIST properties.

ulFlags
Input parameter. Defined flags that control the collector:
SYNC_ASSOCIATED
Specifes that the synchronizer only exports folder associated information (FAI) messages. Typically, FAI messages represent forms and views.
lppMessage
Output parameter. Points to a MAPI IMessage interface that can receive an open message object. The synchronizer can set additional properties on this object by using the MAPI IMAPIProp::SetProps method or through an OLE stream.

Return Values

See Return Values.

In addition, ImportMessageChange can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_CONFLICT
A conflict has occurred.
SYNC_E_ERROR
An unknown error occurred.
SYNC_OBJECT_DELETED
The object has been deleted.

Remarks

The ImportMessageChange method is called by the synchronizer for each message that is created or modified. This method should not be called from the agent.

Collector implementers need only provide the MAPI IMAPIProp::SetProps method, the MAPI IMAPIProp::SaveChanges method, and the Win32 IUnknown interface.

See Also

IExchangeImportContentsChanges


IExchangeImportContentsChanges::ImportMessageDeletion

The ImportMessageDeletion method accepts a message deletion notification from the synchronizer.

HRESULT ImportMessageDeletion(
  ULONG ulFlags,
  LPENTRYLIST lpSourceEntryList
);

Parameters

ulFlags
Input parameter. Set this parameter to zero, as this parameter is ignored. lpSourceEntryList

Input parameter. Points to a MAPI ENTRYLIST structure, which contains the list of SOURCE_KEY properties that identify the messages to delete. This parameter cannot be NULL; if you pass a NULL value, ImportMessageDeletion raises an exception.

Return Values

See Return Values.

In addition, ImportMessageDeletion can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.

Remarks

The ImportMessageDeletion method is called by the synchronizer for each message that is deleted. This method should not be called from the agent.

If one of the source key properties in the entry list is not a valid source key property, ImportMessageDeletion exits without processing the rest of the list and returns SYNC_E_INVALID_PARAMETER.

See Also

IExchangeImportContentsChanges, IExchangeImportHierarchyChanges::ImportFolderDeletion


IExchangeImportContentsChanges::ImportMessageMove

The ImportMessageMove method transfers a message from one folder to another.

HRESULT ImportMessageMove(
  ULONG cbSourceKeySrcFolder,
  BYTE FAR * pbSourceKeySrcFolder,
  ULONG cbSourceKeySrcMessage,
  BYTE FAR * pbSourceKeySrcMessage,
  ULONG cbPCLMessage,
  BYTE FAR * pbPCLMessage,
  ULONG cbSourceKeyDestMessage,
  BYTE FAR * pbSourceKeyDestMessage,
  ULONG cbChangeNumDestMessage,
  BYTE FAR * pbChangeNumDestMessage
);

Parameters

cbSourceKeySrcFolder
Input parameter. The length, in bytes, of the key contained in pbSourceKeySrcFolder.
pbSourceKeySrcFolder
Input parameter. Points to a key of type PR_SOURCE_KEY that identifies the parent folder for this message.
cbSourceKeySrcMessage
Input parameter. The length, in bytes, of the key contained in pbSourceKeySrcMessage.
pbSourceKeySrcMessage
Input parameter. Points to a key of type PR_SOURCE_KEY that identifies this message.
cbPCLMessage
Input parameter. The length, in bytes, of the key contained in pbPCLMessage.
pbPCLMessage
Input parameter. Points to a key of type PR_PREDECESSOR_CHANGE_LIST that contains the change list for this message.
cbSourceKeyDestMessage
Input parameter. The length, in bytes, of the key contained in pbSourceKeyDestMessage.
pbSourceKeyDestMessage
Input parameter. Points to a key of type PR_SOURCE_KEY that identifies this message after the change.
cbChangeNumDestMessage
Input parameter. The length, in bytes, of the key contained in pbChangeNumDestMessage.
pbChangeNumDestMessage
Input parameter. Points to a key of type PR_CHANGE_KEY that identifies this change.

Return Values

See Return Values.

In addition, ImportMessageMove can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.

Remarks

The ImportMessageMove method is used by the collector to move a message, instead of having to delete the message and recreate it under a different parent.

See Also

IExchangeImportContentsChanges, IExchangeImportHierarchyChanges::ImportFolderChange


IExchangeImportContentsChanges::ImportPerUserReadStateChange

The ImportPerUserReadStateChange method toggles the read state of a list of messages.

HRESULT ImportPerUserReadStateChange(
  ULONG cElements,
  LPREADSTATE lpReadState
);

Parameters

cElements
Input parameter. The number of READSTATE array elements in lpReadState.
lpReadState
Input parameter. Points to an array of READSTATE structures, each of which contains a PR_SOURCE_KEY property that identifies the messages whose read state has changed.

Return Values

See Return Values.

In addition, ImportPerUserReadStateChange can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.

Remarks

The ImportPerUserReadStateChange method is called by the synchronizer for each message that is changed. This method should not be called from the agent.

See Also

IExchangeImportContentsChanges, PR_SOURCE_KEY, READSTATE


IExchangeImportContentsChanges::UpdateState

The UpdateState method updates the status of importing the incremental message changes.

HRESULT UpdateState(
  LPSTREAM lpStream
);

Parameters

lpStream
Input parameter. Points to a Win32 IStream interface, which is where the state data is stored. Typically this parameter points to the interface opened by the IExchangeExportChanges::Config method. UpdateState also uses this interface if this parameter is NULL.

Return Values

See Return Values.

In addition, UpdateState can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.

Remarks

The agent must use a different Win32 IStream interface if it's going to shut down and resume later, or if it's checkpointing the progress of the incremental change synchronization.

See Also

IExchangeExportChanges::Config, IExchangeImportContentsChanges, IExchangeImportHierarchyChanges::UpdateState


IExchangeImportHierarchyChanges

The IExchangeImportHierarchyChanges interface supports the importing of incremental hierarchy changes into an information store. In an ICS application, this interface is used in conjunction with the IExchangeImportContentsChanges interface by the collector.

Quick Info

Header file: | EDKMDB.H
Exposed by: | Information store (not personal folder store (PST) or offline folder store (OST)) objects
Corresponding pointer type: | LPEXCHANGEIMPORTHIERARCHYCHANGES

Vtable Order

GetLastError

Config

UpdateState

ImportFolderChange

ImportFolderDeletion

Remarks

To obtain the IExchangeImportHierarchyChanges interface, the agent must open the information store and call the MAPI IMAPIProp::OpenProperty method on the PR_COLLECTOR property of the object.

When calling the OpenProperty method, pass the value IID_IExchangeImportHierarchyChanges in the lpiid parameter.

For additional information on this interface, see About Incremental Change Synchronization.


IExchangeImportHierarchyChanges::Config

The Config method initializes the collector in preparation to import changes from the synchronizer.

HRESULT Config(
  LPSTREAM * lpStream,
  ULONG ulFlags
);

Parameters

lpStream
Input parameter. Points to an open Win32 IStream interface. For unidirectional synchronization, this parameter is usually NULL.
ulFlags
Input parameter. Set this parameter to NULL, as this parameter is ignored.

Return Values

See Return Values.

In addition, Config can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.
SYNC_E_UNKNOWN_FLAGS
One of the flags was not valid.

Remarks

The Config method is called once by the agent to initialize the collector. Some collectors can use the Win32 IStream interface where the lpStream parameter points to maintain a cross-reference of source keys and their corresponding internal identifiers. Maintaining this cross-reference enables more efficient deletions when an object is created and deleted before synchronization occurs.

See Also

IExchangeExportChanges::Config, IExchangeImportHierarchyChanges


IExchangeImportHierarchyChanges::GetLastError

The GetLastError method retrieves information about the most recent error during importing the incremental hierarchy changes.

HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult
Input parameter. An error returned by one of the other IExchangeImportHierarchyChanges methods.
ulFlags
Input parameter. Defined flag that controls the format of the error report:
SYNC_UNICODE
Specifies that text is Unicode. If this flag is not set, the text is returned as the type of text in the clients' code page.
lppMAPIError

Output parameter. Points to the address of a MAPI MAPIERROR structure, which contains information on the last error.

Return Values

See Return Values.

In addition, GetLastError can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

See Also

IExchangeImportHierarchyChanges


IExchangeImportHierarchyChanges::ImportFolderChange

The ImportFolderChange method accepts a folder change notification from the synchronizer.

HRESULT ImportFolderChange(
  ULONG cValue,
  LPSPropValue lpPropArray
);

Parameters

cValue
Input parameter. The number of MAPI SPropValue array elements in lpPropArray.
lpPropArray
Input parameter. Points to an array of SPropValue structures, each of which contains a property tag and its value.

The array must contain at least the PR_PARENT_SOURCE_KEY, PR_SOURCE_KEY, PR_CHANGE_KEY, PR_PREDECESSOR_CHANGE_LIST, and MAPI PR_DISPLAY_NAME properties.

Return Values

See Return Values.

In addition, ImportFolderChange can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_CONFLICT
A conflict has occurred.
SYNC_E_ERROR
An unknown error occurred.
SYNC_NO_PARENT
Cannot locate the parent folder indicated by PR_PARENT_SOURCE_KEY.
SYNC_OBJECT_DELETED
The object has been deleted.

Remarks

The ImportFolderChange method is called by the synchronizer to import either a new folder or update an existing folder. This method should not be called from the agent.

To implement the ImportFolderChange method for a collector
  1. Search for the folder whose PR_SOURCE_KEY property matches the PR_PARENT_SOURCE_KEY property.
  2. If this folder does not exist, return SYNC_E_NO_PARENT.
  3. Search for a folder that matches the PR_SOURCE_KEY property.
  4. If the folder has been deleted, return SYNC_E_OBJECT_DELETED.
  5. If the folder does not exist, create it as a sub-folder of the parent folder (specified by the PR_PARENT_SOURCE_KEY property).
  6. If the folder exists and the imported change key (specified by the PR_CHANGE_KEY property) already appears in the predecessor change list, discard the change and return SUCCESS_SUCCESS.
  7. If the folder exists and the imported change key does not appear in the predecessor change list (specified by the PR_PREDECESSOR_CHANGE_LIST property), but the predecessor change list of the existing folder is contained with the predecessor change list of the imported folder, replace the existing properties with the new properties.
  8. If the folder exists, a conflict is detected, and conflicts are not allowed, return SYNC_E_CONFLICT.
  9. If the folder exists, a conflict is detected, and conflicts are allowed, use the modification times of the conflicting properties to determine whether to update or ignore the property.
    1. Return SUCCESS_SUCCESS.

See Also

IExchangeImportHierarchyChanges


IExchangeImportHierarchyChanges::ImportFolderDeletion

The ImportFolderDeletion method accepts a folder deletion notification from the synchronizer.

HRESULT ImportFolderDeletion(
  ULONG ulFlags,
  LPENTRYLIST lpSourceEntryList
);

Parameters

ulFlags
Input parameter. Set this parameter to zero, as this parameter is ignored.
lpSourceEntryList
Input parameter. Points to a MAPI ENTRYLIST structure, which contains the list of SOURCE_KEY properties that identify the folders to delete.

Return Values

See Return Values.

In addition, ImportFolderDeletion can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.
SYNC_E_INVALID_PARAMETER
One of the parameters was not valid.

Remarks

The ImportFolderDeletion method is called by the synchronizer for each folder that is deleted. This method should not be called from the agent.

If one of the folders in the entry list is not a valid folder or cannot be deleted, ImportFolderDeletion exits without processing the rest of the list and returns SYNC_E_INVALID_PARAMETER.

See Also

IExchangeImportContentsChanges::ImportMessageDeletion, IExchangeImportHierarchyChanges


IExchangeImportHierarchyChanges::UpdateState

The UpdateState method updates the status of importing the incremental hierarchy changes.

HRESULT UpdateState(
  LPSTREAM lpStream
);

Parameters

lpStream
Input parameter. Points to a Win32 IStream interface, which is where the state data is stored. Typically this parameter points to the interface opened by the IExchangeExportChanges::Config method. UpdateState also uses this interface if this parameter is NULL.

Return Values

See Return Values.

In addition, UpdateState can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
SYNC_E_ERROR
An unknown error occurred.

Remarks

The agent must use a different IStream interface if it is going to shut down and resume later, or if it is checkpointing the progress of the incremental change synchronization.

See Also

IExchangeExportChanges::Config, IExchangeImportContentsChanges::UpdateState, IExchangeImportHierarchyChanges


IExchangeManageStore

The IExchangeManageStore interface supports managing the folders and mailboxes in an information store.

Quick Info

Header file: | EDKMDB.H
Exposed by: | Message store objects
Corresponding pointer type: | LPEXCHANGEMANAGESTORE

Vtable Order

CreateStoreEntryID

EntryIDFromSourceKey

GetRights

GetMailboxTable

GetPublicFolderTable

Remarks

To get a pointer to this interface, call the QueryInterface method of the message store object. For additional information on this interface, see Logging On to a Mailbox Using the IExchangeManageStore Interface.


IExchangeManageStore::CreateStoreEntryID

The CreateStoreEntryID method allows applications or services that run with Administrator privileges to manage multiple mailboxes.

HRESULT CreateStoreEntryID(
  LPTSTR lpszMsgStoreDN,
  LPTSTR lpszMailboxDN,
  ULONG ulFlags,
  ULONG * lpcbEntryID,
  LPRENTRYID * lppEntryID
);

Parameters

lpszMsgStoreDN
Input parameter. Specifies the distinguished name of the information store where the mailbox is located. For example:
/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=ThisServer
/cn=Microsoft Private MDB

lpszMailboxDN
Input parameter. Specifies the distinguished name of the mailbox your service is attempting to access.
ulFlags
Input parameter. Defined values that control what gets opened. Use the bitwise OR operator (|) to enable multiple operations:
OPENSTORE _HOME_LOGON
Opens the home logon of the user's information store. Should be used when a separate logon to the user's information store is required. For example, if your application tracks the Read status of messages in a public folder on a per-user basis, it must logon to the user's mailbox in addition to the public folder to mark certain items as Read.
OPENSTORE _OVERRIDE_HOME_MDB
Ignores the current home information store for the user. Use OPENSTORE_OVERRIDE_HOME_MDB to implement methods that move a mailbox or copy a mailbox to a server other than the home server of the user. You cannot create multiple mailboxes on different servers for a single user, unless you specify this flag.
OPENSTORE_PUBLIC
Opens the public information store.
OPENSTORE _TAKE_OWNERSHIP
Opens the information store as the owner of the store, using the identity of the owner of the store. Posts a security event to the event log.
OPENSTORE _USE_ADMIN_PRIVILEGE
Opens the information store of another user, if you have administration rights on the other information store. Allows your application to own the information store while it's running, but does not log you on the mailbox under the identity of the owner of the mailbox. Posts a security event to the event log. OPENSTORE_USE_ADMIN_PRIVILEGE is normally used in conjunction with OPENSTORE_TAKE_OWNERSHIP.
lpcbEntryID
Output parameter. The number of bytes returned in the entry identifier that is pointed to by lppEntryID.
lppEntryID
Output parameter. A pointer to the entry identifier.

Note If a user can use your application to browse their own folders, you must set the MDB_TEMPORARY and MDB_NO_MAIL bits in the ulFlags parameter to the MAPI IMAPISession::OpenMsgStore method.

Return Values

See Return Values.

Remarks

This method creates and returns an entry identifier that can be used to access a server mailbox using the MAPI IMAPISession::OpenMsgStore method. For more information, see the MAPI Programmer's Reference.

In addition, this method formats the entry identifier and does not access the information store or require any resources on the server. As a result, this method call is a relatively inexpensive operation. Your application should free the entry identifier after it has finished using it.

See Also

IExchangeManageStore


IExchangeManageStore::EntryIDFromSourceKey

The EntryIDFromSourceKey method obtains the entry identifier for either a folder or message from its PR_SOURCE_KEY property.

HRESULT EntryIDFromSourceKey(
  ULONG cFolderKeySize,
  BYTE FAR * pFolderSourceKey,
  ULONG cMessageKeySize,
  BYTE FAR * pMessageSourceKey,
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

cFolderKeySize
Input parameter. The length, in bytes, of the key in pFolderSourceKey.
pFolderSourceKey
Input parameter. Points to a folder source key, identified by a PR_SOURCE_KEY property, for which you either want an entry identifier or want an entry identifier for a message within this folder.
cMessageKeySize
Input parameter. The length, in bytes, of the message source key in pMessageSourceKey. If you want to get the entry identifier for a folder, set this parameter to zero.
pMessageSourceKey
Input parameter. Points to a message source key, identified by a PR_SOURCE_KEY property, for which you want an entry identifier. If you want to get the entry identifier for a folder, set this parameter to NULL.
lpcbEntryID
Output parameter. The length, in bytes, of the entry identifier returned in lppEntryID.
lppEntryID
Output parameter. Points to the address of a MAPI ENTRYID structure, which contains the entry identifier for the folder or message.

Return Values

See Return Values.

In addition, EntryIDFromSourceKey can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
MAPI_E_CALL_FAILED
An unknown error occurred.
MAPI_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

Remarks

The EntryIDFromSourceKey method retrieves the entry identifier for a folder from its PR_SOURCE_KEY property or for a message from its PR_SOURCE_KEY property and its folder's PR_SOURCE_KEY property.

See Also

IExchangeManageStore


IExchangeManageStore::GetMailboxTable

The GetMailboxTable method obtains information about all of the mailboxes on a server.

HRESULT GetMailboxTable(
  LPTSTR lpszServerName,
  LPMAPITABLE FAR * lppTable,
  ULONG ulFlags
);

Parameters

lpszServerName
Input parameter. Points to a string that contains the distinguished name (DN) of the server.
lppTable
Output parameter. Points to a MAPI IMAPITable interface containing the information about all of the mailboxes on the server specified in lpszServerName.
ulFlags
Input parameter. A defined value that specifies whether the server name is Unicode:
MAPI_UNICODE
The server name is in Unicode format.
0
(Zero) The server name is in ASCII format.

Return Values

See Return Values.

In addition, GetMailboxTable can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
MAPI_E_CALL_FAILED
An unknown error occurred.
MAPI_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_LOGON_FAILED
The Microsoft Exchange Server information store is not running on the server.
MAPI_E_NETWORK_ERROR
Cannot connect to the server.
MAPI_E_NO_ACCESS
The user has no permissions on the folder.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

Remarks

The GetMailboxTable method returns a pointer to a MAPI table whose rows represent each of the mailboxes on the server you specify in lpszServerName. The columns of this table give you information such as the mailbox name (in PR_DISPLAY_NAME), the sizes of each of the messages in the mailbox (in PR_MESSAGE_SIZE), and the total number of messages in the mailbox (in PR_ASSOC_CONTENT_COUNT).

The following properties are returned for each mailbox:

PR_DISPLAY_NAME
A MAPI property containing the name of the mailbox as displayed.
PR_EMAIL_ADDRESS
A MAPI property containing the e-mail address of the mailbox.
PR_LOCALE_ID
The locale identifier (LCID) of the mailbox.
PR_MESSAGE_SIZE
A MAPI property contains the sum (in bytes) of the sizes of all properties on a message object.
PR_MESSAGE_SIZE_EXTENDED
The sum (in bytes) of the sizes of all properties on a message object. This is an 8-byte version of the MAPI PR_MESSAGE_SIZE property.
PR_CONTENT_COUNT
A MAPI property containing the total number of normal messages in the mailbox.
PR_ASSOC_CONTENT_COUNT
A MAPI property containing the total number of messages in the mailbox.
PR_NT_USER_NAME
The Windows NT user account name of the last user to log on to the information store.
PR_LAST_LOGON_TIME
The date and time when the user last logged on to the information store.
PR_LAST_LOGOFF_TIME
The date and time when the user last logged out of the information store.
PR_STORAGE_LIMIT_INFORMATION
Contains information about whether a mailbox is currently within the storage limit set by the Administrator program.
PR_INSTANCE_KEY
A MAPI property containing a unique key identifying the mailbox (and a row in the table).

See Also

IExchangeManageStore


IExchangeManageStore::GetPublicFolderTable

The GetPublicFolderTable method obtains information about all of the public folders on a server.

HRESULT GetPublicFolderTable(
  LPTSTR lpszServerName,
  LPMAPITABLE FAR * lppTable,
  ULONG ulFlags
);

Parameters

lpszServerName
Input parameter. Points to a string that contains the distinguished name (DN) of the server.
lppTable
Output parameter. Points to a MAPI IMAPITable interface containing the information about all of the public folders on the server specified in lpszServerName.
ulFlags
Input parameter. A defined value that specifies the folder type and whether the server name is Unicode:
MAPI_UNICODE
The server name is in Unicode format.
MDB_IPM
The public folders are interpersonal message (IPM) folders.
MDB_NON_IPM
The public folders are non-IPM folders.

Return Values

See Return Values.

In addition, GetPublicFolderTable can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
MAPI_E_CALL_FAILED
An unknown error occurred.
MAPI_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_LOGON_FAILED
The Microsoft Exchange Server information store is not running on the server.
MAPI_E_NETWORK_ERROR
Cannot connect to the server.
MAPI_E_NO_ACCESS
The user has no permissions on the public folder.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

Remarks

The following properties are returned for each public folder:

PR_ASSOC_CONTENT_COUNT
A MAPI property containing the total number of associated messages in the public folder.
PR_ASSOC_MESSAGE_SIZE
The size, in bytes, of all the associated messages in the public folder (reserved for internal use).
PR_ASSOC_MESSAGE_SIZE_EXTENDED
This property is reserved for internal use.
PR_ASSOC_MSG_W_ATTACH_COUNT
The total number of associated messages with attachments in the public folder (reserved for internal use).
PR_ATTACH_ON_ASSOC_MSG_COUNT
This property is reserved for internal use.
PR_ATTACH_ON_NORMAL_MSG_COUNT
The total count of attachments on all normal messages in a folder.
PR_CACHED_COLUMN_COUNT
The total number of cached columns on the public folder (reserved for internal use).
PR_CATEG_COUNT
The total number of categorizations on the public folder.
PR_CONTACT_COUNT
The number of contacts in a public folder.
PR_CONTENT_COUNT
A MAPI property that gives the number of messages in a folder, as computed by the message store.
PR_CREATION_TIME
A MAPI property containing the creation date and time for a message.
PR_DISPLAY_NAME
A MAPI property containing the name of the public folder as displayed.
PR_EMAIL_ADDRESS
A MAPI property containing the email address of the public folder.
PR_FOLDER_FLAGS
Various public folder information:
MDB_FOLDER_IPM
The public folder is an IPM folder.
MDB_FOLDER_SEARCH
The public folder is a search folder.
MDB_FOLDER_NORMAL
The public folder is a normal folder.
MDB_FOLDER_RULES
The public folder contains rules.
PR_FOLDER_PATHNAME
The pathname to the public folder.
PR_INSTANCE_KEY
A MAPI property containing a value that uniquely identifies a row in a table.
PR_LAST_ACCESS_TIME
The date that the replica of a public folder was accessed.
PR_LAST_MODIFICATION_TIME
A MAPI property containing the date and time the object or subobject was last modified.
PR_MESSAGE_SIZE
A MAPI property containing the size, in bytes, of all of messages in the public folder.
PR_MESSAGE_SIZE_EXTENDED
The sum (in bytes) of the sizes of all properties on a message object.
PR_NORMAL_MESSAGE_SIZE
The total size, in bytes, of all of the normal messages in the public folder.
PR_NORMAL_MESSAGE_SIZE_EXTENDED
The total size, in bytes, of all of the normal messages in the public folder. This is an 8-byte version of the PR_NORMAL_MESSAGE_SIZE property.
PR_NORMAL_MSG_W_ATTACH_COUNT
The total number of normal messages with attachments in the public folder.
PR_OWNER_COUNT
The PR_OWNER_COUNT property contains the number of owners of a public folder.
PR_RECIPIENT_ON_ASSOC_MSG_COUNT
The total number of recipients on the associated messages in the public folder.
PR_RECIPIENT_ON_NORMAL_MSG_COUNT
The total number of recipients on the normal messages in the public folder.
PR_RESTRICTION_COUNT
The total number of restrictions on the public folder.

See Also

IExchangeManageStore


IExchangeManageStore::GetRights

The GetRights method obtains the rights that the user has for a folder.

HRESULT GetRights(
  ULONG cbUserEntryIDSize,
  LPENTRYID lpUserEntryID,
  ULONG cbEntryIDSize,
  LPENTREYID lpEntryID,
  ULONG FAR * pRights
);

Parameters

cbUserEntryIDSize
Input parameter. The size, in bytes, of the entry identifier in lpUserEntryID.
lpUserEntryID
Input parameter. Points to a MAPI ENTRYID structure, which contains the entry identifier for the user whose rights you want.
cbEntryIDSize
Input parameter. The size, in bytes, of the entry identifier in lpEntryID.
lpEntryID
Input parameter. Points to an ENTRYID structure, which contains the entry identifier for the folder.
pRights
Output parameter. Points to a value containing the rights the user has on the folder:
frightsReadAny
The user can read any of the messages in the folder.
frightsCreate
The user can create a new message in the folder.
frightsEditOwned
The user can edit any message in the folder that they own.
frightsDeleteOwned
The user can delete any message in the folder that they own.
frightsEditAny
The user can edit any message in the folder.
frightsDeleteAny
The user can delete any message in the folder.
frightsCreateSubfolder
The user can create a new sub-folder in the folder.
frightsOwner
The user owns the folder, and has all rights.
frightsContact
The user is the contact for the folder.

Return Values

See Return Values. In addition, GetRights can return one of the following values:

SUCCESS_SUCCESS
The method completed successfully.
MAPI_E_CALL_FAILED
An unknown error occurred.
MAPI_E_INVALID_PARAMETER
One of the parameters was not valid.
MAPI_E_NO_ACCESS
The user has no permissions on the folder.
MAPI_E_NOT_ENOUGH_MEMORY
There wasn't enough memory to complete the operation.

See Also

IExchangeManageStore, IExchangeManageStore::EntryIDFromSourceKey


IExchangeModifyTable

TheIExchangeModifyTable interface supports access to Microsoft Exchange Server table objects, specifically ACL table objects and rule table objects on Microsoft Exchange Server folders. This interface is similar to the IMAPITable interface, but adds support for Microsoft Exchange Server-specific structures used to control ACLs and rules.

Quick Info

Header file: | EDKMDB.H
Exposed by: |
Corresponding pointer type: | LPEXCHANGEMODIFYTABLE

Vtable Order

GetLastError

GetTable

ModifyTable

Required Properties

If modifying a rules table: PR_RULE_ID, PR_RULE_SEQUENCE, PR_RULE_STATE, PR_RULE_CONDITION, PR_RULE_ACTIONS, PR_RULE_USER_FLAGS, PR_RULE_PROVIDER

If modifying an ACLs table: PR_MEMBER_ENTRYID, PR_MEMBER_RIGHTS, PR_MEMBER_NAME

Remarks

To obtain this interface, call the MAPI IMAPIProp::OpenProperty method on a property of type PT_OBJECT on a folder object.

When calling the OpenProperty method, pass the value IID_IExchangeModifyTable in the lpiid parameter.

For additional information on this interface, see About Rules and About Access Control Lists.

See Also

PR_ACL_TABLE, PR_RULES_TABLE


IExchangeModifyTable::GetLastError

The GetLastError method retrieves information about the last error that occurred for a table object.

HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult
Input parameter. The error returned.
ulFlags
Input parameter. Not used, set to 0 (zero).
lppMAPIError
Output parameter. Points to a MAPI MAPIERROR structure containing information about the last error that occurred for a table object.

Return Values

See Return Values.

See Also

IExchangeModifyTable


IExchangeModifyTable::GetTable

The GetTable method retrieves a pointer to an interface to a MAPI table object.

HRESULT GetTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags
Input parameter. Reserved for future use. Set this parameter to 0 (zero).
lppTable
Output parameter. Points to a MAPI IMAPITable interface containing the table object.

Return Values

See Return Values.

See Also

IExchangeModifyTable


IExchangeModifyTable::ModifyTable

The ModifyTable method updates a MAPI table object.

HRESULT ModifyTable(
  ULONG ulFlags,
  LPROWLIST lpMods
);

Parameters

ulFlags
Input parameter. Use one of the following values:
0 (zero)
Use the value of the ulRowFlags member of the ROWENTRY structure.
ROWLIST_REPLACE
Replace all the rows in the table.
lpMods
Input parameter. Points to a ROWLIST structure containing the properties for the table object.

Return Values

See Return Values.

See Also

GetTable, IExchangeModifyTable


IExchangeRuleAction

The IExchangeRuleAction interface supports the actions that are scheduled for a deferred action message (DAM).

Quick Info

Header file: | EDKMDB.H
Exposed by: | Message objects
Corresponding pointer type: | LPEXCHANGERULEACTION

Vtable Order

ActionCount

GetAction

Remarks

To obtain the IExchangeRuleAction interface, call the MAPI IMAPIProp::OpenProperty method on the PR_CLIENT_ACTIONS property of the object. When calling the OpenProperty method, pass the value IID_IExchangeRuleAction in the lpiid parameter.

Note Do not attempt to open an instance of this interface on a non-DAM. If you do, the OpenProperty method returns MAPI_W_ERRORS_RETURNED, which is only a warning, and the interface pointer is uninitialized.

For additional information on this interface, see About Rules.


IExchangeRuleAction::ActionCount

The ActionCount method retrieves the number of actions for the rule on a deferred action message.

HRESULT ActionCount
  ULONG FAR * lpcActions
);

Parameters

lpcActions
Output parameter. Points to a ULONG variable that contains the number of actions that are executed when the deferred action message rule is executed.

Return Values

See Return Values.

Remarks

See deferred action message.

See Also

IExchangeRuleAction


IExchangeRuleAction::GetAction

The GetAction method retrieves an action for the rule on a deferred action message.

HRESULT GetAction
  ULONG ulActionNumber,
  LARGE_INTEGER * lpruleid,
  LPACTION FAR * lppAction
);

Parameters

ulActionNumber
Input parameter. A ULONG variable containing the index to this action. The first action is at position 0 (zero).
lpruleid
Output parameter. Points to a LARGE_INTEGER variable containing the identifier for the rule.
lppAction
Output parameter. Points to an ACTION structure containing the action that is to be taken on the message.

Return Values

See Return Values.

Remarks

To determine the number of actions, call ActionCount.

See Also

IExchangeRuleAction


IExchangeRuleExt

The IExchangeRuleExt interface supports custom actions for a deferred action message (DAM). The custom action DLL that contains this interface is supplied by the user. You must supply this interface and its methods; in addition, you must supply the IUnknown interface and its QueryInterface, AddRef, and Release methods. For information about implementing the IUnknown interface and its methods, see the MAPI Programmer's Reference.

Quick Info

Header file: | EXCHCLI.H
Exposed by: |
Corresponding pointer type: | LPEXCHANGERULEEXT

Vtable Order

Install

QueryRelease

GetCommand

QueryCommandDisplayName

Command

Remarks

For additional information on this interface, see About Rules.


IExchangeRuleExt::Command

The Command method executes a command on a deferred action message. The Microsoft Exchange Client calls this method when the associated rule is triggered.

HRESULT Command(
  LPEXCHANGERULEEXTCALLBACK percb,
  LPCTSTR pszCommand,
  ULONG cb,
  LPENTRYID peid
);

Parameters

percb
Input parameter. Points to an instance of an IExchangeRuleExtCallback interface.
pszCommand
Input parameter. Points to a string containing an encoding of the command to execute. The Microsoft Exchange Client obtains this command encoding through a call to the GetCommand method.
cb
Input parameter. The size, in bytes, of the MAPI ENTRYID structure where peid points.
peid
Input parameter. Points to an ENTRYID structure containing the entry identifier of the message to which the command applies.

Return Values

Return E_FAIL if the command fails; return NOERROR if the command completes successfully.

Remarks

The custom action DLL can use the IExchangeRuleExtCallback interface's methods to obtain information on the Microsoft Exchange Client.

See Also

IExchangeRuleExt


IExchangeRuleExt::GetCommand

The GetCommand method retrieves information about a command. The Microsoft Exchange Client calls this method to obtain the command encoding and display name for the command.

HRESULT GetCommand(
  LPEXCHANGERULEEEXTCALLBACK percb,
  TCHAR FAR * pszCommand,
  ULONG cchCommand,
  TCHAR FAR * pszDisplayName,
  ULONG cchDisplayName
);

Parameters

percb
Input parameter. Points to an instance of an IExchangeRuleExtCallback interface.
pszCommand
Input/output parameter. Points to a string containing the encoding of the command. This parameter can be initialized with the encoding of a previous command.
cchCommand
Input parameter. The size, in bytes, of the string where pszCommand points.
pszDisplayName
Input/output parameter. Points to a string containing the name of the command that is displayed. This parameter can be initialized with the display name of a previous command.
cchDisplayName
Output parameter. The size, in bytes, of the string where pszDisplayName points.

Return Values

Returns E_FAIL if the user cancels the command; returns NOERROR if the command completes successfully.

See Also

Command, IExchangeRuleExt


IExchangeRuleExt::Install

The Install method informs the custom action DLL of the context in which it is invoked. The Microsoft Exchange Client calls this method either when the user selects a custom action for an Inbox Assistant rule or when that rule is triggered.

HRESULT Install(
  LPEXCHANGERULEEXTCALLBACK percb,
  ULONG ulContext
);

Parameters

percb
Input parameter. Points to an instance of an IExchangeRuleExtCallback interface.
ulContext
Input parameter. The context in which the custom action DLL is invoked:
ERCONTEXT_INFO
The user selected a custom action in the Inbox Assistant.
ERCONTEXT_EXEC
The Microsoft Exchange Client triggered that custom action.

Return Values

Return E_FAIL if the user cancels the command; return NOERROR if the command completes successfully.

Remarks

The custom action DLL is invoked from either the Inbox Assistant or from the Microsoft Exchange Client. The Inbox Assistant invokes this method so it can then assign a custom action to a rule using the GetCommand method. The Microsoft Exchange Client invokes this method so it can then apply that rule to the associated message using the Command method.

See Also

IExchangeRuleExt, QueryRelease


IExchangeRuleExt::QueryCommandDisplayName

The QueryCommandDisplayName method retrieves the display name of a command. The Inbox Assistant calls this method when the user edits an existing rule that specifies a custom action.

HRESULT QueryCommandDisplayName(
  LPEXCHANGERULEEXTCALLBACK percb,
  LPCTSTR pszCommand,
  TCHAR FAR * pszDisplayName,
  ULONG cchDisplayName
);

Parameters

percb
Input parameter. Points to an instance of an IExchangeRuleExtCallback interface.
pszCommand
Input parameter. Points to a string containing the encoding of the command.
pszDisplayName
Output parameter. Points to a string containing the name of the command that is displayed.
cchDisplayName
Output parameter. The size, in bytes, of the string where pszDisplayName points.

Return Values

Return E_FAIL if the user cancels the command; return NOERROR if the command completes successfully.

Remarks

The display name should be the same as the name originally returned by the GetCommand method. Microsoft Exchange Server does not save that display name when it saves the Inbox Assistant rule.

See Also

IExchangeRuleExt


IExchangeRuleExt::QueryRelease

The QueryRelease method does any cleanup that is necessary before the Microsoft Exchange Client unloads the custom action DLL from memory.

HRESULT QueryRelease(
  VOID
);

Parameters

None.

Return Values

Return NOERROR if the command completes successfully; otherwise return E_FAIL. Note that the Microsoft Exchange Client will unload the custom action DLL from memory regardless of the return value.

Remarks

The Microsoft Exchange Client invokes this method so the custom action DLL can release any memory or perform any other housekeeping chores before the DLL is unloaded from memory.

See Also

IExchangeRuleExt, Install


IExchangeRuleExtCallback

The IExchangeRuleExtCallback interface supplies information about the Microsoft Exchange Client that invoked the custom action DLL for a deferred action message (DAM).

Quick Info

Header file: | EXCHCLI.H
Exposed by: |
Corresponding pointer type: | LPEXCHANGERULEEXTCALLBACK

Vtable Order

GetVersion

GetWindow

GetSession

Remarks

For additional information on this interface, see About Rules.


IExchangeRuleExtCallback::GetSession

The GetSession method retrieves the MAPI logon session.

HRESULT GetSession(
  LPMAPISESSION FAR * ppses
);

Parameters

ppses
Output parameter. Points to a MAPI IMAPISession interface containing the MAPI logon session.

Return Values

See Return Values.

See Also

IExchangeRuleExtCallback


IExchangeRuleExtCallback::GetVersion

The GetVersion method retrieves the version number of the Microsoft Exchange Client.

HRESULT GetVersion(
  ULONG FAR * pulVersion,
  ULONG ulFlags
);

Parameters

pulVersion
Output parameter. Points to a LONG variable where the version number is stored.
ulFlags
Input parameter. Specifies the version information that is returned:
EECBGV_GETBUILDVERSION
Returns the build number of Microsoft Exchange Server, with the major version in the high word and the minor version in the low word.
EECBGV_GETACTUALVERSION
Returns the Microsoft Exchange Server version number in the low word and operating system version number in the high word.
EECBGV_GETVIRTUALVERSION
Returns the Microsoft Exchange Server version number in the low word and operating system version number in the high word.

Return Values

See Return Values.

See Also

IExchangeRuleExtCallback


IExchangeRuleExtCallback::GetWindow

The GetWindow method retrieves a handle to the parent window.

HRESULT GetWindow(
  HWND FAR * phwnd
);

Parameters

phwnd
Output parameter. Points to the handle of the parent window.

Return Values

See Return Values.

See Also

IExchangeRuleExtCallback


Properties

A property is a specific attribute of a Microsoft Exchange Server object. Properties describe something about the object, such as the subject line of a message or the address type of a distribution list. The Microsoft Exchange Server defines many properties, some to describe many objects and some that are appropriate only for a particular type of object. You can extend the set of Microsoft Exchange Server properties by creating new, custom properties. Many Microsoft Exchange Server properties are directly derived from MAPI properties. See the MAPI Programmer's Reference for further information on MAPI properties.

An object and its properties exist in only one of the following locations:

  • An information store You can access information store object properties through the interfaces and functions of the Microsoft Exchange Server SDK, such as using the HrOpenExchangePublicStore function to open the public information store. See Information Store Operations for further information on opening the information store.
  • A user’s MAPI profile You can access user profile properties only through the MAPI IProfAdmin interface. For more information, see the MAPI Programmer's Reference.
  • The Microsoft Exchange Server directory You can access the properties of directory objects through the directory access functions (see Using Directory Access Functions). Many directory attributes are equivalent to MAPI address book properties and as such are accessible through the MAPI IAddrBook interface. For more information on this mapping, see Accessing Directory Attributes with MAPI. For general information on using these properties with MAPI, see Using MAPI with Directory Objects.

Use the MAPI IMAPIProp interface to access an object’s properties. All objects that have properties implement an interface that inherits from IMAPIProp. Some of the inherited interfaces, such as the MAPI IMessage interface (implemented by message objects), have unique methods beyond those inherited from IMAPIProp. Service providers can implement new object properties, which only the provider can access. For further information, see the MAPI Programmer's Reference.

There are different types of properties, depending on the type of data that the property value contains, such as an integer, real number, text, or Boolean (see Property Types).

The MAPI SPropValue structure contains information about a property’s type, value, and identifier. For further information, see the MAPI Programmer's Reference.

The property identifier is a unique number within a specific range of numbers (see MAPIDEFS.H). In addition, each property has a property tag, which consists of a numeric representation of the property type concatenated with its property identifier.

Property tag names share a common format. Beginning with the PR prefix, they are composed of one or more words that describe the property joined by underscores. For example, PR_USER_NAME is the tag for the property that contains the name of a user of a message store.

Sometimes the same property can be expressed in different units. In such cases, you may see the same property tag with one of the following suffixes:

_A | Expressed as an ANSI string
_O | Expressed as an object
_T | Expressed as a teletext string
_W | Expressed as a wide (Unicode) value

For example, the PR_EMS_AB_IS_MEMBER_OF_DL property (an object that lists the distribution lists that include this mailbox) can be expressed as follows:

  • PR_EMS_AB_IS_MEMBER_OF_DL_A
  • PR_EMS_AB_IS_MEMBER_OF_DL_O
  • PR_EMS_AB_IS_MEMBER_OF_DL_T
  • PR_EMS_AB_IS_MEMBER_OF_DL_W

All these properties have the same definition, but are expressed in different units.


Property Types

A property type identifies the data type of the property’s value, such as PT_LONG or PT_BOOLEAN. The set of MAPI property types is defined in the MAPIDEFS.H header file. All properties must correspond to one of these types, whether they are defined by MAPI, by client applications, or by service providers. All property types are data types of the underlying operating system, and some types relate to OLE properties.

Property type names are represented by constants that follow a similar naming convention to the one used for property tags. All property types have two parts: the prefix “PT_” and a string that describes the data type, such as LONG or STRING8.

Property types can be single-valued or multivalued. A single-valued property contains one value, such as an integer, Boolean, character string, sized array of bytes, or structure.

A multivalued property contains multiple values of its type. To represent a multivalued property, the MV_FLAG flag is combined with the base property type in a logical OR operation. If supported, a multivalued property can be used anywhere that a single-valued property can be used.

The following illustration shows the structure of a multivalued property of type PT_LONG. The value is no longer a single variable; it is made up of a pointer that points to an array of values and a count of the number of values in the array.

Multivalued property structure

Although support for multivalued properties is optional, Microsoft recommends that clients and service providers support both single-valued and multivalued properties. Doing so enables greater interaction between MAPI-compliant components.


Microsoft Exchange Server Property Types

The following table describes Microsoft Exchange Server property types that are supported by MAPI.

Property Type | Multivalued Type | Underlying Data Type
PT_APPTIME | PT_MV_APPTIME | Double. Interpreted as date and time. Same as OLE type VT_DATE and compatible with the Visual Basic time representation.
PT_BINARY | PT_MV_BINARY | SBinary. Counted byte array.
PT_BOOLEAN | PT_MV_12 | 16-bit Boolean. 0 = FALSE, nonzero = TRUE. Same as OLE type VT_BOOL.
PT_CLSID | PT_MV_CLSID | CLSID structure. Class identifier. VT_CLSID.
PT_CURRENCY | PT_MV_CURRENCY | 64-bit integer intepreted as decimal. Compatible with Visual Basic CURRENCY type. Same as OLE type VT_CY.
PT_DOUBLE | PT_MV_DOUBLE | Double. 64-bit floating point, PT_R4. Same as OLE type VT_R8.
PT_ERROR | (None) | SCODE, 32-bit unsigned integer. Same as OLE type VT_ERROR.
PT_FLOAT | PT_MV_FLOAT | 32-bit floating point, PT_R4. Same as OLE type VT_R4.
PT_I2 | PT_MV_I2 | Signed 16-bit integer, PT_SHORT. Same as OLE type VT_I2.
PT_I4 | PT_MV_I4 | Signed or unsigned 32-bit integer. Same as OLE type VT_I4. Same as PT_LONG.
PT_I8 | PT_MV_I8 | Signed or unsigned 64-bit integer. Same as OLE type VT_I8. Uses the structure LARGE_INTEGER.
PT_LONG | PT_MV_LONG | Signed or unsigned 32-bit integer, PT_I4. Same as OLE type VT_I4.
PT_LONGLONG | PT_MV_LONGLONG | Signed or unsigned 64-bit integer, PT_I8. Same as OLE type VT_I8.
PT_NULL | (None) | Indicates no property value. Same as OLE type VT_NULL. Reserved for interface use.
PT_OBJECT | (None) | A pointer to an object that implements the WIN32 IUnknown interface. Similar to several OLE types, including VT_UNKNOWN.
PT_R4 | PT_MV_R4 | 4-byte floating-point data. Same as OLE type VT_R4.
PT_R8 | PT_MV_R8 | 8-byte floating-point data. Same as OLE type VT_DOUBLE.
PT_SHORT | PT_MV_SHORT | Signed 16-bit integer, PT_SHORT. Same as OLE type VT_I2.
PT_STRING8 | PT_MV_STRING8 | Null-terminated 8-bit character string data. Same as OLE type VT_LPSTR.
PT_SYSTIME | PT_MV_SYSTIME | 64-bit integer. Date and time values in the form of a MAPI FILETIME structure. Same as OLE type VT_FILETIME.
PT_TSTRING | PT_MV_TSTRING | Set to PT_UNICODE when compiling with the UNICODE symbol; else PT_STRING8. Either the OLE type VT_LPSTR or VT_LPWSTR.
PT_UNICODE | PT_MV_UNICODE | Null-terminated wide-string data. Same as OLE type VT_LPWSTR.
PT_UNSPECIFIED | (Not supported) | Indicates that the client application does not supply the property type. Reserved for interface use.


Microsoft Exchange Server Properties

The following properties are presented in alphabetical order. Microsoft Exchange Server objects have these properties, as well as their MAPI properties. For information on MAPI properties, see the MAPI Programmer’s Reference.

Information store properties are defined in the EDKMDB.H header file. Address book properties are defined in the EMSABTAG.H header file. Personal folder store properties are defined in the MSPST.H header file.

For a list of properties that apply to a certain object, see that object’s documentation.


PR_ACL_DATA

The PR_ACL_DATA property contains the binary form of the PR_ACL_TABLE object, which is the access control list (ACL) table for a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder objects (information store objects)
Identifier: | 0x3fe0
Property type: | PT_BINARY
Access: | Read/write

See Also

PR_ACL_TABLE, Manipulating ACLs


PR_ACL_TABLE

The PR_ACL_TABLE property contains a table consisting of all the access control lists (ACLs) applied to a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder objects (information store objects)
Identifier: | 0x3fe0
Property type: | PT_OBJECT
Access: | Read-only

See Also

PR_ACL_DATA, Manipulating ACLs


PR_ADDRBOOK_FOR_LOCAL_SITE_ENTRYID

The PR_ADDRBOOK_FOR_LOCAL_SITE_ENTRYID property is reserved for internal use.


PR_ADDRESS_BOOK_DISPLAY_NAME

The PR_ADDRESS_BOOK_DISPLAY_NAME property is reserved for internal use.


PR_ADDRESS_BOOK_ENTRYID

The PR_ADDRESS_BOOK_ENTRYID property consists of the name-service entry identifier of a directory object referring to a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder objects (information store objects) in the public information store.
Identifier: | 0x663b
Property type: | PT_BINARY
Access: | Read-only

See Also

PR_PUBLISH_IN_ADDRESS_BOOK


PR_ARRIVAL_TIME

The PR_ARRIVAL_TIME property contains the date and time a specific message arrived at a gateway.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message transfer envelope objects (information store objects)
Identifier: | 0x665f
Property type: | PT_SYSTIME
Access: | Read/write

Remarks

The PR_ARRIVAL_TIME property is used by developers to track the arrival time of messages.


PR_ASSOC_MESSAGE_SIZE

The PR_ASSOC_MESSAGE_SIZE property is reserved for internal use.


PR_ASSOC_MESSAGE_SIZE_EXTENDED

The PR_ASSOC_MESSAGE_SIZE_EXTENDED property is reserved for internal use.


PR_ASSOC_MSG_W_ATTACH_COUNT

The PR_ASSOC_MSG_W_ATTACH_COUNT property is reserved for internal use.


PR_ATTACH_ON_ASSOC_MSG_COUNT

The PR_ATTACH_ON_ASSOC_MSG_COUNT property is reserved for internal use.


PR_ATTACH_ON_NORMAL_MSG_COUNT

The PR_ATTACH_ON_NORMAL_MSG_COUNT property contains the total count of attachments on all normal messages in a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66b1
Property type: | PT_LONG
Access: | N/A

Remarks

The PR_ATTACH_ON_NORMAL_MSG_COUNT property can be set as a column in the table returned by the IExchangeManageStore::GetPublicFolderTable method. This table contains a row for each public folder replicated to the server. The columns give information such as the display name of the folder, pathname, and last access time. See the Public Folder Resources tab for the Public Information Store property sheet in the Administrator program to view the format of this table.

The PR_ATTACH_ON_NORMAL_MSG_COUNT property also indicates the total number of attachments on nonassociated messages in the folder.

See Also

IExchangeManageStore::GetPublicFolderTable


PR_CACHED_COLUMN_COUNT

The PR_CACHED_COLUMN_COUNT property is reserved for internal use.


PR_CATEG_COUNT

The PR_CATEG_COUNT property contains the total number of categorizations in a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66ab
Property type: | PT_LONG
Access: | Read/write


PR_CHANGE_KEY

The PR_CHANGE_KEY property contains a binary number that uniquely identifies the message or folder version.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message and public folder objects (information store objects)
Identifier: | 0x65e2
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_CHANGE_KEY property is used primarily by the incremental change synchronization (ICS) interface. This property is assigned to an object that has undergone a change by the store in which the object was modified. This property travels with the object and is only updated when the object is next changed.

For Microsoft Exchange Server, the PR_CHANGE_KEY property is 22 bytes in length, which includes the store GUID (16 bytes) followed by a 6-byte number that is unique to the store.

Synchronizer implementers must format the PR_SOURCE_KEY as a minimum of 17 bytes in length, including a GUID and a unique binary number that identifies the object within the foreign store.

Two change keys from the same store can be directly compared. In the case of Microsoft Exchange Server, the larger number represents the most recent change.

Note: It is recommended that third-party developers do not use 6 bytes as their unique number.

For more information, see About Incremental Change Synchronization.

See Also

IExchangeExportChanges, IExchangeImportContentsChanges, IExchangeImportHierarchyChanges, PR_PARENT_SOURCE_KEY, PR_PREDECESSOR_CHANGE_LIST; PR_SOURCE_KEY


PR_CLIENT_ACTIONS

The PR_CLIENT_ACTIONS property contains the rule actions.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x6645
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_CLIENT_ACTIONS property is used only on a deferred action message (DAM) to store the action data for the Microsoft Exchange Client to carry out when one or more deferred actions rules have fired on the mailbox. This property should not be used for other purposes. Developers who wish to provide custom client-side rule behavior should implement custom rule actions, which do not need to access this property directly and are called by the client when it has received a DAM.


PR_COLLECTOR

The PR_COLLECTOR property is used with the MAPI OpenProperty function to retrieve either the IExchangeImportHierarchyChanges interface or the IExchangeImportContentsChanges interface.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message store objects (information store objects)
Identifier: | 0x662e
Property type: | PT_OBJECT
Access: | Read-only

Remarks

The PR_COLLECTOR property is part of the incremental change synchronization (ICS) interface, which is not supported by all information stores. See the MAPI Programmer’s Reference.

See Also

IExchangeExportChanges, IExchangeImportContentsChanges, IExchangeImportHierarchyChanges, PR_CONTENTS_SYNCHRONIZER


PR_CONFLICT_ENTRYID

The PR_CONFLICT_ENTRYID property is the entry identifier of an original conflict message that contains conflicting versions of the message as attachments.

Quick Info

Header file: | EDKMDB.H
Applies to: | Notification message objects (information store objects)
Identifier: | 0x3ff0
Property type: | PT_BINARY
Access: | Read/write

Remarks

Handling Message Conflicts.


PR_CONTACT_COUNT

The PR_CONTACT_COUNT property contains the number of contacts in a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66b7
Property type: | PT_LONG
Access: | Read/write


PR_CONTENT_SEARCH_KEY

The PR_CONTENT_SEARCH_KEY property contains the entry identifier of the message inside the message transfer envelope (MTE).

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x6666
Property type: | PT_BINARY
Access: | Read/write

Remarks

PR_CONTENT_SEARCH_KEY is a property on a message.


PR_CONTENTS_SYNCHRONIZER

The PR_CONTENTS_SYNCHRONIZER property is used with the MAPI OpenProperty function to retrieve the IExchangeExportChanges interface. This interface is for exporting only a folder's contents changes, not its hierarchy changes.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x662d
Property type: | PT_OBJECT
Access: | Read-only

Remarks

The PR_CONTENTS_SYNCHRONIZER property is part of the incremental change synchronization (ICS) interface, which is not supported by all stores. See the MAPI Programmer’s Reference.

See Also

IExchangeExportChanges


PR_CREATOR_ENTRYID

The PR_CREATOR_ENTRYID property contains the address book entry identifier of the user who created the message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x6641
Property type: | PT_BINARY
Access: | Read-only


PR_CREATOR_NAME

The PR_CREATOR_NAME property specifies the display name of the user who created the message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x6640
Property type: | PT_TSTRING
Access: | Read-only


PR_DAM_BACK_PATCHED

The PR_DAM_BACK_PATCHED property is reserved for internal use.


PR_DAM_ORIGINAL_ENTRYID

The PR_DAM_ORIGINAL_ENTRYID property is reserved for internal use.


PR_DEFERRED_SEND_NUMBER

The PR_DEFERRED_SEND_NUMBER property contains the units of time that the system waits before sending a message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3feb
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_DEFERRED_SEND_NUMBER property is used with the PR_DEFERRED_SEND_UNITS property to determine the length of time the system waits before sending a message.

See Also

PR_DEFERRED_SEND_TIME, PR_DEFERRED_SEND_UNITS


PR_DEFERRED_SEND_TIME

The PR_DEFERRED_SEND_TIME property indicates a future time at which a message is to be sent.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3fef
Property type: | PT_SYSTIME
Access: | Read-only

Remarks

The PR_DEFERRED_SEND_TIME property is used by Microsoft Exchange Server to defer the sending of messages until a specified time in the future. This property can be set directly, or it can be calculated from the PR_DEFERRED_SEND_NUMBER and PR_DEFERRED_SEND_UNITS properties. The advantage of the latter method (if the message is reopened and edited before the deferral delay expires) is that it can be resubmitted with the same deferral delay.

Deferred sending depends on a user's default delivery configuration. If mail is delivered to a Microsoft Exchange Server information store mailbox, deferred messages are held in the Outbox until they can be sent by the server. If mail is delivered to a personal folders information store (PST), deferred messages are spooled from the Outbox of the PST to a hidden folder on the server.

In other words, if your Outbox is in a Microsoft Exchange Server mailbox you can intercept deferred mail before it is sent, but not if your Outbox is in a PST.

Note The PR_DEFERRED_SEND_TIME property is not the same as the MAPI PR_DEFERRED_DELIVERY_TIME property. The PR_DEFERRED_SEND_TIME property instructs the mail transport to delay taking responsibility for a message, while the PR_DEFERRED_DELIVERY_TIME property instructs the mail transport to take responsibility for the message immediately, but to delay final delivery of the message.

See Also

PR_DEFERRED_SEND_NUMBER, PR_DEFERRED_SEND_UNITS


PR_DEFERRED_SEND_UNITS

The PR_DEFERRED_SEND_UNITS property specifies the unit of time to be used with the PR_DEFERRED_SEND_NUMBER property to determine the PR_DEFERRED_SEND_TIME for a message that has been deferred.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3fec
Property type: | PT_LONG
Access: | Read/write

Values

0
Minutes
1
Hours
2
Days
3
Weeks

Remarks

The PR_DEFERRED_SEND_UNITS property is used with the PR_DEFERRED_SEND_NUMBER property to determine the length of time for the system to wait before sending a message. For more details, refer to the PR_DEFERRED_SEND_TIME property.

See Also

PR_DEFERRED_SEND_NUMBER, PR_DEFERRED_SEND_TIME


PR_DESIGN_IN_PROGRESS

The PR_DESIGN_IN_PROGRESS property contains a flag that indicates a folder is being modified and can only be accessed by the owner.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3fe4
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Folder is not being modified
1
TRUE = Folder is being modified

See Also

PR_FOLDER_DESIGN_FLAGS


PR_EFORMS_FOR_LOCALE_ENTRYID

The PR_EFORMS_FOR_LOCALE_ENTRYID property is reserved for internal use.


PR_EFORMS_LOCALE_ID

The PR_EFORMS_LOCALE_ID property is reserved for internal use.


PR_EFORMS_REGISTRY_ENTRYID

The PR_EFORMS_REGISTRY_ENTRYID property specifies the entry identifier of the forms library folder under the non-IPM subtree.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message store object (information store objects)
Identifier: | 0x6621
Property type: | PT_BINARY
Access: | Read-only


PR_EMS_AB_ACCESS_CATEGORY

The PR_EMS_AB_ACCESS_CATEGORY property is reserved for internal use.


PR_EMS_AB_ACTIVATION_SCHEDULE

The PR_EMS_AB_ACTIVATION_SCHEDULE property contains the activation schedule of a regularly scheduled event for a Microsoft Exchange Server component.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Add-In, Computer, DX-Requestor, DXA-Site-Server, Mail-Gateway, Mailbox-Agent, Replication-Connector, and Site-Addressing objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8045
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_EMS_AB_ACTIVATION_SCHEDULE property is an 84-byte value that consists of one byte for every two hours. Each bit signifies a 15-minute interval, beginning with the high bit and going toward the low bit. The value starts at 12:00 a.m. (midnight) Sunday morning Greenwich Mean Time (GMT). Therefore, you must convert to GMT before deciding which bit to set.

This property works in conjunction with the PR_EMS_AB_ACTIVATION_STYLE property to determine when a component is activated.

See Also

PR_EMS_AB_ACTIVATION_STYLE


PR_EMS_AB_ACTIVATION_STYLE

The PR_EMS_AB_ACTIVATION_STYLE property contains the style of activation of a regularly scheduled event for a Microsoft Exchange Server component.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox-Agent, Site-Addressing, Computer, Add-In, DXA-Site-Server, Mail-Gateway, DX-Requestor, and Replication-Connector objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8046
Property type: | PT_LONG
Access: | Read/write

Values

Computer, Mailbox-Agent, Site-Addressing, and DX-Requestor objects
0
Never run
1
Run at selected times
2
Always run
DXA-Site-Server objects
0
Never update
1
Update at selected times
2
Always update
Mail-Gateway and Replication-Connector objects
0
Never run
1
Run at selected times
2
Always run
3
Remote initiated

Remarks

The PR_EMS_AB_ACTIVATION_STYLE property works in conjunction with the PR_EMS_AB_ACTIVATION_SCHEDULE property to determine when a component is activated.

See Also

PR_EMS_AB_ACTIVATION_SCHEDULE


PR_EMS_AB_ADDRESS_ENTRY_DISPLAY_TABLE

The PR_EMS_AB_ADDRESS_ENTRY_DISPLAY_TABLE property contains the MAPI display table for an address entry.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Display-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8017
Property type: | PT_BINARY
Access: | Read-only

Remarks

For more information about display tables, see the MAPI Programmer’s Reference.


PR_EMS_AB_ADDRESS_ENTRY_DISPLAY_TABLE_MSDOS

The PR_EMS_AB_ADDRESS_ENTRY_DISPLAY_TABLE_MSDOS property contains the MS-DOS format display table for an address entry.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Display-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8047
Property type: | PT_BINARY
Access: | Read-only

Remarks

For more information about display tables, see the MAPI Programmer’s Reference.


PR_EMS_AB_ADDRESS_SYNTAX

The PR_EMS_AB_ADDRESS_SYNTAX property contains the correct syntax to use when encoding the display table properties as a string.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Address-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8018
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_EMS_AB_ADDRESS_SYNTAX property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid when reading a property from an object copied into another address book provider.

For more information, see Sample Address Syntax Program.


PR_EMS_AB_ADDRESS_TYPE

The PR_EMS_AB_ADDRESS_TYPE property contains the address type to use when setting up replication to a remote site.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Replication-Connector and Address-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8048
Property type: | PR_EMS_AB_ADDRESS_TYPE PT_TSTRING PR_EMS_AB_ADDRESS_TYPE_A PT_STRING8 PR_EMS_AB_ADDRESS_TYPE_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
32
Maximum length


PR_EMS_AB_ADMD

The PR_EMS_AB_ADMD property determines whether the internal trace information is stripped.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway and MTA objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8049
Property type: | PR_EMS_AB_ADMD PT_TSTRING PR_EMS_AB_ADMD_A PT_STRING8 PR_EMS_AB_ADMD_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
16
Maximum length


PR_EMS_AB_ADMIN_DESCRIPTION

The PR_EMS_AB_ADMIN_DESCRIPTION property contains a short description of a directory object for the administrator.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x804a
Property type: | PR_EMS_AB_ADMIN_DESCRIPTION PT_TSTRING PR_EMS_AB_ADMIN_DESCRIPTION_A PT_STRING8 PR_EMS_AB_ADMIN_DESCRIPTION_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1024
Maximum length


PR_EMS_AB_ADMIN_DISPLAY_NAME

The PR_EMS_AB_ADMIN_DISPLAY_NAME property contains the Administrator display name for a directory Top object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x804b
Property type: | PR_EMS_AB_ADMIN_DISPLAY_NAME PT_TSTRING PR_EMS_AB_ADMIN_DISPLAY_NAME_A PT_STRING8 PR_EMS_AB_ADMIN_DISPLAY_NAME_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_ADMIN_EXTENSION_DLL

The PR_EMS_AB_ADMIN_EXTENSION_DLL property contains the name of the Administrator extension DLL associated with an Admin-Extension object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Admin-Extension objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x804c
Property type: | PR_EMS_AB_ADMIN_EXTENSION_DLL PT_TSTRING PR_EMS_AB_ADMIN_EXTENSION_DLL_A PT_STRING8 PR_EMS_AB_ADMIN_EXTENSION_DLL_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
255
Maximum length

Remarks

The PR_EMS_AB_ADMIN_EXTENSION_DLL property holds the name of the DLL that adds one or more property pages to any object. This is the name of the DLL without the path, which is automatically prepended as:

\\<server>\Add-ins\<extension-name>\<machine>

For example,

\\davidand1\Add-ins\SMTP\I386\IMCADMIN.DLL

The relationship between an object and an Admin-Extension object

See Also

PR_EMS_AB_EXTENSION_NAME, PR_EMS_AB_EXTENSION_NAME_INHERITED


PR_EMS_AB_ALIASED_OBJECT_NAME

The PR_EMS_AB_ALIASED_OBJECT_NAME property is reserved for internal use.


PR_EMS_AB_ALT_RECIPIENT

The PR_EMS_AB_ALT_RECIPIENT property contains the distinguished name of an alternate recipient mailbox that will receive all incoming mail for a mailbox.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x804e
Property type: | PR_EMS_AB_ALT_RECIPIENT PT_TSTRING PR_EMS_AB_ALT_RECIPIENT_A PT_STRING8 PR_EMS_AB_ALT_RECIPIENT_O PT_OBJECT PR_EMS_AB_ALT_RECIPIENT_T PT_TSTRING PR_EMS_AB_ALT_RECIPIENT_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length

See Also

PR_EMS_AB_DELIVER_AND_REDIRECT


PR_EMS_AB_ALT_RECIPIENT_BL

The PR_EMS_AB_ALT_RECIPIENT_BL property contains the backlink to an alternate recipient for a mail recipient.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x804f
Property type: | PR_EMS_AB_ALT_RECIPIENT_BL PT_MV_TSTRING PR_EMS_AB_ALT_RECIPIENT_BL_A PT_MV_STRING8 PR_EMS_AB_ALT_RECIPIENT_BL_O PT_OBJECT PR_EMS_AB_ALT_RECIPIENT_BL_T PT_MV_TSTRING PR_EMS_AB_ALT_RECIPIENT_BL_W PT_MV_UNICODE
Access: | Read-only
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_ANCESTOR_ID

The PR_EMS_AB_ANCESTOR_ID property is reserved for internal use.


PR_EMS_AB_ASSOC_NT_ACCOUNT

The PR_EMS_AB_ASSOC_NT_ACCOUNT property contains the primary Windows NT account associated with a mailbox.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8027
Property type: | PT_BINARY
Access: | Read/write

Values

1
Minimum length
256
Maximum length

Remarks

The PR_EMS_AB_ASSOC_NT_ACCOUNT and PR_EMS_AB_NT_SECURITY_DESCRIPTOR properties are used by Administrator program components to establish an association between a mailbox and a Windows NT account. For example, if you have selected the option to delete Windows NT accounts when a mailbox is deleted, then this is the Windows NT account that will be deleted.

After getting the PR_EMS_AB_ASSOC_NT_ACCOUNT property, call LookupAccountSid(), as shown in the following sample code:

PSID         psid = NULL;
    SID_NAME_USE snu  = {0};
    psid = lpProps.Value.bin.lpb;
    LookupAccountSid(NULL, psid, szAccount, &cchAccount,
    szDomain, &cchDomain, &snu);

See Also

PR_EMS_AB_NT_SECURITY_DESCRIPTOR


PR_EMS_AB_ASSOC_REMOTE_DXA

The PR_EMS_AB_ASSOC_REMOTE_DXA property is reserved for internal use.


PR_EMS_AB_ASSOCIATION_LIFETIME

The PR_EMS_AB_ASSOCIATION_LIFETIME property is reserved for internal use.


PR_EMS_AB_AUTH_ORIG_BL

The PR_EMS_AB_AUTH_ORIG_BL property is reserved for internal use.


PR_EMS_AB_AUTHORITY_REVOCATION_LIST

The PR_EMS_AB_AUTHORITY_REVOCATION_LIST property is reserved for internal use.


PR_EMS_AB_AUTHORIZED_DOMAIN

The PR_EMS_AB_AUTHORIZED_DOMAIN property is reserved for internal use.


PR_EMS_AB_AUTHORIZED_PASSWORD

The PR_EMS_AB_AUTHORIZED_PASSWORD property is reserved for internal use.


PR_EMS_AB_AUTHORIZED_USER

The PR_EMS_AB_AUTHORIZED_USER property is reserved for internal use.


PR_EMS_AB_AUTOREPLY

The PR_EMS_AB_AUTOREPLY property is reserved for internal use.


PR_EMS_AB_AUTOREPLY_MESSAGE

The PR_EMS_AB_AUTOREPLY_MESSAGE property contains the message that is sent when the Out of Office rule is applied and the Out of Office Assistant is set.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x800a
Property type: | PR_EMS_AB_AUTOREPLY_MESSAGE PT_TSTRING PR_EMS_AB_AUTOREPLY_MESSAGE_A PT_STRING8 PR_EMS_AB_AUTOREPLY_MESSAGE_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1024
Maximum length

See Also

PR_EMS_AB_AUTOREPLY_SUBJECT


PR_EMS_AB_AUTOREPLY_SUBJECT

The PR_EMS_AB_AUTOREPLY_SUBJECT property contains the subject line for an Out of Office message.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x803e
Property type: | PR_EMS_AB_AUTOREPLY_SUBJECT PT_TSTRING PR_EMS_AB_AUTOREPLY_SUBJECT_A PT_STRING8 PR_EMS_AB_AUTOREPLY_SUBJECT_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

0
Minimum length
256
Maximum length

See Also

PR_EMS_AB_AUTOREPLY_MESSAGE


PR_EMS_AB_BUSINESS_CATEGORY

The PR_EMS_AB_BUSINESS_CATEGORY property is reserved for internal use.


PR_EMS_AB_BUSINESS_ROLES

The PR_EMS_AB_BUSINESS_ROLES property is reserved for internal use.


PR_EMS_AB_CA_CERTIFICATE

The PR_EMS_AB_CA_CERTIFICATE property is reserved for internal use.


PR_EMS_AB_CAN_CREATE_PF

The PR_EMS_AB_CAN_CREATE_PF property is reserved for internal use.


PR_EMS_AB_CAN_CREATE_PF_BL

The PR_EMS_AB_CAN_CREATE_PF_BL property is reserved for internal use.


PR_EMS_AB_CAN_CREATE_PF_DL

The PR_EMS_AB_CAN_CREATE_PF_DL property is reserved for internal use.


PR_EMS_AB_CAN_CREATE_PF_DL_BL

The PR_EMS_AB_CAN_CREATE_PF_DL_BL property is reserved for internal use.


PR_EMS_AB_CAN_NOT_CREATE_PF

The PR_EMS_AB_CAN_NOT_CREATE_PF property is reserved for internal use.


PR_EMS_AB_CAN_NOT_CREATE_PF_BL

The PR_EMS_AB_CAN_NOT_CREATE_PF_BL property is reserved for internal use.


PR_EMS_AB_CAN_NOT_CREATE_PF_DL

The PR_EMS_AB_CAN_NOT_CREATE_PF_DL property is reserved for internal use.


PR_EMS_AB_CAN_NOT_CREATE_PF_DL_BL

The PR_EMS_AB_CAN_NOT_CREATE_PF_DL_BL property is reserved for internal use.


PR_EMS_AB_CAN_PRESERVE_DNS

The PR_EMS_AB_CAN_PRESERVE_DNS property is reserved for internal use.


PR_EMS_AB_CERTIFICATE_REVOCATION_LIST

The PR_EMS_AB_CERTIFICATE_REVOCATION_LIST property is reserved for internal use.


PR_EMS_AB_CLOCK_ALERT_OFFSET

The PR_EMS_AB_CLOCK_ALERT_OFFSET property is reserved for internal use.


PR_EMS_AB_CLOCK_ALERT_REPAIR

The PR_EMS_AB_CLOCK_ALERT_REPAIR property is reserved for internal use.


PR_EMS_AB_CLOCK_WARNING_OFFSET

The PR_EMS_AB_CLOCK_WARNING_OFFSET property is reserved for internal use.


PR_EMS_AB_CLOCK_WARNING_REPAIR

The PR_EMS_AB_CLOCK_WARNING_REPAIR property is reserved for internal use.


PR_EMS_AB_COMPUTER_NAME

The PR_EMS_AB_COMPUTER_NAME property contains the name of the computer running a mailbox agent or gateway service.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox-Agent, Mail-Gateway, and Add-In objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8065
Property type: | PR_EMS_AB_COMPUTER_NAME PT_TSTRING PR_EMS_AB_COMPUTER_NAME_A PT_STRING8 PR_EMS_AB_COMPUTER_NAME_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_CONNECTED_DOMAINS

The PR_EMS_AB_CONNECTED_DOMAINS property is reserved for internal use.


PR_EMS_AB_CONTAINER_INFO

The PR_EMS_AB_CONTAINER_INFO property is reserved for internal use.


PR_EMS_AB_COST

The PR_EMS_AB_COST property contains the relative cost for routing messages through a particular site connector.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Site-Connector objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8068
Property type: | PT_LONG
Access: | Read/write

Values

1
Minimum (default)
100
Maximum


PR_EMS_AB_COUNTRY_NAME

The PR_EMS_AB_COUNTRY_NAME property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway and Country objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8069
Property type: | PR_EMS_AB_COUNTRY_NAME PT_TSTRING PR_EMS_AB_COUNTRY_NAME_A PT_STRING8 PR_EMS_AB_COUNTRY_NAME_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
3
Maximum length


PR_EMS_AB_CROSS_CERTIFICATE_PAIR

The PR_EMS_AB_CROSS_CERTIFICATE_PAIR property is reserved for internal use.


PR_EMS_AB_DELIV_CONT_LENGTH

The PR_EMS_AB_DELIV_CONT_LENGTH property contains the maximum message size (in kilobytes) for a gateway or mail recipient.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway, Mail-Recipient, and MTA objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x806a
Property type: | PT_LONG
Access: | Read/write

Values

0
0K bytes
Absent
No limit


PR_EMS_AB_DELIV_EITS

The PR_EMS_AB_DELIV_EITS property contains deliverable encoded information types (EITs) for a mail recipient, gateway, or message transfer agent (MTA).

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway, Mail-Recipient, and MTA objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x806b
Property type: | PT_MV_BINARY
Access: | Read/write


PR_EMS_AB_DELIV_EXT_CONT_TYPES

The PR_EMS_AB_DELIV_EXT_CONT_TYPES property contains deliverable external content types for an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway, Mail Recipient, and MTA objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x806c
Property type: | PT_MV_BINARY
Access: | Read/write


PR_EMS_AB_DELIVER_AND_REDIRECT

The PR_EMS_AB_DELIVER_AND_REDIRECT property determines whether the original recipient is to receive a copy of a message that has been redirected to an alternative recipient.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x806d
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = A copy of the message is not sent to the original recipient.
1
TRUE = A copy of the message is sent to the original recipient.

Remarks

When set to TRUE, both the original and alternate recipients receive a copy of the message.

See Also

PR_EMS_AB_ALT_RECIPIENT


PR_EMS_AB_DELIVERY_MECHANISM

The PR_EMS_AB_DELIVERY_MECHANISM property contains the mechanism by which mail is delivered to an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Exchange-Admin-Service, Local-DXA, Mailbox, Mail-Gateway, MHS-Message-Store, MHS-Public-Store, MSFT-DSA, and Public-Folder objects (directory objects) . These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface
Identifier: | 0x806e
Property type: | PT_LONG
Access: | Read/write

Values

0
Message Store (MDB)
1
APIA Delivery Queue
2
XAPIA Retrieval Queue
3
OSI


PR_EMS_AB_DESCRIPTION

The PR_EMS_AB_DESCRIPTION property contains an optional description of an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x806f
Property type: | PR_EMS_AB_DESCRIPTION PT_MV_TSTRING PR_EMS_AB_DESCRIPTION_A PT_MV_STRING8 PR_EMS_AB_DESCRIPTION_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1024
Maximum length


PR_EMS_AB_DESTINATION_INDICATOR

The PR_EMS_AB_DESTINATION_INDICATOR property is reserved for internal use.


PR_EMS_AB_DIAGNOSTIC_REG_KEY

The PR_EMS_AB_DIAGNOSTIC_REG_KEY property is reserved for internal use.


PR_EMS_AB_DISPLAY_NAME_OVERRIDE

The PR_EMS_AB_DISPLAY_NAME_OVERRIDE property determines whether the display name set by the administrator can be overridden by a non-administrator.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Public-Folder objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8001
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Display name cannot be set by a nonadministrator.
1
TRUE = Display name can be set by a nonadministrator.


PR_EMS_AB_DISPLAY_NAME_PRINTABLE

The PR_EMS_AB_DISPLAY_NAME_PRINTABLE property contains the printable string version of the display name.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x39ff
Property type: | PR_EMS_AB_DISPLAY_NAME_PRINTABLE PT_TSTRING PR_EMS_AB_DISPLAY_NAME_PRINTABLE_A PT_STRING8 PR_EMS_AB_DISPLAY_NAME_PRINTABLE_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length

Remarks

The PR_EMS_AB_DISPLAY_NAME_PRINTABLE property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid when reading a property from an object copied into another address book provider.

The printable string version of the display name is required because the normal display name may contain extended characters that cannot be displayed by some mail systems. The printable string display name supports only the first 128 ASCII characters.


PR_EMS_AB_DL_MEM_REJECT_PERMS_BL

The PR_EMS_AB_DL_MEM_REJECT_PERMS_BL property is reserved for internal use.


PR_EMS_AB_DL_MEM_SUBMIT_PERMS_BL

The PR_EMS_AB_DL_MEM_SUBMIT_PERMS_BL property is reserved for internal use.


PR_EMS_AB_DL_MEMBER_RULE

The PR_EMS_AB_DL_MEMBER_RULE property is reserved for internal use.


PR_EMS_AB_DOMAIN_DEF_ALT_RECIP

The PR_EMS_AB_DOMAIN_DEF_ALT_RECIP property contains the recipient to which mail is to be delivered when all routing fails.

Quick Info

Header file: | EMSABTAG.H
Applies to: | MTA-Cfg objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8075
Property type: | PR_EMS_AB_DOMAIN_DEF_ALT_RECIP PT_TSTRING PR_EMS_AB_DOMAIN_DEF_ALT_RECIP_A PT_STRING8 PR_EMS_AB_DOMAIN_DEF_ALT_RECIP_O PT_OBJECT PR_EMS_AB_DOMAIN_DEF_ALT_RECIP_T PT_TSTRING PR_EMS_AB_DOMAIN_DEF_ALT_RECIP_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_DOMAIN_NAME

The PR_EMS_AB_DOMAIN_NAME property is reserved for internal use.


PR_EMS_AB_DSA_SIGNATURE

The PR_EMS_AB_DSA_SIGNATURE property is reserved for internal use.


PR_EMS_AB_DXA_ADMIN_COPY

The PR_EMS_AB_DXA_ADMIN_COPY property is reserved for internal use.


PR_EMS_AB_DXA_ADMIN_FORWARD

The PR_EMS_AB_DXA_ADMIN_FORWARD property is reserved for internal use.


PR_EMS_AB_DXA_ADMIN_UPDATE

The PR_EMS_AB_DXA_ADMIN_UPDATE property is reserved for internal use.


PR_EMS_AB_DXA_APPEND_REQCN

The PR_EMS_AB_DXA_APPEND_REQCN property is reserved for internal use.


PR_EMS_AB_DXA_CONF_CONTAINER_LIST

The PR_EMS_AB_DXA_CONF_CONTAINER_LIST property is reserved for internal use.


PR_EMS_AB_DXA_CONF_REQ_TIME

The PR_EMS_AB_DXA_CONF_REQ_TIME property is reserved for internal use.


PR_EMS_AB_DXA_CONF_SEQ

The PR_EMS_AB_DXA_CONF_SEQ property is reserved for internal use.


PR_EMS_AB_DXA_CONF_SEQ_USN

The PR_EMS_AB_DXA_CONF_SEQ_USN property is reserved for internal use.


PR_EMS_AB_DXA_EXCHANGE_OPTIONS

The PR_EMS_AB_DXA_EXCHANGE_OPTIONS property is reserved for internal use.


PR_EMS_AB_DXA_EXPORT_NOW

The PR_EMS_AB_DXA_EXPORT_NOW property is reserved for internal use.


PR_EMS_AB_DXA_FLAGS

The PR_EMS_AB_DXA_FLAGS property is reserved for internal use.


PR_EMS_AB_DXA_IMP_SEQ

The PR_EMS_AB_DXA_IMP_SEQ property is reserved for internal use.


PR_EMS_AB_DXA_IMP_SEQ_TIME

The PR_EMS_AB_DXA_IMP_SEQ_TIME property is reserved for internal use.


PR_EMS_AB_DXA_IMP_SEQ_USN

The PR_EMS_AB_DXA_IMP_SEQ_USN property is reserved for internal use.


PR_EMS_AB_DXA_IMPORT_NOW

The PR_EMS_AB_DXA_IMPORT_NOW property is reserved for internal use.


PR_EMS_AB_DXA_IN_TEMPLATE_MAP

The PR_EMS_AB_DXA_IN_TEMPLATE_MAP property is reserved for internal use.


PR_EMS_AB_DXA_LOCAL_ADMIN

The PR_EMS_AB_DXA_LOCAL_ADMIN property is reserved for internal use.


PR_EMS_AB_DXA_LOGGING_LEVEL

The PR_EMS_AB_DXA_LOGGING_LEVEL property is reserved for internal use.


PR_EMS_AB_DXA_NATIVE_ADDRESS_TYPE

The PR_EMS_AB_DXA_NATIVE_ADDRESS_TYPE property is reserved for internal use.


PR_EMS_AB_DXA_OUT_TEMPLATE_MAP

The PR_EMS_AB_DXA_OUT_TEMPLATE_MAP property is reserved for internal use.


PR_EMS_AB_DXA_PASSWORD

The PR_EMS_AB_DXA_PASSWORD property is reserved for internal use.


PR_EMS_AB_DXA_PREV_EXCHANGE_OPTIONS

The PR_EMS_AB_DXA_PREV_EXCHANGE_OPTIONS property is reserved for internal use.


PR_EMS_AB_DXA_PREV_EXPORT_NATIVE_ONLY

The PR_EMS_AB_DXA_PREV_EXPORT_NATIVE_ONLY property is reserved for internal use.


PR_EMS_AB_DXA_PREV_IN_EXCHANGE_SENSITIVIT

The PR_EMS_AB_DXA_PREV_IN_EXCHANGE_SENSITIVIT property is reserved for internal use.


PR_EMS_AB_DXA_PREV_REMOTE_ENTRIES

The PR_EMS_AB_DXA_PREV_REMOTE_ENTRIES property is reserved for internal use.


PR_EMS_AB_DXA_PREV_REPLICATION_SENSITIVITY

The PR_EMS_AB_DXA_PREV_REPLICATION_SENSITIVITY property is reserved for internal use.


PR_EMS_AB_DXA_PREV_TEMPLATE_OPTIONS

The PR_EMS_AB_DXA_PREV_TEMPLATE_OPTIONS property is reserved for internal use.


PR_EMS_AB_DXA_PREV_TYPES

The PR_EMS_AB_DXA_PREV_TYPES property is reserved for internal use.


PR_EMS_AB_DXA_RECIPIENT_CP

The PR_EMS_AB_DXA_RECIPIENT_CP property is reserved for internal use.


PR_EMS_AB_DXA_REMOTE_CLIENT

The PR_EMS_AB_DXA_REMOTE_CLIENT property is reserved for internal use.


PR_EMS_AB_DXA_REQ_SEQ

The PR_EMS_AB_DXA_REQ_SEQ property is reserved for internal use.


PR_EMS_AB_DXA_REQ_SEQ_TIME

The PR_EMS_AB_DXA_REQ_SEQ_TIME property is reserved for internal use.


PR_EMS_AB_DXA_REQ_SEQ_USN

The PR_EMS_AB_DXA_REQ_SEQ_USN property is reserved for internal use.


PR_EMS_AB_DXA_REQNAME

The PR_EMS_AB_DXA_REQNAME property is reserved for internal use.


PR_EMS_AB_DXA_SVR_SEQ

The PR_EMS_AB_DXA_SVR_SEQ property is reserved for internal use.


PR_EMS_AB_DXA_SVR_SEQ_TIME

The PR_EMS_AB_DXA_SVR_SEQ_TIME property is reserved for internal use.


PR_EMS_AB_DXA_SVR_SEQ_USN

The PR_EMS_AB_DXA_SVR_SEQ_USN property is reserved for internal use.


PR_EMS_AB_DXA_TASK

The PR_EMS_AB_DXA_TASK property is reserved for internal use.


PR_EMS_AB_DXA_TEMPLATE_OPTIONS

The PR_EMS_AB_DXA_TEMPLATE_OPTIONS property is reserved for internal use.


PR_EMS_AB_DXA_TEMPLATE_TIMESTAMP

The PR_EMS_AB_DXA_TEMPLATE_TIMESTAMP property is reserved for internal use.


PR_EMS_AB_DXA_TYPES

The PR_EMS_AB_DXA_TYPES property is reserved for internal use.


PR_EMS_AB_DXA_UNCONF_CONTAINER_LIST

The PR_EMS_AB_DXA_UNCONF_CONTAINER_LIST property is reserved for internal use.


PR_EMS_AB_ENCAPSULATION_METHOD

The PR_EMS_AB_ENCAPSULATION_METHOD property contains the default encapsulation instructions to be used for recipients on a gateway.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80a2
Property type: | PT_LONG
Access: | Read/write


PR_EMS_AB_ENCRYPT

The PR_EMS_AB_ENCRYPT property is reserved for internal use.


PR_EMS_AB_ENCRYPT_ALG_LIST_NA

The PR_EMS_AB_ENCRYPT_ALG_LIST_NA property is reserved for internal use.


PR_EMS_AB_ENCRYPT_ALG_LIST_OTHER

The PR_EMS_AB_ENCRYPT_ALG_LIST_OTHER property is reserved for internal use.


PR_EMS_AB_ENCRYPT_ALG_SELECTED_NA

The PR_EMS_AB_ENCRYPT_ALG_SELECTED_NA property is reserved for internal use.


PR_EMS_AB_ENCRYPT_ALG_SELECTED_OTHER

The PR_EMS_AB_ENCRYPT_ALG_SELECTED_OTHER property is reserved for internal use.


PR_EMS_AB_EXPAND_DLS_LOCALLY

The PR_EMS_AB_EXPAND_DLS_LOCALLY property is reserved for internal use.


PR_EMS_AB_EXPIRATION_TIME

The PR_EMS_AB_EXPIRATION_TIME property contains the expiration time for a mailbox or distribution list.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8028
Property type: | PT_SYSTIME
Access: | Read/write

Values

11
Minimum length
17
Maximum length


PR_EMS_AB_EXPORT_CONTAINERS

The PR_EMS_AB_EXPORT_CONTAINERS property is reserved for internal use.


PR_EMS_AB_EXPORT_CUSTOM_RECIPIENTS

The PR_EMS_AB_EXPORT_CUSTOM_RECIPIENTS property is reserved for internal use.


PR_EMS_AB_EXTENDED_CHARS_ALLOWED

The PR_EMS_AB_EXTENDED_CHARS_ALLOWED property is reserved for internal use.


PR_EMS_AB_EXTENSION_ATTRIBUTE_X

The PR_EMS_AB_EXTENSION_ATTRIBUTE_X properties are general attributes available to application developers or administrators.

Quick Info

Header file: EMSABTAG.H
Applies to: Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: PR_EMS_AB_EXTENSION_ATTRIBUTE_1 0x802d

PR_EMS_AB_EXTENSION_ATTRIBUTE_2 0x802e

PR_EMS_AB_EXTENSION_ATTRIBUTE_3 0x802f

PR_EMS_AB_EXTENSION_ATTRIBUTE_4 0x8030

PR_EMS_AB_EXTENSION_ATTRIBUTE_5 0x8031

PR_EMS_AB_EXTENSION_ATTRIBUTE_6 0x8032

PR_EMS_AB_EXTENSION_ATTRIBUTE_7 0x8033

PR_EMS_AB_EXTENSION_ATTRIBUTE_8 0x8034

PR_EMS_AB_EXTENSION_ATTRIBUTE_9 0x8035

PR_EMS_AB_EXTENSION_ATTRIBUTE_10 0x8036
Property type: PR_EMS_AB_EXTENSION_ATTRIBUTE_1 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_1_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_1_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_2 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_2_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_2_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_3 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_3_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_3_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_4 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_4_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_4_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_5 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_5_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_5_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_6 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_6_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_6_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_7 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_7_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_7_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_8 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_8_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_8_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_9 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_9_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_9_W PT_UNICODE

PR_EMS_AB_EXTENSION_ATTRIBUTE_10 PT_TSTRING

PR_EMS_AB_EXTENSION_ATTRIBUTE_10_A PT_STRING8

PR_EMS_AB_EXTENSION_ATTRIBUTE_10_W PT_UNICODE
Access: Read/write
Unicode: Yes

Values

1
Minimum length
1024
Maximum length

Remarks

The PR_EMS_AB_EXTENSION_ATTRIBUTE_X property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid when reading a property from an object copied into another address book provider.


PR_EMS_AB_EXTENSION_DATA

The PR_EMS_AB_EXTENSION_DATA property contains a list of data sections specific to an extension.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80a8
Property type: | PT_MV_BINARY
Access: | Read/write

Remarks

The PR_EMS_AB_EXTENSION_DATA property contains a list of data sections used to store configuration information to be displayed by an Administrator extension property page.

Each binary value is structured as follows:

Binary value structure

The property page can be assigned any name, but it must be unique.


PR_EMS_AB_EXTENSION_NAME

The PR_EMS_AB_EXTENSION_NAME property contains the name of an Admin-Extension object that corresponds to the Administrator extension DLL that adds property pages to an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80a9
Property type: | PR_EMS_AB_EXTENSION_NAME PT_MV_TSTRING PR_EMS_AB_EXTENSION_NAME_A PT_MV_STRING8 PR_EMS_AB_EXTENSION_NAME_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
255
Maximum length

Remarks

Property pages added using the PR_EMS_AB_EXTENSION_NAME property are not inherited by the children of the object that has this property.

This property points to an Admin-Extension object under the Configuration/Add-ins Container. The name of the Admin-Extension object is created by taking the contents of the property, adding a colon (:) and then adding a string that represents the computer type. For example: i386.

See Also

PR_EMS_AB_EXTENSION_NAME_INHERITED


PR_EMS_AB_EXTENSION_NAME_INHERITED

The PR_EMS_AB_EXTENSION_NAME_INHERITED property contains the name of an Admin-Extension object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80aa
Property type: | PR_EMS_AB_EXTENSION_NAME_INHERITED PT_MV_TSTRING PR_EMS_AB_EXTENSION_NAME_INHERITED_A PT_MV_STRING8 PR_EMS_AB_EXTENSION_NAME_INHERITED_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
255
Maximum length

Remarks

The PR_EMS_AB_EXTENSION_NAME_INHERITED property is the same as PR_EMS_AB_EXTENSION_NAME, except that the Admin-Extension object is inherited by all the object’s children. For example, this property is used to add a property page to all mail recipients under a specified container.

See Also

PR_EMS_AB_EXTENSION_NAME


PR_EMS_AB_FACSIMILE_TELEPHONE_NUMBER

The PR_EMS_AB_FACSIMILE_TELEPHONE_NUMBER property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Organization, Organizational-Person, Organizational-Role, Organizational-Unit, and Residential-Person objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80ab
Property type: | PT_MV_BINARY
Access: | Read/write


PR_EMS_AB_FILE_VERSION

The PR_EMS_AB_FILE_VERSION property contains the file version stamp for DLLs used by the object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Addr-Type, Admin-Extension, and DSA objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80ac
Property type: | PT_BINARY
Access: | Read/write

Values

1 (2 hex digits)
Minimum length
8 (16 hex digits)
Maximum length

Remarks

The PR_EMS_AB_FILE_VERSION property contains a 64-bit file version identifier in Windows FILEVERSION format. Objects associated with DLLs use the PR_EMS_AB_FILE_VERSION property to check that the correct version of a DLL is being used.


PR_EMS_AB_FILTER_LOCAL_ADDRESSES

The PR_EMS_AB_FILTER_LOCAL_ADDRESSES property determines if an address matches a local address space (ADMD, Country, PRMD, Organization, or Organization Units [1-4]). If a local mail recipient cannot be found in the directory, a nondelivery report is generated for the message.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Site-Addressing and MTA objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80ad
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE (default)
1
TRUE


PR_EMS_AB_FOLDER_PATHNAME

The PR_EMS_AB_FOLDER_PATHNAME property contains the full path name of the folder.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Public-Folder objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8004
Property type: | PR_EMS_AB_FOLDER_PATHNAME PT_TSTRING PR_EMS_AB_FOLDER_PATHNAME_A PT_STRING8 PR_EMS_AB_FOLDER_PATHNAME_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Remarks

The PR_EMS_AB_FOLDER_PATHNAME property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid when reading a property from an object copied into another address book provider.


PR_EMS_AB_FOLDERS_CONTAINER

The PR_EMS_AB_FOLDERS_CONTAINER property contains the distinguished name of the container into which new public folders are to be created.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Information-Store-Cfg objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80ae
Property type: | PR_EMS_AB_FOLDERS_CONTAINER PT_TSTRING PR_EMS_AB_FOLDERS_CONTAINER_A PT_STRING8 PR_EMS_AB_FOLDERS_CONTAINER_O PT_OBJECT PR_EMS_AB_FOLDERS_CONTAINER_T PT_TSTRING PR_EMS_AB_FOLDERS_CONTAINER_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_GARBAGE_COLL_PERIOD

The PR_EMS_AB_GARBAGE_COLL_PERIOD property contains the number of hours representing the interval at which garbage is collected.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Directory-Cfg objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80af
Property type: | PT_LONG
Access: | Read/write

Remarks

During garbage collection, objects older than the tombstone lifetime are permanently deleted from the system. The directory is then compacted for maximum efficiency.

See Also

PR_EMS_AB_IS_DELETED, PR_EMS_AB_TOMBSTONE_LIFETIME


PR_EMS_AB_GATEWAY_LOCAL_CRED

The PR_EMS_AB_GATEWAY_LOCAL_CRED property is reserved for internal use.


PR_EMS_AB_GATEWAY_LOCAL_DESIG

The PR_EMS_AB_GATEWAY_LOCAL_DESIG property is reserved for internal use.


PR_EMS_AB_GATEWAY_PROXY

The PR_EMS_AB_GATEWAY_PROXY property contains a list of proxy addresses that is unique for a domain.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Site-Addressing objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80b2
Property type: | PR_EMS_AB_GATEWAY_PROXY PT_MV_TSTRING PR_EMS_AB_GATEWAY_PROXY_A PT_MV_STRING8 PR_EMS_AB_GATEWAY_PROXY_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1123
Maximum length


PR_EMS_AB_GATEWAY_ROUTING_TREE

The PR_EMS_AB_GATEWAY_ROUTING_TREE property is reserved for internal use.


PR_EMS_AB_GWART_LAST_MODIFIED

The PR_EMS_AB_GWART_LAST_MODIFIED property is reserved for internal use.


PR_EMS_AB_HAS_FULL_REPLICA_NCS

The PR_EMS_AB_HAS_FULL_REPLICA_NCS property is reserved for internal use.


PR_EMS_AB_HAS_MASTER_NCS

The PR_EMS_AB_HAS_MASTER_NCS property is reserved for internal use.


PR_EMS_AB_HELP_DATA16

The PR_EMS_AB_HELP_DATA16 property contains the binary Help information template for a 16-bit client.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Display-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x803a
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_EMS_AB_HELP_DATA16 property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid when reading a property from an object copied into another address book provider. The data is in a Windows Help file format.


PR_EMS_AB_HELP_DATA32

The PR_EMS_AB_HELP_DATA32 property contains the binary Help information for the template for the 32-bit client.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Display-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8010
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_EMS_AB_HELP_DATA32 property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid when reading a property from an object copied into another address book provider.


PR_EMS_AB_HELP_FILE_NAME

The PR_EMS_AB_HELP_FILE_NAME property contains the name of the Help file for the Display-Template object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Display-Template objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x803b
Property type: | PR_EMS_AB_HELP_FILE_NAME PT_TSTRING PR_EMS_AB_HELP_FILE_NAME_A PT_STRING8 PR_EMS_AB_HELP_FILE_NAME_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
13
Maximum length

Remarks

The PR_EMS_AB_HELP_FILE_NAME property is valid only when reading a property from the Microsoft Exchange Server address book. It is not valid after a recipient object has been copied to another type of address book. (e.g., a personal address book).


PR_EMS_AB_HEURISTICS

The PR_EMS_AB_HEURISTICS property is reserved for internal use.


PR_EMS_AB_HIDE_DL_MEMBERSHIP

The PR_EMS_AB_HIDE_DL_MEMBERSHIP property determines whether the individual members of a distribution list are to be listed (and able to be viewed by other users) or unlisted.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Distribution-List objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80b8
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Membership is not displayed.
1
TRUE = Membership is displayed.


PR_EMS_AB_HIDE_FROM_ADDRESS_BOOK

The PR_EMS_AB_HIDE_FROM_ADDRESS_BOOK property contains a flag that indicates whether the information for a Mail-Recipient object is displayed in the address book.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80b9
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE (default) = Mail-Recipient object information is not displayed.
1
TRUE = Mail-Recipient object information is displayed.


PR_EMS_AB_HOME_MDB

The PR_EMS_AB_HOME_MDB property contains the distinguished name of the home information store used by a mail recipient or gateway.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient and Gateway objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8006
Property type: | PR_EMS_AB_HOME_MDB PT_TSTRING PR_EMS_AB_HOME_MDB_A PT_STRING8 PR_EMS_AB_HOME_MDB_O PT_OBJECT PR_EMS_AB_HOME_MDB_T PT_TSTRING PR_EMS_AB_HOME_MDB_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_HOME_MDB_BL

The PR_EMS_AB_HOME_MDB_BL property contains a backlink to the list of the users associated with a server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8014
Property type: | PR_EMS_AB_HOME_MDB_BL PT_MV_TSTRING PR_EMS_AB_HOME_MDB_BL_A PT_MV_STRING8 PR_EMS_AB_HOME_MDB_BL_O PT_OBJECT PR_EMS_AB_HOME_MDB_BL_T PT_MV_TSTRING PR_EMS_AB_HOME_MDB_BL_W PT_MV_UNICODE
Access: | Read-only
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_HOME_MTA

The PR_EMS_AB_HOME_MTA property is reserved for internal use.


PR_EMS_AB_HOME_PUBLIC_SERVER

The PR_EMS_AB_HOME_PUBLIC_SERVER property contains the name of the home public server for mailboxes on an information store.

Quick Info

Header file: | EMSABTAG.H
Applies to: | MHS-Message-Store objects (directory objects). These objects appear to MAPI as messaging user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x803f
Property type: | PR_EMS_AB_HOME_PUBLIC_SERVER PT_TSTRING PR_EMS_AB_HOME_PUBLIC_SERVER_A PT_STRING8 PR_EMS_AB_HOME_PUBLIC_SERVER_O PT_OBJECT PR_EMS_AB_HOME_PUBLIC_SERVER_T PT_TSTRING PR_EMS_AB_HOME_PUBLIC_SERVER_W PT_UNICODE
Access: | Read-only
Unicode: | Yes


PR_EMS_AB_IMPORT_CONTAINER

The PR_EMS_AB_IMPORT_CONTAINER property is reserved for internal use.


PR_EMS_AB_IMPORT_SENSITIVITY

The PR_EMS_AB_IMPORT_SENSITIVITY property is reserved for internal use.


PR_EMS_AB_IMPORTED_FROM

The PR_EMS_AB_IMPORTED_FROM property is used by directory synchronization agents to identify objects that they imported.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8042
Property type: | PR_EMS_AB_IMPORTED_FROM PT_TSTRING PR_EMS_AB_IMPORTED_FROM_A PT_STRING8 PR_EMS_AB_IMPORTED_FROM_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1024
Maximum length

Remarks

If a directory synchronization agent adds a mailbox and then initiates a request to Microsoft Exchange Server for all new mailboxes, the agent will receive the mailbox it just added. To avoid loops, the PR_EMS_AB_IMPORTED_FROM property provides a means for the agent to recognize that it created the object.

The standard format for this property is:

Agent Name:Source Identifier

If your directory synchronization agent runs as a service of Windows NT Server, then use the service name for Agent Name.

Source Identifier identifies the foreign source of the imported object. The DIRSYNC sample application included with this SDK has a concept of instances that roughly relates to the name of the foreign data source. The format of Source Identifier is determined by the particular directory synchronization agent.

See DIRSYNC: Importing and Exporting Mailboxes.


PR_EMS_AB_INBOUND_SITES

The PR_EMS_AB_INBOUND_SITES property is reserved for internal use.


PR_EMS_AB_INSTANCE_TYPE

The PR_EMS_AB_INSTANCE_TYPE property is reserved for internal use.


PR_EMS_AB_INTERNATIONAL_ISDN_NUMBER

The PR_EMS_AB_INTERNATIONAL_ISDN_NUMBER property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80be
Property type: | PT_MV_TSTRING
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
16
Maximum length


PR_EMS_AB_INVOCATION_ID

The PR_EMS_AB_INVOCATION_ID property is reserved for internal use.


PR_EMS_AB_IS_DELETED

The PR_EMS_AB_IS_DELETED property is set to TRUE when an object is deleted.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80c0
Property type: | PT_BOOLEAN
Access: | Read-only

Values

0
FALSE = Object is not a tombstone.
1
TRUE = Object is a tombstone

Remarks

The PR_EMS_AB_IS_DELETED property is set to TRUE when an object has been deleted, but not completely removed from the system. An object in this state is called a tombstone. Tombstones are replicated to other servers to inform them that a directory object has been deleted.

See Also

PR_EMS_AB_TOMBSTONE_LIFETIME


PR_EMS_AB_IS_MEMBER_OF_DL

The PR_EMS_AB_IS_MEMBER_OF_DL property contains the distinguished names of all distribution lists of which the object is a member.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8008
Property type: | PR_EMS_AB_IS_MEMBER_OF_DL PT_OBJECT PR_EMS_AB_IS_MEMBER_OF_DL_A PT_MV_STRING8 PR_EMS_AB_IS_MEMBER_OF_DL_O PT_OBJECT PR_EMS_AB_IS_MEMBER_OF_DL_T PT_MV_TSTRING PR_EMS_AB_IS_MEMBER_OF_DL_W PT_MV_UNICODE
Access: | Read-only
Unicode: | Yes

Values

1
Minimum length
256
Maximum length

See Also

PR_EMS_AB_MEMBER


PR_EMS_AB_IS_SINGLE_VALUED

The PR_EMS_AB_IS_SINGLE_VALUED property is reserved for internal use.


PR_EMS_AB_KCC_STATUS

The PR_EMS_AB_KCC_STATUS property is reserved for internal use.


PR_EMS_AB_KM_SERVER

The PR_EMS_AB_KM_SERVER property is reserved for internal use.


PR_EMS_AB_KNOWLEDGE_INFORMATION

The PR_EMS_AB_KNOWLEDGE_INFORMATION property is reserved for internal use.


PR_EMS_AB_LINE_WRAP

The PR_EMS_AB_LINE_WRAP property can be used by gateways to save the maximum allowed message line length.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80c4
Property type: | PT_LONG
Access: | Read/write


PR_EMS_AB_LINK_ID

The PR_EMS_AB_LINK_ID property is reserved for internal use.


PR_EMS_AB_LOCAL_BRIDGE_HEAD

The PR_EMS_AB_LOCAL_BRIDGE_HEAD property is reserved for internal use.


PR_EMS_AB_LOCAL_BRIDGE_HEAD_ADDRESS

The PR_EMS_AB_LOCAL_BRIDGE_HEAD_ADDRESS property is reserved for internal use.


PR_EMS_AB_LOCAL_INITIAL_TURN

The PR_EMS_AB_LOCAL_INITIAL_TURN property is reserved for internal use.


PR_EMS_AB_LOCAL_SCOPE

The PR_EMS_AB_LOCAL_SCOPE property is reserved for internal use.


PR_EMS_AB_LOG_FILENAME

The PR_EMS_AB_LOG_FILENAME property is reserved for internal use.


PR_EMS_AB_LOG_ROLLOVER_INTERVAL

The PR_EMS_AB_LOG_ROLLOVER_INTERVAL property is reserved for internal use.


PR_EMS_AB_MAINTAIN_AUTOREPLY_HISTORY

The PR_EMS_AB_MAINTAIN_AUTOREPLY_HISTORY property is reserved for internal use.


PR_EMS_AB_MANAGER

The PR_EMS_AB_MANAGER property contains the mail address for a mailbox owner's manager, expressed as a distinguished name.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Remote-Address and Mailbox objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8005
Property type: | PR_EMS_AB_MANAGER PT_OBJECT PR_EMS_AB_MANAGER_A PT_STRING8 PR_EMS_AB_MANAGER_O PT_OBJECT PR_EMS_AB_MANAGER_T PT_TSTRING PR_EMS_AB_MANAGER_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_MAPI_DISPLAY_TYPE

The PR_EMS_AB_MAPI_DISPLAY_TYPE property is reserved for internal use.


PR_EMS_AB_MAPI_ID

The PR_EMS_AB_MAPI_ID property is reserved for internal use.


PR_EMS_AB_MAXIMUM_OBJECT_ID

The PR_EMS_AB_MAXIMUM_OBJECT_ID property is reserved for internal use.


PR_EMS_AB_MDB_BACKOFF_INTERVAL

The PR_EMS_AB_MDB_BACKOFF_INTERVAL property contains the number of minutes the information store waits before resending a message to the gateway.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80cf
Property type: | PT_LONG
Access: | Read/write

Remarks

When the number of unread messages in a gateway's mailbox folders (MTS-IN, MTS-OUT, etc) reaches the limit set by PR_EMS_AB_MDB_UNREAD_LIMIT, the information store stops the transfer of messages from the MTA to the gateway for the length of time specified by the PR_EMS_AB_MDB_BACKOFF_INTERVAL property.

See Also

PR_EMS_AB_MDB_UNREAD_LIMIT


PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD

The PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD property contains the number of minutes a message can remain unread by a gateway before the information store will generate a nondelivery report.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80d0
Property type: | PT_LONG
Access: | Read/write

Remarks

The Microsoft Exchange Server information store transfers a message to a gateway by placing the message in the gateway's MTS-OUT folder. If a message remains unread in the MTS-OUT folder for more than the number of minutes set by the PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD property, the information store removes the message from the folder and generates a nondelivery report.


PR_EMS_AB_MDB_OVER_QUOTA_LIMIT

The PR_EMS_AB_MDB_OVER_QUOTA_LIMIT property specifies the maximum amount of storage that the information store allocates to an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Information-Store-Cfg, Public-Folder, Mailbox, MHS-Message-Store and MHS-Public-Store objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80d1
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_EMS_AB_MDB_OVER_QUOTA_LIMIT property determines the number of kilobytes of storage that the Microsoft Exchange Server information store allocates to an object.

For Mailbox and Mailbox-Agent objects:
PR_EMS_AB_MDB_OVER_QUOTA_LIMIT refers to the total amount of storage used by all folders and subfolders. If this value is exceeded, users cannot submit new messages, but can still receive them.

For MHS-Message-Store objects:
PR_EMS_AB_MDB_OVER_QUOTA_LIMIT defines a default value that can be applied to objects in the private and public information stores.

If no PR_EMS_AB_MDB_OVER_QUOTA_LIMIT property is specified on an object, the storage available to the object is not limited. If a value of 0 is specified, no storage is allocated to the object.

For Public-Folder, MHS-Public-Store, Information-Store-Cfg objects:
PR_EMS_AB_MDB_OVER_QUOTA_LIMIT is ignored.


PR_EMS_AB_MDB_STORAGE_QUOTA

The PR_EMS_AB_MDB_STORAGE_QUOTA property specifies the amount of storage that the information store allocates to an object before generating a warning.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox, Mail-Gateway, MHS-Message-Store, Public-Folder, MHS-Public-Store and Information-Store-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80d2
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_EMS_AB_MDB_STORAGE_QUOTA property determines the number of kilobytes of storage that the Microsoft Exchange Server information store allocates to an object before a warning is issued.

For Mailbox, Mailbox-Agent, and Mail-Gateway objects:
PR_EMS_AB_MDB_STORAGE_QUOTA refers to the total amount of storage used by all folders and subfolders. If this value is exceeded, a warning message is sent to the object's owner.

For Public folder objects:
PR_EMS_AB_MDB_STORAGE_QUOTA refers to the total amount of storage used by the public folder. If this value is exceeded, a warning message is sent to the public folder contact.

For MHS-Message-Store and MHS-Public-Store objects:
PR_EMS_AB_MDB_STORAGE_QUOTA defines a default value that can be applied to objects in the private and public information stores.

If no PR_EMS_AB_MDB_STORAGE_QUOTA property is specified on an object, the storage available to the object is not limited. If a value of 0 is specified, no storage is allocated to the object.

For Information-Store-Cfg objects:
PR_EMS_AB_MDB_STORAGE_QUOTA is ignored.


PR_EMS_AB_MDB_UNREAD_LIMIT

The PR_EMS_AB_MDB_UNREAD_LIMIT property contains the maximum number of unread messages allowed in a gateway mailbox.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80d3
Property type: | PT_LONG
Access: | Read/write

Remarks

When the number of unread messages in a gateway's mailbox folders (such as MTS-IN and MTS-OUT) reaches the limit set by the PR_EMS_AB_MDB_UNREAD_LIMIT property, the information store stops the transfer of messages from the MTA to the gateway for the length of time specified by the PR_EMS_AB_MDB_BACKOFF_INTERVAL property.

The PR_EMS_AB_MDB_UNREAD_LIMIT, PR_EMS_AB_MDB_BACKOFF_INTERVAL, and PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD properties are related as follows:

If a gateway service is turned off, messages can continue to be delivered to the gateway's MTS-OUT folder until the number of unread messages reaches PR_EMS_AB_MDB_UNREAD_LIMIT. When this limit is reached, delivery to the gateway stops and additional messages back up in MTA delivery queues.

Unread messages in MTS-OUT are removed and nondelivery reports are generated after PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD minutes. Within PR_EMS_AB_MDB_BACKOFF_INTERVAL minutes, messages can once again be transferred from the MTA to the gateway's MTS-OUT folder.

See Also

PR_EMS_AB_MDB_BACKOFF_INTERVAL, PR_EMS_AB_MDB_MSG_TIME_OUT_PERIOD


PR_EMS_AB_MDB_USE_DEFAULTS

The PR_EMS_AB_MDB_USE_DEFAULTS property determines whether a mailbox or public folder uses the storage quota set on the information store or the storage quota set on the object itself.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox and Public-Folder objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80d4
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Use the storage quota set on the object itself.
1
TRUE = Use the storage quota set on the information store.

Remarks

When the PR_EMS_AB_MDB_USE_DEFAULTS property is set to TRUE, Mailbox and Mailbox-Agent objects take their storage quota settings from the PR_EMS_AB_MDB_STORAGE_QUOTA and PR_EMS_AB_MDB_OVER_QUOTA_LIMIT properties on the server’s MHS-Message-Store object.

When PR_EMS_AB_MDB_USE_DEFAULTS is set to TRUE, Public folder objects take their storage quota settings from the PR_EMS_AB_MDB_STORAGE_QUOTA property on the server's MHS-Public-Store object.

See Also

PR_EMS_AB_MDB_OVER_QUOTA_LIMIT, PR_EMS_AB_MDB_STORAGE_QUOTA


PR_EMS_AB_MEMBER

The PR_EMS_AB_MEMBER property contains the list of members of a distribution list.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Distribution-List and Group-Of-Names objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8009
Property type: | PR_EMS_AB_MEMBER PT_OBJECT PR_EMS_AB_MEMBER_A PT_MV_STRING8 PR_EMS_AB_MEMBER_O PT_OBJECT PR_EMS_AB_MEMBER_T PT_MV_TSTRING PR_EMS_AB_MEMBER_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length

See Also

PR_EMS_AB_IS_MEMBER_OF_DL


PR_EMS_AB_MESSAGE_TRACKING_ENABLED

The PR_EMS_AB_MESSAGE_TRACKING_ENABLED property determines whether this message transfer agent or information store should keep message-tracking information.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Information-Store-Cfg and MTA-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80d5
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Do not keep message-tracking information
1
TRUE = Keep message-tracking information


PR_EMS_AB_MONITOR_CLOCK

The PR_EMS_AB_MONITOR_CLOCK property is reserved for internal use.


PR_EMS_AB_MONITOR_SERVERS

The PR_EMS_AB_MONITOR_SERVERS property is reserved for internal use.


PR_EMS_AB_MONITOR_SERVICES

The PR_EMS_AB_MONITOR_SERVICES property is reserved for internal use.


PR_EMS_AB_MONITORED_CONFIGURATIONS

The PR_EMS_AB_MONITORED_CONFIGURATIONS property is reserved for internal use.


PR_EMS_AB_MONITORED_SERVERS

The PR_EMS_AB_MONITORED_SERVERS property is reserved for internal use.


PR_EMS_AB_MONITORED_SERVICES

The PR_EMS_AB_MONITORED_SERVICES property is reserved for internal use.


PR_EMS_AB_MONITORING_ALERT_DELAY

The PR_EMS_AB_MONITORING_ALERT_DELAY property is reserved for internal use.


PR_EMS_AB_MONITORING_ALERT_UNITS

The PR_EMS_AB_MONITORING_ALERT_UNITS property is reserved for internal use.


PR_EMS_AB_MONITORING_AVAILABILITY_STYLE

The PR_EMS_AB_MONITORING_AVAILABILITY_STYLE property is reserved for internal use.


PR_EMS_AB_MONITORING_AVAILABILITY_WINDOW

The PR_EMS_AB_MONITORING_AVAILABILITY_WINDOW property is reserved for internal use.


PR_EMS_AB_MONITORING_CACHED_VIA_MAIL

The PR_EMS_AB_MONITORING_CACHED_VIA_MAIL property is reserved for internal use.


PR_EMS_AB_MONITORING_CACHED_VIA_RPC

The PR_EMS_AB_MONITORING_CACHED_VIA_RPC property is reserved for internal use.


PR_EMS_AB_MONITORING_ESCALATION_PROCEDURE

The PR_EMS_AB_MONITORING_ESCALATION_PROCEDURE property is reserved for internal use.


PR_EMS_AB_MONITORING_HOTSITE_POLL_INTERVAL

The PR_EMS_AB_MONITORING_HOTSITE_POLL_INTERVAL property is reserved for internal use.


PR_EMS_AB_MONITORING_HOTSITE_POLL_UNITS

The PR_EMS_AB_MONITORING_HOTSITE_POLL_UNITS property is reserved for internal use.


PR_EMS_AB_MONITORING_MAIL_UPDATE_INTERVAL

The PR_EMS_AB_MONITORING_MAIL_UPDATE_INTERVAL property is reserved for internal use.


PR_EMS_AB_MONITORING_MAIL_UPDATE_UNITS

The PR_EMS_AB_MONITORING_MAIL_UPDATE_UNITS property is reserved for internal use.


PR_EMS_AB_MONITORING_NORMAL_POLL_INTERVAL

The PR_EMS_AB_MONITORING_NORMAL_POLL_INTERVAL property is reserved for internal use.


PR_EMS_AB_MONITORING_NORMAL_POLL_UNITS

The PR_EMS_AB_MONITORING_NORMAL_POLL_UNITS property is reserved for internal use.


PR_EMS_AB_MONITORING_RECIPIENTS

The PR_EMS_AB_MONITORING_RECIPIENTS property is reserved for internal use.


PR_EMS_AB_MONITORING_RECIPIENTS_NDR

The PR_EMS_AB_MONITORING_RECIPIENTS_NDR property is reserved for internal use.


PR_EMS_AB_MONITORING_RPC_UPDATE_INTERVAL

The PR_EMS_AB_MONITORING_RPC_UPDATE_INTERVAL property is reserved for internal use.


PR_EMS_AB_MONITORING_RPC_UPDATE_UNITS

The PR_EMS_AB_MONITORING_RPC_UPDATE_UNITS property is reserved for internal use.


PR_EMS_AB_MONITORING_WARNING_DELAY

The PR_EMS_AB_MONITORING_WARNING_DELAY property is reserved for internal use.


PR_EMS_AB_MONITORING_WARNING_UNITS

The PR_EMS_AB_MONITORING_WARNING_UNITS property is reserved for internal use.


PR_EMS_AB_MTA_LOCAL_CRED

The PR_EMS_AB_MTA_LOCAL_CRED property is reserved for internal use.


PR_EMS_AB_MTA_LOCAL_DESIG

The PR_EMS_AB_MTA_LOCAL_DESIG property is reserved for internal use.


PR_EMS_AB_N_ADDRESS

The PR_EMS_AB_N_ADDRESS property is reserved for internal use.


PR_EMS_AB_N_ADDRESS_TYPE

The PR_EMS_AB_N_ADDRESS_TYPE property is reserved for internal use.


PR_EMS_AB_NETWORK_ADDRESS

The PR_EMS_AB_NETWORK_ADDRESS property contains a list of the names by which a server is known to the various transports in use by the network.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Computer objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8170
Property type: | PR_EMS_AB_NETWORK_ADDRESS PT_MV_TSTRING PR_EMS_AB_NETWORK_ADDRESS_A PT_MV_STRING8 PR_EMS_AB_NETWORK_ADDRESS_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_NT_MACHINE_NAME

The PR_EMS_AB_NT_MACHINE_NAME property is reserved for internal use.


PR_EMS_AB_NT_SECURITY_DESCRIPTOR

The PR_EMS_AB_NT_SECURITY_DESCRIPTOR property contains the Windows NT access rights for this object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8013
Property type: | PT_BINARY
Access: | Read/write

Values

1
Minimum length
256
Maximum length

Remarks

The PR_EMS_AB_NT_SECURITY_DESCRIPTOR and PR_EMS_AB_ASSOC_NT_ACCOUNT properties are used by Administrator program components to associate between a mailbox and an Windows NT account. For example, if you have selected the option to delete Windows NT accounts when a mailbox is deleted, then this is the Windows NT account that will be deleted.

The PR_EMS_AB_NT_SECURITY_DESCRIPTOR property is in the form of Windows NT Security Descriptor.”

See Also

PR_EMS_AB_ASSOC_NT_ACCOUNT


PR_EMS_AB_NUM_OF_OPEN_RETRIES

The PR_EMS_AB_NUM_OF_OPEN_RETRIES property is reserved for internal use.


PR_EMS_AB_NUM_OF_TRANSFER_RETRIES

The PR_EMS_AB_NUM_OF_TRANSFER_RETRIES property is reserved for internal use.


PR_EMS_AB_OBJ_DIST_NAME

The PR_EMS_AB_OBJ_DIST_NAME property is reserved for internal use.


PR_EMS_AB_OBJECT_CLASS_CATEGORY

The PR_EMS_AB_OBJECT_CLASS_CATEGORY property is reserved for internal use.


PR_EMS_AB_OBJECT_VERSION

The PR_EMS_AB_OBJECT_VERSION property is reserved for internal use.


PR_EMS_AB_OFFLINE_AB_CONTAINERS

The PR_EMS_AB_OFF_LINE_AB_CONTAINERS property is reserved for internal use.


PR_EMS_AB_OFFLINE_AB_SCHEDULE

The PR_EMS_AB_OFF_LINE_AB_SCHEDULE property is reserved for internal use.


PR_EMS_AB_OFFLINE_AB_SERVER

The PR_EMS_AB_OFF_LINE_AB_SERVER property is reserved for internal use.


PR_EMS_AB_OFFLINE_AB_STYLE

The PR_EMS_AB_OFF_LINE_AB_STYLE property is reserved for internal use.


PR_EMS_AB_OID_TYPE

The PR_EMS_AB_OID_TYPE property is reserved for internal use.


PR_EMS_AB_OM_OBJECT_CLASS

The PR_EMS_AB_OM_OBJECT_CLASS property is reserved for internal use.


PR_EMS_AB_OM_SYNTAX

The PR_EMS_AB_OM_SYNTAX property is reserved for internal use.


PR_EMS_AB_OOF_REPLY_TO_ORIGINATOR

The PR_EMS_AB_OOF_REPLY_TO_ORIGINATOR property determines whether Out of Office replies will be sent to the user who sends mail to a distribution list.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Distribution-List objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x80ff
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Out of Office replies will not be sent.
1
TRUE = Out of Office replies will be sent.


PR_EMS_AB_OPEN_RETRY_INTERVAL

The PR_EMS_AB_OPEN_RETRY_INTERVAL property is reserved for internal use.


PR_EMS_AB_ORGANIZATION_NAME

The PR_EMS_AB_ORGANIZATION_NAME property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Application-Entity, Device, Group-Of-Names, and Organization objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8101
Property type: | PR_EMS_AB_ORGANIZATION_NAME PT_MV_TSTRING PR_EMS_AB_ORGANIZATION_NAME_A PT_MV_STRING8 PR_EMS_AB_ORGANIZATION_NAME_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
64
Maximum length


PR_EMS_AB_ORGANIZATIONAL_UNIT_NAME

The PR_EMS_AB_ORGANIZATIONAL_UNIT_NAME property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Application-Entity, Application-Process, Device, Group-Of-Names, Organizational-Person, Organizational-Role, Organizational-Unit, and Residential-Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8102
Property type: | PR_EMS_AB_ORGANIZATIONAL_UNIT_NAME PT_MV_TSTRING PR_EMS_AB_ORGANIZATIONAL_UNIT_NAME_A PT_MV_STRING8 PR_EMS_AB_ORGANIZATIONAL_UNIT_NAME_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
64
Maximum length


PR_EMS_AB_ORIGINAL_DISPLAY_TABLE

The PR_EMS_AB_ORIGINAL_DISPLAY_TABLE property is reserved for internal use.


PR_EMS_AB_ORIGINAL_DISPLAY_TABLE_MSDOS

The PR_EMS_AB_ORIGINAL_DISPLAY_TABLE_MSDOS property is reserved for internal use.


PR_EMS_AB_OUTBOUND_SITES

The PR_EMS_AB_OUTBOUND_SITES property is reserved for internal use.


PR_EMS_AB_OWNER

The PR_EMS_AB_OWNER property contains the distinguished name of the mailbox that owns the object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Group-Of-Names, Add-In, Distribution-List, Mailbox-Agent, and Device objects (directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x800c
Property type: | PR_EMS_AB_OWNER PT_TSTRING PR_EMS_AB_OWNER_A PT_STRING8 PR_EMS_AB_OWNER_O PT_OBJECT PR_EMS_AB_OWNER_T PT_TSTRING PR_EMS_AB_OWNER_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_OWNER_BL

The PR_EMS_AB_OWNER_BL property contains the backlink to the owner of a distribution list.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8024
Property type: | PR_EMS_AB_OWNER_BL PT_TSTRING PR_EMS_AB_OWNER_BL_A PT_STRING8 PR_EMS_AB_OWNER_BL_O PT_OBJECT PR_EMS_AB_OWNER_BL_T PT_TSTRING PR_EMS_AB_OWNER_BL_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_P_SELECTOR

The PR_EMS_AB_P_SELECTOR property is reserved for internal use.


PR_EMS_AB_P_SELECTOR_INBOUND

The PR_EMS_AB_P_SELECTOR_INBOUND property is reserved for internal use.


PR_EMS_AB_PER_MSG_DIALOG_DISPLAY_TABLE

The PR_EMS_AB_PER_MSG_DIALOG_DISPLAY_TABLE contains a MAPI display table object describing a per-message options dialog.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Address-Template objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8108
Property type: | PT_BINARY
Access: | Read/write


PR_EMS_AB_PER_RECIP_DIALOG_DISPLAY_TABLE

The PR_EMS_AB_PER_RECIP_DIALOG_DISPLAY_TABLE contains a MAPI display table object describing a per-recipients options dialog.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Address-Template objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8109
Property type: | PT_BINARY
Access: | Read/write


PR_EMS_AB_PERIOD_REP_SYNC_TIMES

The PR_EMS_AB_PERIOD_REP_SYNC_TIMES property is reserved for internal use.


PR_EMS_AB_PERIOD_REPL_STAGGER

The PR_EMS_AB_PERIOD_REPL_STAGGER property is reserved for internal use.


PR_EMS_AB_PF_CONTACTS

The PR_EMS_AB_PF_CONTACTS property contains the distinguished name of contact(s) of the folder.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Public-Folder objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8038
Property type: | PR_EMS_AB_PF_CONTACTS PT_MV_TSTRING PR_EMS_AB_PF_CONTACTS_A PT_MV_STRING8 PR_EMS_AB_PF_CONTACTS_O PT_OBJECT PR_EMS_AB_PF_CONTACTS_T PT_MV_TSTRING PR_EMS_AB_PF_CONTACTS_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_POSTAL_ADDRESS

The PR_EMS_AB_POSTAL_ADDRESS property contains the mailing address of an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Organizational-Unit, Organization, Organizational-Role, Residential-Person and Organizational-Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x810c
Property type: | PT_MV_BINARY
Access: | Read/write

Values

1 (2 hex digits)
Minimum length
4096 (8192 hex digits)
Maximum length


PR_EMS_AB_PREFERRED_DELIVERY_METHOD

The PR_EMS_AB_PREFERRED_DELIVERY_METHOD property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Organization, Organizational-Person, Oganizational-Role, Organizational-Unit, and Residential Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x810d
Property type: | PT_MV_LONG
Access: | Read/write


PR_EMS_AB_PRMD

The PR_EMS_AB_PRMD property refers to the X.400 administrative messaging domain (ADMD) associated with an object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x810e
Property type: | PR_EMS_AB_PRMD PT_TSTRING PR_EMS_AB_PRMD_A PT_STRING8 PR_EMS_AB_PRMD_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
16
Maximum length


PR_EMS_AB_PROXY_ADDRESSES

The PR_EMS_AB_PROXY_ADDRESSES property contains a list of foreign system addresses for this recipient.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Recipient objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x800f
Property type: | PR_EMS_AB_PROXY_ADDRESSES PT_MV_TSTRING PR_EMS_AB_PROXY_ADDRESSES_A PT_MV_STRING8 PR_EMS_AB_PROXY_ADDRESSES_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1123
Maximum length


PR_EMS_AB_PROXY_GENERATOR_DLL

The PR_EMS_AB_PROXY_GENERATOR_DLL property contains the name of a proxy generation DLL. Refer to the Gateway Programmer’s Reference for details.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Addr-Type objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x810f
Property type: | PR_EMS_AB_PROXY_GENERATOR_DLL PT_TSTRING PR_EMS_AB_PROXY_GENERATOR_DLL_A PT_STRING8 PR_EMS_AB_PROXY_GENERATOR_DLL_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
255
Maximum length

Remarks

The PR_EMS_AB_PROXY_GENERATOR_DLL property only contains the DLL file name of the proxy address, not the full path name. The DLL is found in the following path:

\\server\address\<address-type>\<computer>

where an example of <address-type> is SMTP and a <computer> is i386.


PR_EMS_AB_PUBLIC_DELEGATES

The PR_EMS_AB_PUBLIC_DELEGATES property contains a list of users allowed to send mail on behalf of the mailbox owner.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8015
Property type: | PR_EMS_AB_PUBLIC_DELEGATES PT_OBJECT PR_EMS_AB_PUBLIC_DELEGATES_A PT_MV_STRING8 PR_EMS_AB_PUBLIC_DELEGATES_O PT_OBJECT PR_EMS_AB_PUBLIC_DELEGATES_T PT_MV_TSTRING PR_EMS_AB_PUBLIC_DELEGATES_ PT_MV_UNICODE
Access: | Read-only
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_PUBLIC_DELEGATES_BL

The PR_EMS_AB_PUBLIC_DELEGATES_BL property contains a list of users on behalf of which the mailbox owner can send mail.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8110
Property type: | PR_EMS_AB_PUBLIC_DELEGATES_BL PT_MV_TSTRING PR_EMS_AB_PUBLIC_DELEGATES_BL_A PT_MV_STRING8 PR_EMS_AB_PUBLIC_DELEGATES_BL_O PT_OBJECT PR_EMS_AB_PUBLIC_DELEGATES_BL_T PT_MV_TSTRING PR_EMS_AB_PUBLIC_DELEGATES_BL_W PT_MV_UNICODE
Access: | Read-only
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_QUOTA_NOTIFICATION_SCHEDULE

The PR_EMS_AB_QUOTA_NOTIFICATION_SCHEDULE property is reserved for internal use.


PR_EMS_AB_QUOTA_NOTIFICATION_STYLE

The PR_EMS_AB_QUOTA_NOTIFICATION_STYLE property is reserved for internal use.


PR_EMS_AB_RANGE_LOWER

The PR_EMS_AB_RANGE_LOWER property is reserved for internal use.


PR_EMS_AB_RANGE_UPPER

The PR_EMS_AB_RANGE_UPPER property is reserved for internal use.


PR_EMS_AB_RAS_CALLBACK_NUMBER

The PR_EMS_AB_RAS_CALLBACK_NUMBER property is reserved for internal use.


PR_EMS_AB_RAS_PHONE_NUMBER

The PR_EMS_AB_RAS_PHONE_NUMBER property is reserved for internal use.


PR_EMS_AB_RAS_PHONEBOOK_ENTRY_NAME

The PR_EMS_AB_RAS_PHONEBOOK_ENTRY_NAME property is reserved for internal use.


PR_EMS_AB_RAS_REMOTE_SRVR_NAME

The PR_EMS_AB_RAS_REMOTE_SRVR_NAME property is reserved for internal use.


PR_EMS_AB_REGISTERED_ADDRESS

The PR_EMS_AB_REGISTERED_ADDRESS property is reserved for internal use.


PR_EMS_AB_REMOTE_BRIDGE_HEAD

The PR_EMS_AB_REMOTE_BRIDGE_HEAD property is reserved for internal use.


PR_EMS_AB_REMOTE_BRIDGE_HEAD_ADDRESS

The PR_EMS_AB_REMOTE_BRIDGE_HEAD_ADDRESS property is reserved for internal use.


PR_EMS_AB_REMOTE_OUT_BH_SERVER

The PR_EMS_AB_REMOTE_OUT_BH_SERVER property is reserved for internal use.


PR_EMS_AB_REMOTE_SITE

The PR_EMS_AB_REMOTE_SITE property is reserved for internal use.


PR_EMS_AB_REPLICATION_MAIL_MSG_SIZE

The PR_EMS_AB_REPLICATION_MAIL_MSG_SIZE property is reserved for internal use.


PR_EMS_AB_REPLICATION_SENSITIVITY

The PR_EMS_AB_REPLICATION_SENSITIVITY property is reserved for internal use.


PR_EMS_AB_REPLICATION_STAGGER

The PR_EMS_AB_REPLICATION_STAGGER property is reserved for internal use.


PR_EMS_AB_REPORT_TO_ORIGINATOR

The PR_EMS_AB_REPORT_TO_ORIGINATOR property specifies whether the originator of a message is informed that the message submitted to a distribution list is too big.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Distribution-List objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8120
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Do not receive reports.
1
TRUE = Receive reports.


PR_EMS_AB_REPORT_TO_OWNER

The PR_EMS_AB_REPORT_TO_OWNER property specifies whether the owner of a distribution list is informed that an oversized message has been submitted to the distribution list.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Distribution-List objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8121
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Do not receive reports.
1
TRUE = Receive reports.


PR_EMS_AB_REPORTS

The PR_EMS_AB_REPORTS property contains a list of direct reports.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x800e
Property type: | PR_EMS_AB_REPORTS PT_OBJECT PR_EMS_AB_REPORTS_A PT_MV_STRING8 PR_EMS_AB_REPORTS_O PT_OBJECT PR_EMS_AB_REPORTS_T PT_MV_TSTRING PR_EMS_AB_REPORTS_W PT_MV_UNICODE
Access: | Read-only
Unicode: | Yes

Values

1
Minimum length
256
Maximum length

Remarks

The PR_EMS_AB_REPORTS property is the backlink to Manager.


PR_EMS_AB_REQ_SEQ

The PR_EMS_AB_REQ_SEQ property is reserved for internal use.


PR_EMS_AB_RESPONSIBLE_LOCAL_DXA

The PR_EMS_AB_RESPONSIBLE_LOCAL_DXA property is reserved for internal use.


PR_EMS_AB_RID_SERVER

The PR_EMS_AB_RID_SERVER property is reserved for internal use.


PR_EMS_AB_ROLE_OCCUPANT

The PR_EMS_AB_ROLE_OCCUPANT property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Organizational-Role objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8125
Property type: | PR_EMS_AB_ROLE_OCCUPANT PT_MV_TSTRING PR_EMS_AB_ROLE_OCCUPANT_A PT_MV_STRING8 PR_EMS_AB_ROLE_OCCUPANT_W PT_MV_UNICODE PR_EMS_AB_ROLE_OCCUPANT_O PT_OBJECT PR_EMS_AB_ROLE_OCCUPANT_T PT_MV_TSTRING
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_ROUTING_LIST

The PR_EMS_AB_ROUTING_LIST property contains a list of entries describing the address types supported by a connector or gateway. The set of supported address types is called the connector's address space.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway, Site-Addressing, and Site-Connector objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8126
Property type: | PR_EMS_AB_ROUTING_LIST PT_MV_TSTRING PR_EMS_AB_ROUTING_LIST_A PT_MV_STRING8 PR_EMS_AB_ROUTING_LIST_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
2243
Maximum length


PR_EMS_AB_RTS_CHECKPOINT_SIZE

The PR_EMS_AB_RTS_CHECKPOINT_SIZE property is reserved for internal use.


PR_EMS_AB_RTS_RECOVERY_TIMEOUT

The PR_EMS_AB_RTS_RECOVERY_TIMEOUT property is reserved for internal use.


PR_EMS_AB_RTS_WINDOW_SIZE

The PR_EMS_AB_RTS_WINDOW_SIZE property is reserved for internal use.


PR_EMS_AB_RUNS_ON

The PR_EMS_AB_RUNS_ON property is reserved for internal use.


PR_EMS_AB_S_SELECTOR

The PR_EMS_AB_S_SELECTOR property is reserved for internal use.


PR_EMS_AB_S_SELECTOR_INBOUND

The PR_EMS_AB_S_SELECTOR_INBOUND property is reserved for internal use.


PR_EMS_AB_SEARCH_FLAGS

The PR_EMS_AB_SEARCH_FLAGS property is reserved for internal use.


PR_EMS_AB_SEARCH_GUIDE

The PR_EMS_AB_SEARCH_GUIDE property is reserved for internal use.


PR_EMS_AB_SECURITY_PROTOCOL

The PR_EMS_AB_SECURITY_PROTOCOL property is reserved for internal use.


PR_EMS_AB_SEE_ALSO

The PR_EMS_AB_SEE_ALSO property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Application-Entity, Application-Process, Device, Group-Of-Names, Locality, Organization, Organizational-Role, Organizational-Unit, and Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x812f
Property type: | PR_EMS_AB_SEE_ALSO PT_MV_TSTRING PR_EMS_AB_SEE_ALSO_A PT_MV_STRING8 PR_EMS_AB_SEE_ALSO_O PT_OBJECT PR_EMS_AB_SEE_ALSO_T PT_MV_TSTRING PR_EMS_AB_SEE_ALSO_W PT_MV_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_SERIAL_NUMBER

The PR_EMS_AB_SERIAL_NUMBER property is reserved for internal use.


PR_EMS_AB_SERVICE_ACTION_FIRST

The PR_EMS_AB_SERVICE_ACTION_FIRST property is reserved for internal use.


PR_EMS_AB_SERVICE_ACTION_OTHER

The PR_EMS_AB_SERVICE_ACTION_OTHER property is reserved for internal use.


PR_EMS_AB_SERVICE_ACTION_SECOND

The PR_EMS_AB_SERVICE_ACTION_SECOND property is reserved for internal use.


PR_EMS_AB_SERVICE_RESTART_DELAY

The PR_EMS_AB_SERVICE_RESTART_DELAY property is reserved for internal use.


PR_EMS_AB_SERVICE_RESTART_MESSAGE

The PR_EMS_AB_SERVICE_RESTART_MESSAGE property is reserved for internal use.


PR_EMS_AB_SESSION_DISCONNECT_TIMER

The PR_EMS_AB_SESSION_DISCONNECT_TIMER property is reserved for internal use.


PR_EMS_AB_SITE_AFFINITY

The PR_EMS_AB_SITE_AFFINITY property is reserved for internal use.


PR_EMS_AB_SITE_FOLDER_GUID

The PR_EMS_AB_SITE_FOLDER_GUID property is reserved for internal use only and should not be accessed or changed by other applications.


PR_EMS_AB_SITE_FOLDER_SERVER

The PR_EMS_AB_SITE_FOLDER_SERVER property is reserved for internal use only and should not be accessed or changed by other applications.


PR_EMS_AB_SITE_PROXY_SPACE

The PR_EMS_AB_SITE_PROXY_SPACE property is reserved for internal use.


PR_EMS_AB_SPACE_LAST_COMPUTED

The PR_EMS_AB_SPACE_LAST_COMPUTED property is reserved for internal use.


PR_EMS_AB_STREET_ADDRESS

The PR_EMS_AB_STREET_ADDRESS property contains the street address of the object.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Locality, Organization, Organizational-Person, Organizational-Role, Organizational-Unit, and Residential-Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x813a
Property type: | PR_EMS_AB_STREET_ADDRESS PT_TSTRING PR_EMS_AB_STREET_ADDRESS_A PT_STRING8 PR_EMS_AB_STREET_ADDRESS_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
128
Maximum length


PR_EMS_AB_SUB_REFS

The PR_EMS_AB_SUB_REFS property is reserved for internal use.


PR_EMS_AB_SUBMISSION_CONT_LENGTH

The PR_EMS_AB_SUBMISSION_CONT_LENGTH property is reserved for internal use.


PR_EMS_AB_SUPPORTED_APPLICATION_CONTEXT

The PR_EMS_AB_SUPPORTED_APPLICATION_CONTEXT property is reserved for internal use.


PR_EMS_AB_SUPPORTING_STACK

The PR_EMS_AB_SUPPORTING_STACK property is reserved for internal use.


PR_EMS_AB_SUPPORTING_STACK_BL

The PR_EMS_AB_SUPPORTING_STACK_BL property is reserved for internal use.


PR_EMS_AB_T_SELECTOR

The PR_EMS_AB_T_SELECTOR property is reserved for internal use.


PR_EMS_AB_T_SELECTOR_INBOUND

The PR_EMS_AB_T_SELECTOR_INBOUND property is reserved for internal use.


PR_EMS_AB_TARGET_ADDRESS

The PR_EMS_AB_TARGET_ADDRESS property contains the foreign system e-mail address of a custom recipient. For example, an Internet custom recipient's target address might be SMTP:PatParkes@trager.com.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Remote-Address objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8011
Property type: | PR_EMS_AB_TARGET_ADDRESS PT_TSTRING PR_EMS_AB_TARGET_ADDRESS_A PT_STRING8 PR_EMS_AB_TARGET_ADDRESS_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
1123
Maximum length

Remarks

For more information, see the Gateway Programmer’s Reference.


PR_EMS_AB_TARGET_MTAS

The PR_EMS_AB_TARGET_MTAS property is reserved for internal use.


PR_EMS_AB_TELEPHONE_NUMBER

The PR_EMS_AB_TELEPHONE_NUMBER property is reserved for internal use.


PR_EMS_AB_TELETEX_TERMINAL_IDENTIFIER

The PR_EMS_AB_TELETEX_TERMINAL_IDENTIFIER property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mailbox, Organization, Organizational-Person, Organizational-Role, Organizational-Unit, Remote-Address, Residential-Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8143
Property type: | PT_MV_BINARY
Access: | Read/write


PR_EMS_AB_TEMP_ASSOC_THRESHOLD

The PR_EMS_AB_TEMP_ASSOC_THRESHOLD property is reserved for internal use.


PR_EMS_AB_TOMBSTONE_LIFETIME

The PR_EMS_AB_TOMBSTONE_LIFETIME property contains the number of days that a tombstone will exist before expiring.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Directory-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8145
Property type: | PT_LONG
Access: | Read/write

Remarks

Tombstones are created whenever you delete an object from the directory. It is the tombstone that is replicated to other servers, effectively deleting the corresponding directory entry on the other server. The number that you enter here should be large enough to account for the time required to replicate the tombstone throughout the organization and the length of time required between server backups.

See Also

PR_EMS_AB_GARBAGE_COLL_PERIOD, PR_EMS_AB_IS_DELETED


PR_EMS_AB_TRACKING_LOG_PATH_NAME

The PR_EMS_AB_TRACKING_LOG_PATH_NAME property contains the path name to where the message tracking logs are kept.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Computer objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8146
Property type: | PR_EMS_AB_TRACKING_LOG_PATH_NAME PT_TSTRING PR_EMS_AB_TRACKING_LOG_PATH_NAME_A PT_STRING8 PR_EMS_AB_TRACKING_LOG_PATH_NAME_W PT_UNICODE
Access: | Read/write
Unicode: | Yes

Values

1
Minimum length
256
Maximum length


PR_EMS_AB_TRANS_RETRY_MINS

The PR_EMS_AB_TRANS_RETRY_MINS property is reserved for internal use.


PR_EMS_AB_TRANS_TIMEOUT_MINS

The PR_EMS_AB_TRANS_TIMEOUT_MINS property is reserved for internal use.


PR_EMS_AB_TRANSFER_RETRY_INTERVAL

The PR_EMS_AB_TRANSFER_RETRY_INTERVAL property contains the number of seconds the message transfer agent waits before resending a message.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway and MTA-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8149
Property type: | PT_LONG
Access: | Read/write


PR_EMS_AB_TRANSFER_TIMEOUT_NON_URGENT

The PR_EMS_AB_TRANSFER_TIMEOUT_NON_URGENT property contains the maximum transfer timeout (in minutes) to transfer a nonurgent message.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway and MTA-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x814a
Property type: | PT_LONG
Access: | Read/write


PR_EMS_AB_TRANSFER_TIMEOUT_NORMAL

The PR_EMS_AB_TRANSFER_TIMEOUT_NORMAL property contains the maximum time per kilobyte to transfer a normal message.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway and MTA-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x814b
Property type: | PT_LONG
Access: | Read/write


PR_EMS_AB_TRANSFER_TIMEOUT_URGENT

The PR_EMS_AB_TRANSFER_TIMEOUT_URGENT property contains the maximum time per kilobyte to transfer an urgent message.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Mail-Gateway and MTA-Cfg objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x814c
Property type: | PT_LONG
Access: | Read/write


PR_EMS_AB_TRANSLATION_TABLE_USED

The PR_EMS_AB_TRANSLATION_TABLE_USED property is reserved for internal use.


PR_EMS_AB_TRANSPORT_EXPEDITED_DATA

The PR_EMS_AB_TRANSPORT_EXPEDITED_DATA property is reserved for internal use.


PR_EMS_AB_TRUST_LEVEL

The PR_EMS_AB_TRUST_LEVEL property is reserved for internal use.


PR_EMS_AB_TURN_REQUEST_THRESHOLD

The PR_EMS_AB_TURN_REQUEST_THRESHOLD property is reserved for internal use.


PR_EMS_AB_TWO_WAY_ALTERNATE_FACILITY

The PR_EMS_AB_TWO_WAY_ALTERNATE_FACILITY property is reserved for internal use.


PR_EMS_AB_UNAUTH_ORIG_BL

The PR_EMS_AB_UNAUTH_ORIG_BL property is reserved for internal use.


PR_EMS_AB_USER_PASSWORD

The PR_EMS_AB_USER_PASSWORD property is for X.500 compatibility and is not used by Microsoft Exchange Server.

Quick Info

Header file: | EMSABTAG.H
Applies to: | Organization, Organizational-Unit, and Person objects (directory objects). These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8153
Property type: | PT_MV_BINARY
Access: | Read/write

Values

1 (2 hex digits)
Minimum length
128 (256 hex digits)
Maximum length


PR_EMS_AB_USN_CHANGED

The PR_EMS_AB_USN_CHANGED property contains the update sequence number (USN) for an object at the time it was changed.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8029
Property type: | PT_LONG
Access: | Read-only

Remarks

The PR_EMS_AB_USN_CHANGED property on an object is set to the next USN counter when the object is created or modified. This USN is server-specific, and servers are not updated to be alike, so the PR_EMS_AB_USN_CHANGED property for a certain directory object will usually be different on each server.

Each server has an internal USN counter that is incremented each time an object is created or modified in the directory. The updated USN counter is assigned to the PR_EMS_AB_USN_CHANGED property of the created or modified object when the directory needs to be replicated to another server. The highest USN that was sent to the other server on the previous replication is remembered—only USNs higher than that are sent. The result of this action is that only new information is sent to the other server.

This property can be used in a similar manner when writing directory synchronization programs.

See Also

PR_EMS_AB_USN_SOURCE


PR_EMS_AB_USN_CREATED

The PR_EMS_AB_USN_CREATED property contains the update sequence number (USN) for the object at the time it was created.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8154
Property type: | PT_LONG
Access: | Read-only

Remarks

The PR_EMS_AB_USN_CREATED property of an object is set to the next USN from the counter when the object is created. For a newly created object, the PR_EMS_AB_USN_CHANGED and PR_EMS_AB_USN_CREATED properties are equal.

See Also

PR_EMS_AB_USN_CHANGED


PR_EMS_AB_USN_DSA_LAST_OBJ_REMOVED

The PR_EMS_AB_USN_DSA_LAST_OBJ_REMOVED property is reserved for internal use.


PR_EMS_AB_USN_LAST_OBJ_REM

The PR_EMS_AB_USN_LAST_OBJ_REM property is reserved for internal use.


PR_EMS_AB_USN_SOURCE

The PR_EMS_AB_USN_SOURCE property contains the PR_EMS_AB_USN_CHANGED property that the object had on the server from which it was replicated.

Quick Info

Header file: | EMSABTAG.H
Applies to: | All directory objects. These objects appear to MAPI as messaging_user objects, which are accessible through the MAPI IMailUser interface.
Identifier: | 0x8157
Property type: | PT_LONG
Access: | Read-only

Remarks

When an object is replicated to a new server, the source object’s PR_EMS_AB_USN_CHANGED property is copied to the destination object’s PR_EMS_AB_USN_SOURCE property. The destination object’s PR_EMS_AB_USN_CREATED and PR_EMS_AB_USN_CHANGED properties are set using the destination server’s USN counter, as though the object had been created or modified on the destination server.

See Also

PR_EMS_AB_USN_CHANGED, PR_EMS_AB_USN_CREATED


PR_EMS_AB_X121_ADDRESS

The PR_EMS_AB_X121_ADDRESS property is reserved for internal use.


PR_EMS_AB_X25_CALL_USER_DATA_INCOMING

The PR_EMS_AB_X25_CALL_USER_DATA_INCOMING property is reserved for internal use.


PR_EMS_AB_X25_CALL_USER_DATA_OUTGOING

The PR_EMS_AB_X25_CALL_USER_DATA_OUTGOING property is reserved for internal use.


PR_EMS_AB_X25_FACILITIES_DATA_INCOMING

The PR_EMS_AB_X25_FACILITIES_DATA_INCOMING property is reserved for internal use.


PR_EMS_AB_X25_FACILITIES_DATA_OUTGOING

The PR_EMS_AB_X25_FACILITIES_DATA_OUTGOING property is reserved for internal use.


PR_EMS_AB_X25_LEASED_LINE_PORT

The PR_EMS_AB_X25_LEASED_LINE_PORT property is reserved for internal use.


PR_EMS_AB_X25_LEASED_OR_SWITCHED

The PR_EMS_AB_X25_LEASED_OR_SWITCHED property is reserved for internal use.


PR_EMS_AB_X25_REMOTE_MTA_PHONE

The PR_EMS_AB_X25_REMOTE_MTA_PHONE property is reserved for internal use.


PR_EMS_AB_X400_ATTACHMENT_TYPE

The PR_EMS_AB_X400_ATTACHMENT_TYPE property is reserved for internal use.


PR_EMS_AB_X400_SELECTOR_SYNTAX

The PR_EMS_AB_X400_SELECTOR_SYNTAX property is reserved for internal use.


PR_EMS_AB_X500_ACCESS_CONTROL_LIST

The PR_EMS_AB_X500_ACCESS_CONTROL_LIST property is reserved for internal use.


PR_EMS_AB_XMIT_TIMEOUT_NON_URGENT

The PR_EMS_AB_XMIT_TIMEOUT_NON_URGENT property is reserved for internal use.


PR_EMS_AB_XMIT_TIMEOUT_NORMAL

The PR_EMS_AB_XMIT_TIMEOUT_NORMAL property is reserved for internal use.


PR_EMS_AB_XMIT_TIMEOUT_URGENT

The PR_EMS_AB_XMIT_TIMEOUT_URGENT property is reserved for internal use.


PR_EXCESS_STORAGE_USED

The PR_EXCESS_STORAGE_USED property contains the amount of storage actually used by a user who has exceeded the storage quota.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3ff6
Property type: | PT_LONG
Access: | Read-only

See Also

PR_STORAGE_QUOTA_LIMIT, PR_SVR_GENERATING_QUOTA_MSG


PR_EXPIRY_NUMBER

The PR_EXPIRY_NUMBER property contains the number of time units that must pass before an unread message expires.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3fed
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_EXPIRY_NUMBER property is used for sending messages that expire if they are not read within a certain period. The unread messages no longer exist when the period has expired. If a message with this property is sent to a public folder, it expires immediately.

The information store uses the PR_EXPIRY_NUMBER and PR_EXPIRY_UNITS properties and the MAPI PR_CLIENT_SUBMIT_TIME property to calculate the value of the PR_EXPIRY_TIME property. PR_CLIENT_SUBMIT_TIME and PR_EXPIRY_TIME are standard MAPI properties.

For example:

PR_EXPIRY_TIME = PR_CLIENT_SUBMIT_TIME + (PR_EXPIRY_UNITS + PR_EXPIRY_NUMBER)

See Also

PR_EXPIRY_UNITS


PR_EXPIRY_UNITS

The PR_EXPIRY_UNITS property contains the time unit to be used in calculating the time for a message to expire.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3fee
Property type: | PT_LONG
Access: | Read/write

Values

0
Minutes
1
Hours
2
Days
3
Weeks

Remarks

The PR_EXPIRY_UNITS property is used by the information store to record Send Option dialog settings. The information in this and the MAPI PR_EXPIRY_TIME property is used by the information store to calculate when the message expires. These properties are only sent with messages that contain a deferred action.

The information store uses the PR_EXPIRY_NUMBER PR_EXPIRY_UNITS properties and the MAPI PR_CLIENT_SUBMIT_TIME property to calculate the value of the PR_EXPIRY_TIME property. PR_CLIENT_SUBMIT_TIME and PR_EXPIRY_TIME are standard MAPI properties.

For example:

PR_EXPIRY_TIME = PR_CLIENT_SUBMIT_TIME + (PR_EXPIRY_UNITS + PR_EXPIRY_NUMBER)

See Also

PR_EXPIRY_NUMBER


PR_FAST_TRANSFER

The PR_FAST_TRANSFER property is reserved for internal use.


PR_FOLDER_CHILD_COUNT

The PR_FOLDER_CHILD_COUNT property specifies the number of subfolders contained within a public folder object.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x6638
Property type: | PT_LONG
Access: | Read-only

Remarks

The PR_FOLDER_CHILD_COUNT property is always present even if there are no subfolders for the public folder object. For more information, see the PR_SUBFOLDERS property in the MAPI Programmer's Reference.


PR_FOLDER_DESIGN_FLAGS

The PR_FOLDER_DESIGN_FLAGS property contains a reason for the status of the folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3fe2
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_FOLDER_DESIGN_FLAGS property is only present when the PR_DESIGN_IN_PROGRESS optional property is present. No access to the folder is possible during this time.

See Also

PR_DESIGN_IN_PROGRESS


PR_FOLDER_FLAGS

The PR_FOLDER_FLAGS property contains the type of folder that was requested in a call to the IMAPIFolder::Create_Folder method.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66a8
Property type: | PT_LONG
Access: | Read/write

Values

1
MDB_FOLDER_IPM
2
MDB_FOLDER_SEARCH
4
MDB_FOLDER_NORMAL
8
MDB_FOLDER_RULES

Remarks

The PR_FOLDER_FLAGS property is returned by the IExchangeManageStore::GetPublicFolderTable method. This property is optional.

For information on the PR_FOLDER_TYPE property, see the MAPI Programmer's Reference.

See Also

IExchangeManageStore::GetPublicFolderTable


PR_FOLDER_PATHNAME

The PR_FOLDER_PATHNAME property contains the complete path name to the folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66b5
Property type: | PT_TSTRING
Access: | Read/write

Values

Multiple strings are separated by a backslash (\) except for the All Public Folders folder and the Favorites folder, which have no path. All paths begin with a backslash (\).

Remarks

The PR_FOLDER_PATHNAME property is returned by the IExchangeManageStore::GetPublicFolderTable method.

Folder paths are given in terms of All Public Folders as the root. For example, \Business is the subfolder directly under All Public Folders.

See Also

IExchangeManageStore::GetPublicFolderTable


PR_FOREIGN_ID

The PR_FOREIGN_ID property contains the foreign message identifier of a message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message transfer envelope objects (information store objects)
Identifier: | 0x6667
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_FOREIGN_ID property exists only on messages. On outgoing Microsoft Exchange Server messages, this property initially does not exist. It is added by a gateway after the message has been submitted to a foreign system.

SeeAlso

PR_FOREIGN_REPORT_ID


PR_FOREIGN_REPORT_ID

The PR_FOREIGN_REPORT_ID property contains an identifier from the foreign system that is assigned to a gateway report received from a foreign system.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x6668
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_FOREIGN_REPORT_ID property applies only to reports. The gateway assigns this property from a foreign report's report identifier.

See Also

PR_FOREIGN_ID


PR_FOREIGN_SUBJECT_ID

The PR_FOREIGN_SUBJECT_ID property contains a subject identifier assigned to a gateway report received from a foreign system.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x6669
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_FOREIGN_SUBJECT_ID is assigned by the gateway from the foreign report if the foreign report contains this field. Otherwise, the gateway assigns the property from identifiers in the original message.


PR_FREE_BUSY_FOR_LOCAL_SITE_ENTRYID

The PR_FREE_BUSY_FOR_LOCAL_SITE_ENTRYID property contains the entry identifier of a folder containing Schedule+ information giving free/busy information for users within a site. This information is represented by messages in a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message store objects (information store objects)
Identifier: | 0x6625
Property type: | PT_BINARY
Access: | Read-only

Remarks

This folder is a subfolder of the Schedule+ free/busy folder and contains messages indicating free/busy information for users at that site. This entry identifier can allow an application to write directly to the folder.


PR_GW_ADMIN_OPERATIONS

The PR_GW_ADMIN_OPERATIONS property is used to pass instructions between gateway administration tools and gateways.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message and public folder objects (information store objects)
Identifier: | 0x6658
Property type: | PT_LONG
Access: | Read/write

Values

The PR_GW_ADMIN_OPERATIONS property has the following Folder values when used on a folder:

Bit number | Mask name | Meaning
0 | ADMINOP_HIDDEN | 0 – Messages can be viewed. Default. 1 – Messages cannot be viewed.
1 | ADMINOP_DEFER | 0 – No deferred processing. Default. 1 – Deferred processing OK.
2 | ADMINOP_DELETE | 0 – Messages in this folder cannot be deleted. Default. 1 – Message delete OK.
3 | ADMINOP_NDR | 0 – Delivery of messages in this folder cannot be aborted. Default. 1 – Delivery can be aborted.
4 – 15 |  | Reserved. Must be 0.
16 – 31 |  | Available for use by gateway developers.

The PR_GW_ADMIN_OPERATIONS property has the following values when used on a message, representing deferred processing to be done by the gateway:

Bit Number | Mask Name | Meaning
0 | ADMINOP_HIDDEN | Ignored. Must be 0.
1 | ADMINOP_DEFER | Ignored. Must be 0.
2 | ADMINOP_DELETE | 0 – No action. Default. 1 – Delete message. Do not send NDR.
3 | ADMINOP_NDR | 0 – No action. Default. 1 – Delete message. Send NDR.
4 – 15 |  | Reserved. Must be 0.
16 – 31 |  | Available for use by gateway developers.

Remarks

The PR_GW_ADMIN_OPERATIONS property is used to pass instructions between gateway administration programs and gateways. The QUEVIEW sample application is an example of a gateway administration program. It allows administrators to view and manipulate the contents of gateway mailbox folders like MTS-IN and MTS-OUT.

For more information, see QUEVIEW: Listing Gateway Folders.

SeeAlso

PR_HAS_DAMS


PR_GW_MTSIN_ENTRYID

The PR_GW_MTSIN_ENTRYID property contains the entry identifier for a gateway's MTS-IN folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Gateway message store objects (information store objects)
Identifier: | 0x6628
Property type: | PT_BINARY
Access: | Read-only

Remarks

The MTS-IN folder is used to transfer messages from a gateway to the Microsoft Exchange Server information store.

See Also

PR_GW_ADMIN_OPERATIONS


PR_GW_MTSOUT_ENTRYID

The PR_GW_MTSOUT_ENTRYID property contains the entry identifier for a gateway's MTS-OUT folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Gateway message store objects (information store objects)
Identifier: | 0x6629
Property type: | PT_BINARY
Access: | Read-only

Remarks

The MTS-OUT folder is used to transfer messages from the Microsoft Exchange Server information store to a gateway.

See Also

PR_GW_ADMIN_OPERATIONS


PR_HAS_DAMS

The PR_HAS_DAMS property is reserved for internal use.


PR_HAS_NAMED_PROPERTIES

The PR_HAS_NAMED_PROPERTIES property determines whether a message has named properties on it.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x664a
Property type: | PT_BOOLEAN
Access: | Read-only

Values

0
FALSE = Message has no named properties on it.
1
TRUE = Message has named properties on it.


PR_HAS_RULES

The PR_HAS_RULES property determines whether there are rules set in the rule table on a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x663a
Property type: | PT_BOOLEAN
Access: | Read-only

Values

0
FALSE = There are no rules in the table
1
TRUE = There are rules in the table


PR_HIERARCHY_SERVER

The PR_HIERARCHY_SERVER property is reserved for internal use.


PR_HIERARCHY_SYNCHRONIZER

The PR_HIERARCHY_SYNCHRONIZER property is used with the MAPI OpenProperty function to retrieve the IExchangeExportChanges interface. This interface is for exporting only a folder's hierarchy changes, not its contents changes.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x662c
Property type: | PT_OBJECT
Access: | Read-only

Remarks

The PR_HIERARCHY_SYNCHRONIZER property is part of the incremental change synchronization (ICS) interface, which is not supported by all information stores.

For information on the OpenProperty function, see the MAPI Programmer's Reference.

See Also

IExchangeExportChanges


PR_IN_CONFLICT

The PR_IN_CONFLICT property indicates which embedded message attachments represent conflicting versions of a message in conflict.

Quick Info

Header file: | EDKMDB.H
Applies to: | Attachment objects (information store objects)
Identifier: | 0x666c
Property type: | PT_BOOLEAN
Access: | Read-only

Values

0
FALSE = Attachment is not a conflicting version.
1
TRUE = Attachment is a conflicting version.

Remarks

The PR_IN_CONFLICT property is TRUE for those embedded message attachments that are conflicting versions of the top-level message. It is used by any conflict resolution agent (or form). From this property, the agent can locate the conflicting versions of the message. Then the agent can choose the winning version using any criteria or merge the conflicting versions. For more information, see Handling Message Conflicts.


PR_IN_TRANSIT

The PR_IN_TRANSIT property is reserved for internal use.


PR_INTERNAL_TRACE_INFO

The PR_INTERNAL_TRACE_INFO property is reserved for internal use.


PR_IPM_DAF_ENTRYID

The PR_IPM_DAF_ENTRYID property contains the message store object entry identifier of a deferred action folder (DAF).

Quick Info

Header file: | EDKMDB.H
Applies to: | Mailbox objects (information store objects)
Identifier: | 0x661f
Property type: | PT_BINARY
Access: | Read-only

Remarks

The DAF is a folder that branches from the root folder of a mailbox and stores information about deferred actions. This property gives its entry identifier. The DAF is not seen by users and is not replicated. For more information, see How Rules Interact with the Microsoft Exchange Client.


PR_IPM_FAVORITES_ENTRYID

The PR_IPM_FAVORITES_ENTRYID property contains the entry identifier for the Favorites folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mailbox objects (information store objects)
Identifier: | 0x6630
Property type: | PT_BINARY
Access: | Read-only

Remarks

The Favorites folder is implemented as a nonstandard folder inside a user's mailbox. It contains pointers to folders in the public information store, but appears to client applications as a subfolder of the public information store. The Favorites folder is opened by passing the entry identifier contained in the PR_IPM_FAVORITES_ENTRYID property to the MAPI OpenEntry method.

For information on the OpenEntry method, see the MAPI Programmer's Reference.


PR_IPM_PUBLIC_FOLDERS_ENTRYID

The PR_IPM_PUBLIC_FOLDERS_ENTRYID property contains the entry identifier of the top-level folder for the IPM subtree.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public information store objects (information store objects)
Identifier: | 0x6631
Property type: | PT_BINARY
Access: | Read-only

Remarks

The public information store is divided into the IPM subtree and the non-IPM subtree. The IPM subtree consists of a set of public folders that is replicated and seen by a user.

For more information, see Opening the Favorites Folder and Entry Identifiers of Special Folders.


PR_LAST_ACCESS_TIME

The PR_LAST_ACCESS_TIME property contains the date that the replica of a public folder was accessed.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66a9
Property type: | PT_SYSTIME
Access: | Read/write


PR_LAST_LOGOFF_TIME

The PR_LAST_LOGOFF_TIME property contains the date and time that a mail user last logged off.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mail recipient objects (information store objects)
Identifier: | 0x66a3
Property type: | PT_SYSTIME
Access: | Read/write


PR_LAST_LOGON_TIME

The PR_LAST_LOGON_TIME property contains the date and time that the mail user last logged on.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mail recipient objects (information store objects)
Identifier: | 0x66a2
Property type: | PT_SYSTIME
Access: | Read/write


PR_LAST_MODIFIER_ENTRYID

The PR_LAST_MODIFIER_ENTRYID property contains the entry identifier of the last person to modify a message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x6643
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_IPM_FAVORITES_ENTRYID property is set by the information store every time changes are saved. It can be used by an application to display the address book entry identifier of the last user to modify a message.


PR_LAST_MODIFIER_NAME

The PR_LAST_MODIFIER_NAME property contains the display name of the last person to modify a message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x6642
Property type: | PT_TSTRING
Access: | Read-only

Remarks

The PR_LAST_MODIFIER_NAME property applies to messages. It is set by the information store every time changes are saved. It can be used by an application to display the name of the last user to modify a message.


PR_LOCALE_ID

The PR_LOCALE_ID property contains the locale identifier of a logged-on mailbox user.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mail recipient and mailbox objects (information store objects)
Identifier: | 0x66a1
Property type: | PT_LONG
Access: | Read/write


PR_LONGTERM_ENTRYID_FROM_TABLE

The PR_LONGTERM_ENTRYID_FROM_TABLE property is used by the information store to return long-term MAPI entry identifiers within contents tables.

Quick Info

Header file: | EDKMDB.H
Applies to: | Information store objects
Identifier: | 0x6670
Property type: | PT_BINARY
Access: | Read-only

Remarks

When the MAPI PR_ENTRYID property is requested on a contents table, a short-term MAPI entry identifier is returned. The usual way to recover the long-term entry identifier for an object such as a message is to use the MAPI OpenEntry function to open the object and the IMAPIProp::GetProps method to read the PR_ENTRYID property from the object itself. However, the Microsoft Exchange Server information store allows users to obtain long-term entry identifiers directly from contents tables through the PR_LONGTERM_ENTRYID_FROM_TABLE property.

For more information on the PR_ENTRYID property and the OpenEntry function, see the MAPI Programmer's Reference.


PR_MAILBOX_OWNER_ENTRYID

The PR_MAILBOX_OWNER_ENTRYID property contains the address book entry identifier for the owner of a mailbox.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mailbox objects (information store objects)
Identifier: | 0x661b
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_MAILBOX_OWNER_ENTRYID property is not defined for gateway mailboxes.

See Also

PR_USER_ENTRYID


PR_MAILBOX_OWNER_NAME

The PR_MAILBOX_OWNER_NAME property contains the name of the owner of a mailbox.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mailbox objects (information store objects)
Identifier: | 0x661c
Property type: | PT_TSTRING
Access: | Read-only

Remarks

The PR_MAILBOX_OWNER_NAME property is not defined for gateway mailboxes.


PR_MEMBER_ENTRYID

The PR_MEMBER_ENTRYID property contains the directory object entry identifier of a member of the ACL table.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder and mailbox objects (information store objects)
Identifier: | 0x0fff
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_MEMBER_ENTRYID property is used by the IExchangeModifyTable interface to uniquely identify a person or role to whom the ACL applies.

After a member is created in the ACL table, ENTRYID cannot be changed. To change it, you must delete the table member and recreate it with a different ENTRYID.

See Also

IExchangeModifyTable, PR_ACL_TABLE


PR_MEMBER_ID

The PR_MEMBER_ID property contains the identifier of a table member that has the described rights on a Microsoft Exchange Server folder or mailbox.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder and mailbox objects (information store objects)
Identifier: | 0x6671
Property type: | PT_I8
Access: | Read-only

Remarks

The PR_MEMBER_ID property returns an identifier unique to the table. A directory user identifier is associated with each member identifier and is given by the PR_MEMBER_ENTRYID property. This property is used by the IExchangeModifyTable interface to retrieve the directory entry identifier of a member with explicit rights on a folder.

See Also

IExchangeModifyTable, PR_ACL_DATA, PR_ACL_TABLE, PR_MEMBER_NAME


PR_MEMBER_NAME

The PR_MEMBER_NAME property contains the display name of a member of the ACL table.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x6672
Property type: | PT_TSTRING
Access: | Read-only

Remarks

The PR_MEMBER_NAME property is used by IExchangeModifyTable 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.

See Also

IExchangeModifyTable


PR_MEMBER_RIGHTS

The PR_MEMBER_RIGHTS property contains a set of bits indicating the rights of this member on a folder or mailbox.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x6673
Property type: | PT_LONG
Access: | Read-only

Values

ReadAny
Member can read any messages.
Create
Member can create messages.
EditOwned
Member can edit any messages owned by the user.
DeleteOwned
Member can delete any messages owned by the user.
EditAny
Member can edit any message.
DeleteAny
Member can delete any message.
CreateSubfolder
Member can create subfolders for the folder.
Owner
Member has all the above rights on the folder.
Contact
Member can have your name appear as the contact on the folder.
None
Member has no rights on the folder.
ReadOnly
Member can read any message in the folder.
ReadWrite
Member can read from and write to any message in the folder.
All
Member has all the above rights on the folder.

Remarks

The PR_MEMBER_RIGHTS property is used by the IExchangeModifyTable interface to define rights of a member on a folder. These rights can be displayed and modified.

See Also

IExchangeModifyTable


PR_MESSAGE_LOCALE_ID

The PR_MESSAGE_LOCALE_ID property on a message contains the language client used to create the message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3ff1
Property type: | PT_LONG
Access: | Read/write


PR_MESSAGE_SIZE_EXTENDED

The PR_MESSAGE_SIZE_EXTENDED property contains the sum (in bytes) of the sizes of all properties on a message object.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder and mailbox objects (information store objects)
Identifier: | 0x0e08
Property type: | PT_I8
Access: | N/A

Remarks

The PR_MESSAGE_SIZE_EXTENDED property is an 8-byte version of the MAPI PR_MESSAGE_SIZE property. The message size indicates the approximate number of bytes transferred when the message is moved from one information store to another. Being the sum of the sizes of all the properties on the message object, it is usually considerably greater than the message text alone.

Most information store providers compute the PR_MESSAGE_SIZE_EXTENDED property for messages that they handle. However, some information store providers do not supply this property.

You can use the IMAPIProp::GetProps method to return this value for a folder or mailbox object. You can also ask for this column in the table returned by the IExchangeManageStore::GetPublicFolderTable method.

For information on the PR_MESSAGE_SIZE property and the IMAPIProps::GetProps method, see the MAPI Programmer's Reference.


PR_MOVE_TO_FOLDER_ENTRYID

The PR_MOVE_TO_FOLDER_ENTRYID property contains the entry identifier of the folder for the deferred action.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3ff4
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_MOVE_TO_FOLDER_ENTRYID property applies to deferred action folders (DAFs) only.


PR_MOVE_TO_STORE_ENTRYID

The PR_MOVE_TO_STORE_ENTRYID property contains the entry identifier of the information store for the deferred action.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3ff3
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_MOVE_TO_STORE_ENTRYID property applies to deferred action folders only.


PR_MTS_ID

The PR_MTS_ID property is the message transfer envelope identifier.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message transfer envelope objects (information store objects)
Identifier: | 0x0047
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_MTS_ID property can be used by gateway developers to correlate messages with reports or to follow threads. This property is generated by the transport (such as the gateway) rather than by a client. If not supplied explicitly by a gateway, Microsoft Exchange Server generates a value for PR_MTS_ID automatically.

The PR_MTS_ID property has the same values and is synonymous with the MAPI PR_MESSAGE_SUBMISSION_ID property.

For more information on PR_MESSAGE_SUBMISSION_ID, see the MAPI Programmer's Reference.


PR_MTS_REPORT_ID

The PR_MTS_REPORT_ID property contains the MTS identifier of a report.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x0047
Property type: | PT_BINARY
Access: | Read/write

Remarks

On submitted reports, the PR_MTS_REPORT_ID property is set after report submission by Microsoft Exchange Server .

The PR_MTS_REPORT_ID property has the same values and is synonymous with the MAPI PR_MESSAGE_SUBMISSION_ID property.

For information on the PR_MESSAGE_SUBMISSION_ID property, see the MAPI Programmer's Reference.


PR_MTS_SUBJECT_ID

The PR_MTS_SUBJECT_ID property appears on delivery and nondelivery reports generated by gateways. It contains the X.400 message identifier of the original message to which the report refers.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x6663
Property type: | PT_BINARY
Access: | Read/write

Remarks

If the original message is still available, the value for PR_MTS_SUBJECT_ID should be copied from the original message's PR_MTS_ID property. If the original message is not available, a dummy value can be used for PR_MTS_SUBJECT_ID as long as it is a null-terminated string with the following format:

c=[Country Code];a=[ADMD Name];p=[PRMD ID];l=[Local ID]

where [Country Code], [ADMD Name], [PRMD ID] and [Local ID] can be anything satisfying the syntax requirements for X.400 MTS IDs.

Note that X.400 country codes are either 2 or 3 characters long. This requirement is enforced by the information store.

Note also that the contents of PR_MTS_SUBJECT_ID must be a null-terminated string, even though the property syntax is PT_BINARY. The property length must include the null-terminator.

The following is an example of a valid PR_MTS_SUBJECT_ID string:

c=US;a= ;p=Microsoft;l=Anything


PR_NON_IPM_SUBTREE_ENTRYID

The PR_NON_IPM_SUBTREE_ENTRYID property contains the entry identifier of a top-level folder for the non-IPM subtree.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder store objects (information store objects)
Identifier: | 0x6620
Property type: | PT_BINARY
Access: | Read-only

Remarks

The non-IPM subtree is the area of the public store that is not seen by users. It always contains a standard set of folders and can also contain folders created by applications. Subfolders of the non-IPM subtree include a Schedule+ information folder that contains a subfolder for each site, an offline address book folder containing subfolders for each site, and a forms library folder containing forms in various languages. Some folders on the non-IPM subtree are replicated and others are not.

See Also

About Public Folders


PR_NORMAL_MESSAGE_SIZE

The PR_NORMAL_MESSAGE_SIZE property contains the total size of nonassociated messages in a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | N/A
Identifier: | 0x66b3
Property type: | PT_LONG
Access: | N/A

Remarks

The PR_NORMAL_MESSAGE_SIZE property can be set as a column in the table returned by the IExchangeManageStore::GetPublicFolderTable method. This table contains a row for each public folder replicated to the server. The columns of the rows give information, such as the display name of the folder, pathname, and the last access time. To view the table format, see the Public Folder Resources tab of the Public Information Store property sheet in the Microsoft Exchange Server Administrator program.

This property provides additional information about the public folder, such as the number of bytes of storage used by the nonassociated messages in the folder.

Note The PR_NORMAL_MESSAGE_SIZE_EXTENDED property provides an 8-byte version of this same property.

See Also

PR_NORMAL_MESSAGE_SIZE_EXTENDED, Using the IExchangeManageStore Interface


PR_NORMAL_MESSAGE_SIZE_EXTENDED

The PR_NORMAL_MESSAGE_SIZE_EXTENDED property contains the total size of nonassociated messages in a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | N/A
Identifier: | 0x66b3
Property type: | PT_I8
Access: | N/A

Remarks

The PR_NORMAL_MESSAGE_SIZE_EXTENDED property is an 8-byte version of the PR_NORMAL_MESSAGE_SIZE property.

You can use the IMAPIProp::GetProps method to return this value for a folder object. You can also ask for this column in the table returned by the IExchangeManageStore::GetPublicFolderTable method.

For more information, see Using the IExchangeManageStore Interface.

For information on the IMAPIProp::GetProps method, see the MAPI Programmer's Reference.

See Also

PR_NORMAL_MESSAGE_SIZE,


PR_NORMAL_MSG_W_ATTACH_COUNT

The PR_NORMAL_MSG_W_ATTACH_COUNT property contains the total count of attachments in the folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder object (information store objects)
Identifier: | 0x66ad
Property type: | PT_LONG
Access: | Read/write


PR_NT_USER_NAME

The PR_NT_USER_NAME property contains the Windows NT user account name of the last user to log on to the information store.

Quick Info

Header file: | EDKMDB.H
Applies to: |
Identifier: | 0x66a0
Property type: | PT_TSTRING
Access: | Read/write

See Also

IExchangeManageStore::GetMailboxTable


PR_OFFLINE_ADDRBOOK_ENTRYID

The PR_OFFLINE_ADDRBOOK_ENTRYID property contains the entry identifier of an offline address book.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder store objects (information store objects)
Identifier: | 0x6623
Property type: | PT_BINARY
Access: | Read-only

Remarks

The offline address book contains a subfolder for each site. The folders contain a message with all the offline address book files in a compressed format.


PR_OFFLINE_MESSAGE_ENTRYID

The PR_OFFLINE_MESSAGE_ENTRYID property contains the entry identifier of an offline message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder store objects (information store objects)
Identifier: | 0x6627
Property type: | PT_BINARY
Access: | Read-only


PR_OOF_STATE

The PR_OOF_STATE property contains whether the Out of Office Assistant is enabled.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message store objects (information store objects)
Identifier: | 0x661d
Property type: | PT_BOOLEAN
Access: | Read-only

Values

0
FALSE = Out of Office Assistant is disabled.
1
TRUE = Out of Office Assistant is enabled.


PR_ORIGINATOR_ADDR

The PR_ORIGINATOR_ADDR property contains the address of a message originator.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x665c
Property type: | PT_TSTRING
Access: | Read/write

Remarks

The PR_ORIGINATOR_ADDR property is used on the message transfer envelope of gateway messages.


PR_ORIGINATOR_ADDRTYPE

The PR_ORIGINATOR_ADDRTYPE property contains the address type of a message originator.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x665d
Property type: | PT_TSTRING
Access: | Read/write

Remarks

The PR_ORIGINATOR_ADDRTYPE property is used on the message transfer envelope.


PR_ORIGINATOR_ENTRYID

The PR_ORIGINATOR_ENTRYID property contains the entry identifier of a message source.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x665e
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_ORIGINATOR_ENTRYID property may contain other information about the originator, such as the originator's address, address type, or display name. It is a property on the message transfer envelope.


PR_ORIGINATOR_NAME

The PR_ORIGINATOR_NAME property contains the display name of a message source.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message transfer envelope objects (information store objects)
Identifier: | 0x665b
Property type: | PT_TSTRING
Access: | Read/write

Remarks

The PR_ORIGINATOR_NAME property is used on the message transfer envelope.


PR_OST_ENCRYPTION

The PR_OST_ENCRYPTION property is reserved for internal use.


PR_OVERALL_AGE_LIMIT

The PR_OVERALL_AGE_LIMIT property is reserved for internal use.


PR_OVERALL_MSG_AGE_LIMIT

The PR_OVERALL_MSG_AGE_LIMIT property is reserved for internal use.


PR_OWNER_COUNT

The PR_OWNER_COUNT property contains the number of owners of a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66b6
Property type: | PT_LONG
Access: | Read/write


PR_P1_CONTENT

The PR_P1_CONTENT property is reserved for internal use.


PR_P1_CONTENT_TYPE

The PR_P1_CONTENT_TYPE property is reserved for internal use.


PR_PARENT_SOURCE_KEY

The PR_PARENT_SOURCE_KEY property contains the PR_SOURCE_KEY property of the parent folder of a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | All folder objects (information store objects)
Identifier: | 0x65e1
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_PARENT_SOURCE_KEY property is used primarily by the incremental change synchronization (ICS) interface and contains the PR_SOURCE_KEY that uniquely identifies the parent folder of a folder.

For more information, see About Incremental Change Synchronization.

See Also

IExchangeExportChanges, IExchangeImportContentsChanges, IExchangeImportHierarchyChanges, IExchangeManageStore, PR_CHANGE_KEY, PR_PREDECESSOR_CHANGE_LIST, PR_SOURCE_KEY


PR_PREDECESSOR_CHANGE_LIST

The PR_PREDECESSOR_CHANGE_LIST property contains a list of change keys, including the current PR_CHANGE_KEY.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder and message objects (information store objects)
Identifier: | 0x65e3
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_PREDECESSOR_CHANGE_LIST property is primarily used by the incremental change synchronization (ICS) interface and contains a list of PR_CHANGE_KEY properties. A change in a store will supersede any previous change in the same store, so only one change key per store is maintained. he PR_PREDECESSOR_CHANGE_LIST will contain a list of changes equal to the number of different stores in which the object has changed.

Because PR_CHANGE_KEY properties can be of arbitrary length, each PR_CHANGE_KEY in the list is preceded by a byte that contains the number of bytes for the immediately following PR_CHANGE_KEY.

For more information, see About Incremental Change Synchronization.

See Also

IExchangeExportChanges, IExchangeImportHierarchyChanges, IExchangeImportContentsChanges, PR_SOURCE_KEY, PR_PARENT_SOURCE_KEY, PR_CHANGE_KEY


PR_PROFILE_AB_FILES_PATH

The PR_PROFILE_AB_FILES_PATH property contains contains the offline address book path.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x660e
Property type: | PT_STRING8
Access: | Read/write


PR_PROFILE_ADDR_INFO

The PR_PROFILE_ADDR_INFO property is reserved for internal use.


PR_PROFILE_ALLPUB_COMMENT

The PR_PROFILE_ALLPUB_COMMENT property is reserved for internal use.


PR_PROFILE_ALLPUB_DISPLAY_NAME

The PR_PROFILE_ALLPUB_DISPLAY_NAME property is reserved for internal use.


PR_PROFILE_CONFIG_FLAGS

The PR_PROFILE_CONFIG_FLAGS property is used by the client user interface to configure a service of Microsoft Exchange Server.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6601
Property type: | PT_LONG
Access: | Read/write

Values

1
CONFIG_SERVICE
2
CONFIG_SHOW_STARTUP_UI
4
CONFIG_SHOW_CONNECT_UI
8
CONFIG_PROMPT_FOR_CREDENTIALS


PR_PROFILE_CONNECT_FLAGS

The PR_PROFILE_CONNECT_FLAGS property specifies how to connect to a server.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6604
Property type: | PT_LONG
Access: | Read/write

Values

1
CONNECT_USE_ADMIN_PRIVILEGE
2
CONNECT_NO_RPC_ENCRYPTION


PR_PROFILE_FAVFLD_COMMENT

The PR_PROFILE_FAVFLD_COMMENT property is reserved for internal use.


PR_PROFILE_FAVFLD_DISPLAY_NAME

The PR_PROFILE_FAVFLD_DISPLAY_NAME property is reserved for internal use.


PR_PROFILE_HOME_SERVER

The PR_PROFILE_HOME_SERVER property contains the name of a home server.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6602
Property type: | PT_STRING8
Access: | Read/write

Remarks

No backslash (\) characters are used in the values for this property.

The PR_PROFILE_HOME_SERVER property can be edited in the Edit Profile option of the Messaging Profiles dialog box, within which PR_PROFILE_DOWNLOAD is represented by the Server Name field on the General page of the Microsoft Exchange Server Information Service dialog box.

The PR_PROFILE_HOME_SERVER property is used in the global sections of Microsoft Exchange Server profiles.


PR_PROFILE_HOME_SERVER_ADDRS

The PR_PROFILE_HOME_SERVER_ADDRS property is reserved for internal use.


PR_PROFILE_HOME_SERVER_DN

The PR_PROFILE_HOME_SERVER_DN property is reserved for internal use.


PR_PROFILE_MAILBOX

The PR_PROFILE_MAILBOX property contains the e-mail address for a provider (transport or store).

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x660b
Property type: | PT_ STRING
Access: | Read/write

Remarks

The PR_PROFILE_MAILBOX property is used in private store rows of Microsoft Exchange Server profiles.


PR_PROFILE_MAX_RESTRICT

The PR_PROFILE_MAX_RESTRICT property restricts the maximum number of names the address book will return.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x660d
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_PROFILE_MAX_RESTRICT property is used in the global sections of Microsoft Exchange Server profiles.


PR_PROFILE_OFFLINE_INFO

The PR_PROFILE_OFFLINE_INFO property contains the path to a offline store.


PR_PROFILE_OFFLINE_STORE_PATH

The PR_PROFILE_OFFLINE_STORE_PATH property contains the path to an offline store.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6610
Property type: | PT_LONG
Access: | Read/write


PR_PROFILE_OPEN_FLAGS

The PR_PROFILE_OPEN_FLAGS property determines the flags used for a specific information store.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6609
Property type: | PT_LONG
Access: | Read/write

Values

OPENSTORE_USE_ADMIN_PRIVILEGE
Used with the IExchangeManageStore interface for privileged access to any message store. See IExchangeManageStore::CreateStoreEntryID.
OPENSTORE_PUBLIC
Indicates that the store is the public store in MAPISVC.INF and CreateStoreEntryID.
OPENSTORE_HOME_LOGON
Indicates the home information store in MAPISVC.INF.
OPENSTORE_TAKE_OWNERSHIP
Used with the IExchangeManageStore interface for privileged access to any message store. See IExchangeManageStore::CreateStoreEntryID. Gives the user the same rights as the owner of the store.
OPENSTORE_OVERRIDE_HOME_MDB
Used with the IExchangeManageStore interface for privileged access to any message store, and allows a user to log onto a store other than the user's home information store.
OPENSTORE_TRANSPORT
Indicates the transport.
OPENSTORE_REMOTE_TRANSPORT
Indicates the remote transport.

Remarks

The PR_PROFILE_OPEN_FLAGS property is used by a profile configuration tool.

See Also

IExchangeManageStore::CreateStoreEntryID, IExchangeManageStore


PR_PROFILE_SECURE_MAILBOX

The PR_PROFILE_SECURE_MAILBOX property is reserved for internal use.


PR_PROFILE_SERVER

The PR_PROFILE_SERVER property contains the name of the server where an information store is located.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6614
Property type: | PT_STRING
Access: | Read/write

Remarks

The PR_PROFILE_SERVER property is used in information store rows of Microsoft Exchange Server profiles.


PR_PROFILE_SERVER_DN

The PR_PROFILE_SERVER_DN property is reserved for internal use.


PR_PROFILE_TRANSPORT_FLAGS

The PR_PROFILE_TRANSPORT_FLAGS property determines whether the Microsoft Exchange Server transport provider uploads or downloads messages.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6605
Property type: | PT_LONG
Access: | Read/write

Values

1
TRANSPORT_DOWNLOAD
2
TRANSPORT_UPLOAD

Remarks

The PR_PROFILE_TRANSPORT_FLAGS property is used to create a MAPI profile.


PR_PROFILE_TYPE

The PR_PROFILE_TYPE property describes the type of information store.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x660a
Property type: | PT_LONG
Access: | Read/write

Values

1
PROFILE_PRIMARY_USER
2
PROFILE_DELEGATE
3
PROFILE_PUBLIC_STORE
4
PROFILE_SUBSCRIPTION


PR_PROFILE_UI_STATE

The PR_PROFILE_UI_STATE property is used to remember the last state of the user interface.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6606
Property type: | PT_LONG
Access: | Read/write


PR_PROFILE_UNRESOLVED_NAME

The PR_PROFILE_UNRESOLVED_NAME property contains the unresolved name of a user

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6607
Property type: | PT_STRING8
Access: | Read/write

Remarks

When the profile is actually built, this information is translated into an unambiguous, store-specific reference.


PR_PROFILE_UNRESOLVED_SERVER

The PR_PROFILE_UNRESOLVED_SERVER property contains the unresolved name of a server.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6608
Property type: | PT_STRING8
Access: | Read/write

Remarks

When the profile is actually built, this information is translated into an unambiguous, server-specific reference.


PR_PROFILE_USER

The PR_PROFILE_USER property contains the mailbox of a logged-on user.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6603
Property type: | PT_STRING8
Access: | Read/write

Remarks

The PR_PROFILE_USER property is used in the global sections of Microsoft Exchange Server profiles.


PR_PROFILE_VERSION

The PR_PROFILE_VERSION property contains the current version of a MAPI profile that contains the service of Microsoft Exchange Server.

Quick Info

Header file: | EDKMDB.H
Applies to: | Profile objects
Identifier: | 0x6600
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_PROFILE_VERSION property is used in the global sections of Microsoft Exchange Server profiles.


PR_PST_ENCRYPTION

The PR_PST_ENCRYPTION property contains the encryption level at which to create a file in the personal folder store.

Quick Info

Header file: | MSPST.H
Applies to: | Personal folder store objects
Identifier: | 0x6702
Property type: | PT_LONG
Access: | Read/write

Values

PSTF_NO_ENCRYPTION
Do not encrypt.
PSTF_COMPRESSABLE_ENCRYPTION
Encrypt for potential compression.
PSTF_BEST_ENCRYPTION
Perform the most-rigorous encryption.

See Also

HrCreatePersonalStore


PR_PST_PATH

The PR_PST_PATH property contains the location of the object in the personal folder store to create or configure.

Quick Info

Header file: | MSPST.H
Applies to: | Personal folder store objects
Identifier: | 0x6700
Property type: | PT_STRING8
Access: | Read/write

See Also

HrCreatePersonalStore


PR_PST_PW_SZ_NEW

The PR_PST_PW_SZ_NEW property contains the new password to use for future access to the personal folder store.

Quick Info

Header file: | MSPST.H
Applies to: | Personal folder store objects
Identifier: | 0x6704
Property type: | PT_STRING8
Access: | Read/write

See Also

HrCreatePersonalStore


PR_PUBLIC_FOLDER_ENTRYID

The PR_PUBLIC_FOLDER_ENTRYID property is reserved for internal use.


PR_PUBLISH_IN_ADDRESS_BOOK

The PR_PUBLISH_IN_ADDRESS_BOOK property determines whether a folder's display name appears in the address book.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3fe6
Property type: | PT_BOOLEAN
Access: | Read/write (writeable only by the folder owner)

Values

0
FALSE = Folder display name does not appear in the address book (default).
1
TRUE = Folder display name appears in the address book.

Remarks

The PR_PUBLISH_IN_ADDRESS_BOOK property can be read with the IMAPIProp::GetProps method and set with the IMAPIProp::SetProps method.


PR_RECIPIENT_NUMBER

The PR_RECIPIENT_NUMBER property contains an index into a table of recipients.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message transfer envelope objects (information store objects)
Identifier: | 0x6662
Property type: | PT_LONG
Access: | Read/write

Remarks

The PR_RECIPIENT_NUMBER property is on the recipient table of the message transfer envelope.

The X.400 system uses this number to deliver DRs and NDRs. Gateway developers can track messages by using this property to assign the same number to a recipient as occurs on the foreign system.


PR_RECIPIENT_ON_ASSOC_MSG_COUNT

The PR_RECIPIENT_ON_ASSOC_MSG_COUNT property contains the total number of recipients on the associated messages in a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66b0
Property type: | PT_LONG
Access: | Read/write


PR_RECIPIENT_ON_NORMAL_MSG_COUNT

The PR_RECIPIENT_ON_NORMAL_MSG_COUNT property contains the total number of recipients on the normal messages in a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66af
Property type: | PT_LONG
Access: | Read/write


PR_REPLICA_LIST

The PR_REPLICA_LIST property contains a list of the distinguished names of the servers that are replicating the contents of a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x6698
Property type: | PT_BINARY
Access: | Read/write

Remarks

PR_REPLICA_LIST is a binary property on public folders that contains the list of servers that are content-replicating a given public folder. The format is a list of distinguished names, one for each replica server, separated by NULLs. The server name is retrieved by parsing the distinguished name.


PR_REPLICA_SERVER

The PR_REPLICA_SERVER property contains the server name from which a message is replicated.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder and message objects (information store objects)
Identifier: | 0x6644
Property type: | PT_TSTRING
Access: | Read-only

Remarks

The PR_REPLICA_SERVER property is used on messages contained in public folders. Public folder replication can make a public folder visible to a server without copying the contents of the public folder to the server. PR_REPLICA_SERVER records the server on which a public folder message is physically stored.


PR_REPLICA_VERSION

The PR_REPLICA_VERSION property contains the version number of the installation of Microsoft Exchange Server.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder and message objects (information store objects)
Identifier: | 0x664e
Property type: | PT_I8
Access: | Read-only

Remarks

When read on a private folder, the PR_REPLICA_VERSION property contains the version of the home server. When read on a public folder, it contains the version of the server on which folder replica resides.

The format for PR_REPLICA_VERSION is:

  • The HighPart member of the ULARGE_INTEGER structure contains the Microsoft Exchange major version in the high order word and the Microsoft Exchange minor version in the low order word.
  • The LowPart member of the ULARGE_INTEGER structure contains the Microsoft Exchange build number (integral part) in the high order word, and the build number (decimal part) in the low-order word.

For example:

To represent Microsoft Exchange 5.5, build 1635.09, the ULARGE_INTEGER of PR_REPLICA_VERSION would contain these values:

  • HighPart DWORD, high-order word contains: 5
  • HighPart DWORD, low-order word contains: 5
  • LowPart DWORD, high-order word contains: 1635
  • LowPart DWORD, low-order word contains: 09


PR_REPLICATION_ALWAYS_INTERVAL

The PR_REPLICATION_ALWAYS_INTERVAL property is reserved for internal use.


PR_REPLICATION_MESSAGE_PRIORITY

The PR_REPLICATION_MESSAGE_PRIORITY property is reserved for internal use.


PR_REPLICATION_MSG_SIZE

The PR_REPLICATION_MSG_SIZE property is reserved for internal use.


PR_REPLICATION_SCHEDULE

The PR_REPLICATION_SCHEDULE property is reserved for internal use.


PR_REPLICATION_STYLE

The PR_REPLICATION_STYLE property is reserved for internal use.


PR_REPORT_DESTINATION_ENTRYID

The PR_REPORT_DESTINATION_ENTRYID property contains the entry identifier of the immediate destination of a delivery or nondelivery report.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x6665
Property type: | PT_BINARY
Access: | Read/write


PR_REPORT_DESTINATION_NAME

The PR_REPORT_DESTINATION_NAME property contains the display name of the immediate destination of a report.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x6664
Property type: | PT_TSTRING
Access: | Read/write


PR_RESOLVE_METHOD

The PR_RESOLVE_METHOD property specifies the method used to resolve conflicts on messages in a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3fe7
Property type: | PT_LONG
Access: | Read/write

Values

0
RESOLVE_METHOD_DEFAULT
Default handling of message conflicts.
1
RESOLVE_METHOD_LAST_WRITER_WINS
Last writer will win the conflict.
2
RESOLVE_METHOD_NO_CONFLICT_NOTIFICATION
Same steps as with RESOLVE_METHOD_DEFAULT, except that the contacts defined on a folder and the modifiers of a message are not notified.

Remarks

When two users have simultaneously edited a message in a public folder, the resulting edited versions are in conflict. The conflict is resolved by the method specified by this property. The rejected version of the message is retained as an attachment to the edited version.

For more information, see Default Conflict Resolution, Handling Message Conflicts, Last Writer Wins, and No Conflict Notification.

See Also

PR_IN_CONFLICT


PR_RESTRICTION_COUNT

The PR_RESTRICTION_COUNT property contains the count of restrictions on a public folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x66aa
Property type: | PT_LONG
Access: | Read/write


PR_RIGHTS

The PR_RIGHTS property contains a user's effective rights on a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x6639
Property type: | PT_LONG
Access: | Read-only

Values

frightsReadAny
Reads any messages.
frightsCreate
Creates messages.
frightsEditOwned
Edits any messages owned by the user.
frightsDeleteOwned
Deletes any messages owned by the user.
frightsEditAny
Edits any message.
frightsDeleteAny
Deletes any message.
frightsCreateSubfolder
Creates subfolders for the folder.
frightsOwner
All the above rights on the folder.
frightsContact
Displays your name as the contact on the folder.
rightsNone
No rights on the folder.
rightsReadOnly
Reads any message in a folder.
rightsReadWrite
Reads from and writes to any message in a folder.
rightsAll
All the above rights on a folder.


PR_RULE_ACTION_NUMBER

The PR_RULE_ACTION_NUMBER property is reserved for internal use.


PR_RULE_ACTION_TYPE

The PR_RULE_ACTION_TYPE property is reserved for internal use.


PR_RULE_ACTIONS

The PR_RULE_ACTIONS property is reserved for internal use.


PR_RULE_CONDITION

The PR_RULE_CONDITION property is reserved for internal use.


PR_RULE_ERROR

The PR_RULE_ERROR property is reserved for internal use.


PR_RULE_FOLDER_ENTRYID

The PR_RULE_FOLDER_ENTRYID property is reserved for internal use.


PR_RULE_ID

The PR_RULE_ID property is reserved for internal use.


PR_RULE_IDS

The PR_RULE_IDS property is reserved for internal use.


PR_RULE_LEVEL

The PR_RULE_LEVEL property contains the exit level of a rule.

Quick Info

Header file: | EDKMDB.H
Applies to: | Rule table objects (information store objects)
Identifier: | 0x6683
Property type: | PT_LONG
Access: | Read/write

Remarks

When ST_EXIT_LEVEL is set on a rule, processing skips the rest of the rules.


PR_RULE_NAME

The PR_RULE_NAME property contains a name string that is used for provider self-documentation only.

Quick Info

Header file: | EDKMDB.H
Applies to: | Rule table objects (information store objects)
Identifier: | 0x6682
Property type: | PT_STRING8
Access: | Read-only

Remarks

The PR_RULE_NAME property is not used or displayed by the Microsoft Exchange Client provider.


PR_RULE_PROVIDER

The PR_RULE_PROVIDER property contains the name of the application that set a rule.

Quick Info

Header file: | EDKMDB.H
Applies to: | Rule table objects (information store objects)
Identifier: | 0x6681
Property type: | PT_STRING8
Access: | Read/write

Remarks

Deferred actions need this property 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 manipulates 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 carry out the action when the rule is fired and a deferred action is created.


PR_RULE_PROVIDER_DATA

The PR_RULE_PROVIDER_DATA property is reserved for internal use.


PR_RULE_SEQUENCE

The PR_RULE_SEQUENCE property is reserved for internal use.


PR_RULE_STATE

The PR_RULE_STATE property is reserved for internal use.


PR_RULE_TRIGGER_HISTORY

The PR_RULE_TRIGGER_HISTORY property is reserved for internal use.


PR_RULE_USER_FLAGS

The PR_RULE_USER_FLAGS property is reserved for internal use.


PR_RULES_DATA

The PR_RULES_DATA property contains the PR_RULES_TABLE object.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder objects (information store objects)
Identifier: | 0x3fe1
Property type: | PT_BINARY
Access: | Read/write

See Also

PR_HAS_RULES, PR_RULES_TABLE, Working with Rules


PR_RULES_TABLE

The PR_RULES_TABLE property contains a table with all rules applied to a folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder objects (information store objects)
Identifier: | 0x3fe1
Property type: | PT_OBJECT
Access: | Read-only

Remarks

The PR_RULES_TABLE property is present on all folder objects that have rules. Values included in this property are used for reading and modifying rules. You can use the IMAPIProp::OpenProperty method to obtain an IExchangeModifyTable interface to the rules table on a folder. You can use this interface to read and modify those rules. This call and the interface are demonstrated in the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\RULECLS\RULECLSF.CPP source file.

See Also

IExchangeModifyTable, PR_RULES_DATA, Working with Rules


PR_SCHEDULE_FOLDER_ENTRYID

The PR_SCHEDULE_FOLDER_ENTRYID property contains the folder entry identifier for a schedule folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Mailbox objects (information store objects)
Identifier: | 0x661e
Property type: | PT_BINARY
Access: | Read-only

Remarks

The schedule folder is a subfolder of a mailbox. It stores Schedule+ data and is not seen by the user. Schedule+ data is stored as a property on this nonstandard folder located under the root directory of a mailbox. This folder is not replicated.


PR_SECURE_ORIGINATION

The PR_SECURE_ORIGINATION property determines whether messages have been modified to look like forwarded messages when they are dragged into the folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public folder objects (information store objects)
Identifier: | 0x3fe5
Property type: | PT_BOOLEAN
Access: | Read/write (writeable only by folder owners)

Values

0
FALSE = Messages moved or copied into the folder are unchanged.
1
TRUE = Messages moved or copied into the folder are modified to appear like they were forwarded by the user.

Remarks

When the PR_SECURE_ORIGINATION property is set to TRUE, all messages created, moved, copied, or sent to the folder will have a trustworthy sender. Users will not be able to create messages that appear to be sent by other people. Nor will they be able to place them in the folder without having them modified so that they are the sender of the message.

When this property is set to FALSE, the public folder serves as an information repository to which users can drag in messages from any source with out having the message changed.

This property is exposed in the Microsoft Exchange Client user interface. See Folder/Properties and select the Administration tab. The drop/down labeled Drag drop posting is: " Allows you to set this property to either Move/Copy (=FALSE) or Forward (=TRUE).


PR_SOURCE_KEY

The PR_SOURCE_KEY property contains a binary number that uniquely identifies the message or folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Folder and message objects (information store objects)
Identifier: | 0x65e0
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_SOURCE_KEY property is primarily used by the incremental change synchronization (ICS) interface and contains a binary number that uniquely identifies a message or a folder. When an object is created in an information store, the information store assigns a value to the PR_SOURCE_KEY property on the object.

For Microsoft Exchange Server, this property is 22 bytes in length, including the store GUID (16 bytes) and a 6-byte unique number that identifies the object within the store.

Synchronizer implementers must format the PR_SOURCE_KEY as a minimum of 17 bytes in length, including a GUID and a unique binary number that identifies the object within the foreign store.

Note: It is recommended that third-party developers do not use 6 bytes as their unique number

For more information, see About Incremental Change Synchronization.

See Also

IExchangeExportChanges, IExchangeImportHierarchyChanges, IExchangeImportContentsChanges, IExchangeManageStore, PR_PARENT_SOURCE_KEY, PR_PREDECESSOR_CHANGE_LIST, PR_CHANGE_KEY


PR_SPLUS_FREE_BUSY_ENTRYID

The PR_SPLUS_FREE_BUSY_ENTRYID property contains the entry identifier of the Schedule+ free/busy subtree top-level folder.

Quick Info

Header file: | EDKMDB.H
Applies to: | Public store objects (information store objects)
Identifier: | 0x6622
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_SPLUS_FREE_BUSY_ENTRYID property identifies the top-level folder. The Schedule+ free/busy subtree is not seen by users, but is replicated.

The Schedule+ free/busy subtree top-level folder is a subfolder of the non-IPM subtree. There is an individual subfolder for each site.

See Also

PR_FREE_BUSY_FOR_LOCAL_SITE_ENTRYID


PR_STORAGE_LIMIT_INFORMATION

The PR_STORAGE_LIMIT_INFORMATION property contains information about whether a mailbox is currently within the storage limit set by the Administrator program.

Quick Info

Header file: | EDKMDB.H
Applies to: | N/A
Identifier: | 0x66a4
Property type: | PT_LONG
Access: | N/A

Values

1
MDB_LIMIT_BELOW
2
MDB_LIMIT_ISSUE_WARNING
4
MDB_LIMIT_PROHIBIT_SEND
8
MDB_LIMIT_NO_CHECK

Remarks

The PR_STORAGE_LIMIT_INFORMATION property can be set as a column in the table returned by the IExchangeManageStore::GetMailboxTable method. This table contains a row for each mailbox on the server giving information, such as the display name of the mailbox, number of bytes of storage used, last login time, and so on. To view the format of this table, see the Mailbox Resources tab for the Private Information Store property sheet in the Administrator program.

This property provides additional information about the mailbox, such as the bit values set that indicate whether the user is within the storage limits, over the limits, or if no limit is set.

See Also

IExchangeManageStore::GetMailboxTable


PR_STORAGE_QUOTA_LIMIT

The PR_STORAGE_QUOTA_LIMIT property contains the size of the storage quota that was exceeded by the user.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3ff5
Property type: | PT_LONG
Access: | Read-only

See Also

PR_EXCESS_STORAGE_USED, PR_SVR_GENERATING_QUOTA_MSG


PR_STORE_OFFLINE

The PR_STORE_OFFLINE property is reserved for internal use.


PR_SUBJECT_TRACE_INFO

The PR_SUBJECT_TRACE_INFO property contains trace information on a delivery or nondelivery message report.

Quick Info

Header file: | EDKMDB.H
Applies to: | Report objects (information store objects)
Identifier: | 0x6661
Property type: | PT_BINARY
Access: | Read/write


PR_SVR_GENERATING_QUOTA_MSG

The PR_SVR_GENERATING_QUOTA_MSG property contains the identity of the server that generates a message when a user exceeds the storage quota limit.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message objects (information store objects)
Identifier: | 0x3ff7
Property type: | PT_STRING8
Access: | Read-only

See Also

PR_EXCESS_STORAGE_USED, PR_STORAGE_QUOTA_LIMIT


PR_TEST_LINE_SPEED

The PR_TEST_LINE_SPEED property is reserved for internal use.


PR_TRACE_INFO

The PR_TRACE_INFO property contains trace information indicating how each messaging domain handled a particular message.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message transfer envelope objects (information store objects)
Identifier: | 0x6660
Property type: | PT_BINARY
Access: | Read/write

Remarks

The PR_TRACE_INFO property contains information about where a message has been since it was created. When the information associated with this property is prepared for transmittal across a foreign system, Microsoft Exchange Server encodes the information in a transmission-neutral encoding format (TNEF) with a little-endian byte order.


PR_TRANSFER_ENABLED

The PR_TRANSFER_ENABLED property contains whether gateway outbound message processing is enabled.

Quick Info

Header file: | EDKMDB.H
Applies to: | Gateway message store objects (information store objects)
Identifier: | 0x662a
Property type: | PT_BOOLEAN
Access: | Read/write

Values

0
FALSE = Outbound message processing is disabled.
1
TRUE = Outbound message processing is enabled.

Remarks

The state of the PR_TRANSFER_ENABLED property is undefined when the gateway initially starts, but is set to TRUE within 10 seconds. In other words, this property has no memory between sessions.

The gateway can set this property to FALSE at any time. Setting this property to FALSE will prevent any additional MTA messages from being transferred into the MTS-OUT folder. This property has no impact on the transfer of mail from the MTS-IN folder to the MTA.


PR_USER_ENTRYID

The PR_USER_ENTRYID property contains the entry identifier of a user.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message store objects (information store objects)
Identifier: | 0x6619
Property type: | PT_BINARY
Access: | Read-only

Remarks

The PR_USER_ENTRYID property contains the user's entry identifier, which is not always the same as the owner's entry identifier.

See Also

PR_MAILBOX_OWNER_ENTRYID


PR_USER_NAME

The PR_USER_NAME property contains the name of a user of a message store.

Quick Info

Header file: | EDKMDB.H
Applies to: | Message store objects (information store objects)
Identifier: | 0x661a
Property type: | PT_STRING8
Access: | Read-only

Remarks

The PR_USER_NAME property can be used to identify the store.

See Also

PR_MAILBOX_OWNER_NAME


File Formats

Several Microsoft Exchange Server sample applications and libraries transfer data by creating import and export files. The following sections describe the file formats required for performing development and maintenance tasks.


Directory Access Function Files

By default, import and export files used with the directory access functions are comma-separated ASCII text files. These files can have any extension, but the Microsoft Exchange Server Administrator program expects files with the .EXP extension for use with the Directory Import command of the Tools menu, and it expects .CSV files for use with the Directory Export command of the Tools menu.

An import file contains the attributes of the objects being imported, as well as the data of those attributes. Any attribute associated with an imported object can be manipulated by the directory access import functions. Moreover, depending on the object being handled (and the mode of the import operation), certain attributes may be required to be imported. This section explains these import requirements.

Note Characters used in a distinguished name (DN) or in any string used to build a DN (such as pszBasePoint and pszContainer) must be in the range 0x0020 to 0x007E.


Header Lines and Data Lines

The first line of an import file or export file is the header line. This line lists the attributes being imported (or exported) in order of their import or export. These attributes are designated by the names they are listed under in the Microsoft Exchange Server directory schema. Although other separators can be chosen, the comma is the default separator in this line (and all lines) in the import file, as shown in the following example of a header line:

Obj-Class,Common-Name,Given-Name,Surname,Home-Server,Display-Name

In this example, the six listed attributes are to be imported. In the lines that follow, the actual values for those attributes must be listed, separated by the same separator, in the order that the header line specifies. The following lines are typical data lines:

mailbox,SteveMas,Steve,Masters,FALCON,Steve Masters
mailbox,KevinY,,BOB,,

In the second line of this example, the value for the third attribute (Given-Name) is left blank, as indicated by the first pair of consecutive commas. Depending on the attribute, blank values are sometimes constructed from the values of other attributes, or from the values of a specified user template. Examples of using of directory access import files are given later in this section.

Note Within a given container, objects are identified by the Common-Name property. The BatchImport function uses the Common-Name property to construct the Directory-Name of the object. Multiple lines in the import file having the same value for Common-Name refer to the same object.


Special Import Columns

Import files use two special column types. The first column specifies the type (the Obj-Class) of object to be created. The second column (the Mode) is optional, and designates the operation mode of the import procedure. Obj-Class and Mode are known as pseudo-attributes.


Specifying the Object Class

The first column specifies the type of object to be created. It must appear first and must have a name of Obj-Class. Options available for use as values in this column are shown in the following table. For an illustration, see Example: Importing Directory Data.

Import Object Types (with Object Types in Column 1)

Value | Comment
mailbox | Designates that a mailbox is to be created
remote | Designates that a remote user is to be created
dl | Designates that a distribution list is to be created.


Specifying the Import Mode for BatchImport

The second column is called Mode. It is used to specify the operation mode for the import procedure and is optional. If it is not specified in the import file, the import function assumes Update mode.

Import Modes Used by BatchImport

Mode | Import Behavior
Update | Create data if it does not exist; modify data if it does exist. This is the default mode if no Mode is specified
Create | Specifies that information contained in the row is to be used to create a new object of type Obj-Class; generate an error if the object already exists.
Modify | Specifies that information contained in the row is to be used to modify the existing object identified by Common-Name; generate an error if the object is not found.
Delete | Specifies that an existing object identified by Common-Name is to be deleted; log a warning if the object is not found.

When creating a directory object, be sure to use Create mode if you need to have an error generated for failed creation operations.


Import Requirements

All directory objects have required and optional attributes. When you use directory access functions to import objects, pay special attention to the required attributes and types of import requirements. The following table denotes codes used in this section to identify the import requirements of each object attribute.

Import Requirements

Code | Import Requirements
R | Required field. Must exist and contain valid data in the data file.
C | Required field. If this field does not exist in the data file, it will be constructed by data derived from information in other columns of the data file.
I | Required field. Must either exist and contain data in the data file, or a user template must be specified and the values will be inherited from the user template.

In the directory schema, mailboxes (Mailbox object), remote users (RemoteAddress object), and distribution lists (DistributionList object) are all subclasses of the Mail-Recipient object. This means that most of the common required fields are part of the Mail-Recipient object. The following tables show the required attributes of the Mail-Recipient object, and their relationship to the user interface of the Microsoft Exchange Server Administrator program, as well as the import requirements code.

In the following tables, the Code column gives the letter representing the import requirement of that attribute, as explained in the previous (Import Requirements) table. No optional attributes are listed in these two tables. For a complete list of attributes, including those that are optional, refer to the directory schema reference section.

Mail Recipients

Directory Attribute Name | Import File Header | Code | Description
Common-Name | Common-Name | R | Specifies the common name used for the mailbox name and Windows NT account name.
Display-Name | Display-Name | C | Specifies name that appears in the address book. If not specified, will be constructed (in the form of Given Name, Surname, Generation Qualifier).
Hide-From-Address-Book | Hide-From-AB | I | Specifies flag that, when set, keeps the user from appearing in the address book. Defaults to FALSE if not provided in the input file. Note: FALSE is a value of 0 in the data file. TRUE is any nonzero value.
Home-Server | Home Server | I (for Mailbox only) | Specifies the user's home server. The Home-DSA, Home-MTA, and Home-MDB attributes all inherit the Home Server value. Attribute conflicts generate an error during Import.
Surname | Surname | C | Specifies the user's Last Name. If not specified, Common-Name will be placed in the Surname field.

Mailbox objects have additional attributes beyond those inherited from Mail-Recipient. The following table describes these additional attributes, the relationship to the user interface of the Administrator program, and the import requirements.

Mailbox Attributes

Attribute Name | Admin. Display Name | Code | Description
Delivery-Mechanism | Delivery-Mechanism | I | 0 = MDB 1 = XAPI Delivery Queue 2 = XAPI Retrieval Queue Default to MDB if not specified
Assoc-NT-Acccount | Assoc-NT-Acccount | C | Same as Common-Name. The Windows NTaccount that is considered the primary Windows NT account on this object.


Restrictions on Import Values

The DAPIWrite and BatchImport import functions can import attribute values expressed only as 7-bit ASCII characters. In this respect, they follow the model of the Administrator program. Import functions map Common-Names (and other values such as server names, account names, and passwords) that fall outside the set of 7-bit ASCII characters.

Disallowed characters are mapped to other characters that look similar, or to spaces. For example, Å maps to A, and £ maps to L. The case of the original letter is preserved.


Example: Importing Directory Data

The following is an sample data file for an import session with no user template selected:

Obj-Class,Common-Name,Given-Name,Surname,Home-Server,Display-Name
mailbox,SteveMas,Steve,Masters,FALCON,Steve Masters
mailbox,JerryWh,Jerry,Wheeler,BOB,,
mailbox,KevinY,,,BOB,

In the above example, three mailboxes are created:

  • As specified on the second line, a mailbox for SteveMas is created on the server Falcon. The Given-Name, Surname, and Display-Name information was provided and these attributes are imported.
  • As specified on the third line, a mailbox for JerryWh is created on the server called BOB. The Given Name and Surname are set. The Display Name is created from the Given Name and Surname as Jerry Wheeler because it was not provided.
  • As specified on the fourth line, a mailbox for KevinY is created on the server called BOB. The Surname is set to KevinY because it was not provided. This would also cause the Display-Name to be set to KevinY.

The following is an example data file for an importing session where a user template was selected. This user has a Home-Server of FALCON. (In this example, the user template was designated not in the import file, but through the user interface of the Administrator program.)

Obj-Class,Common-Name,Given-Name,Surname,Display-Name,Member
mailbox,SteveMas,Steve,Masters,,MailPM%MAPITest
mailbox,SharonSw,Sharon,Swanson,Sharon Swanson,Testers

In the preceding example, two mailboxes are created on the FALCON server, a fact derived from the Home-Server attribute of the user template.

  • As specified on the second line, a mailbox for SteveMas is created with a Given Name of Steve and a Surname of Masters. The Display-Name of Steve Masters is constructed; the distinguished name (DN)for SteveMas is added to the membership list for the distribution lists (DL) called MailPM and MAPITest.
  • On the second line, the names of these DLs for SteveMas are separated by a percent sign (%). You can select a different separator by choosing the Directory Import option from Tools menu in the Administrator program. Click Separators to open the Separators dialog box.
  • As specified on the third line, a user SharonSw is created with a Given Name of Sharon and a Surname of Swanson. The Display Name was specified as Sharon Swanson; the DN for SharonSw is added to the DL called Testers.

If the option had been set in the Administrator program user interface to create the Windows NT Server security account, a Windows NT Server account is created in the Windows NT Server security domain for each of these users. The Windows NT user name is the same as the Common-Name.


POPPST .INI File

The .INI file for the POPPST sample application is structured consistently with standard Microsoft .INI files. It requires section header lines and section entry lines. In a section header line, the section keyword is enclosed in square brackets. Section entry lines start with an entry keyword that is immediately followed by an equals sign (=), which in turn is followed by a value for the section entry. All characters (including whitespace) following the '=' up to the next <newline> are included in the value. Leading whitespace is permitted and is not significant, but whitespace in all other locations is significant.

You may include comments by using a semicolon (;) as the first non-whitespace character on a line. Blank lines may be included in the .INI file and are ignored.

The POPPST .INI file can contain three kinds of sections:

  • A [newpst] section in the .INI file defines the values used for the creation of a new PST.
  • Use a [profile] section to identify an existing Microsoft Exchange Server profile that contains a PST to which you want to add messages.
  • A [message] section contains properties used to create a test message that is to be added to a new or existing PST. Using additional [message] sections causes the creation of additional test messages.

Either a [newpst] section or a [profile] section is required, and must be the first section in the .INI file. However, you must not use both a [newpst] section and a [profile] section in one .INI file.

If you specify a [newpst] section, a temporary profile will be used, which means that no name resolution will be possible. If you specify the [profile] section, the message created will be placed in the specified folder in the default message store. If you want the message to be placed into your PST, then you must first set the Personal Folders information store to be your default information store for the specified profile. To do this, select the Options choice of the Tools menu in the Microsoft Exchange Client, and then click the Delivery tab. Then, click Personal Folders in the drop-down list box labeled Deliver new mail to the following location.

One or more [message] sections can follow the [newpst] or [profile] section.

Unless noted as optional in the following description, all section entry lines are required and must occur exactly once per section. The order of section entries within a section is not important. Keywords used in the POPPST program are not case-sensitive. Maximum line-length is 512 characters (MAXINIFILELINE), including the <newline> character.


POPPST .INI File Format

Notations that describe POPPST.INI file grammar

Symbol | Meaning
Angle brackets (<>) | Indicate a token or syntactic element.
Braces ({}) | Indicate an optional syntactic element.
Ellipsis (...) | Indicate that the preceding syntactic element may be repeated.
// | Indicates embedded comments (not part of the file format)
| | Indicates alternation (a | b implies a or b is acceptable)

All required parameters must be represented by non-null strings. To omit an optional parameter, leave the entire line out. For example, to omit the value for XTEXT in the [message] section, delete the entire line beginning with XTEXT= instead of retaining the line and assigning no value.

Note Assignment lines cannot contain spaces between the keyword and the value being assigned. For example, the following line is valid:

XTEXT=boxy.txt

This line is not valid:

XTEXT= boxy.txt

The [newpst] section is used to create a new PST and to add messages to it:

[newpst]
NAME=<pst display name string>
ENCRYPTION=<encryption state>
PASSWORD=<pst password string>
PATH=<file path>

The [profile] section is used to add messages to an existing PST in an existing Microsoft Exchange Server profile:

[profile]
NAME=<profile name string>
PASSWORD=<profile password string>

The [message] section provides values for the properties of a new message to be created. The <number> value in the message section header should be unique. POPPST doesn't actually use the number. It is there only for Windows API compatibility.

[message<whitespace><number>]
    FROM=<user name>
    TO=<user name>{;<user name>}
    CC=<user name>{;<user name>}...     // Optional.
    BCC=<user name>{;<user name>}...    // Optional.
    FOLDER=<folder path>
    SUBJECT=<string>
    XTEXT=<file path>                   // Optional
    DATE=<date>
    TIME=<time>
    PRIORITY=<priority>
    XATTACH=<file path>{;<file path>}.. // Optional.


Syntax of POPPST .INI Elements

The following BNF description applies to the syntactic elements used in POPPST .INI file. Many of the lines in the BNF description are followed by a comment indicating that the string must be acceptable input for a given parameter of a given function, or a valid value for a given property.

<pst display name string> :
    <string>    // Must be a valid PR_DISPLAY_NAME value.

<pst password string> :
    <string>    // Must be a valid PR_PST_PW_SZ_NEW value.

<profile name string> :
    <nonnull string>
        // Must be valid lpszProfileName param of MAPILogon().

<profile password string> :
    <string>    // Must be valid lpszPassword param of MAPILogon().

<whitespace> :
    <char>    // where isspace(<char>) == TRUE

<number> :
    <digit>...

<user name> :
    <user display name>{[<address type>:<email address>]}

<user display name> :
    <nonnull string>    // Must be a valid PR_DISPLAY_NAME value.

<address type> :
    <nonnull string>    // Must be a valid PR_ADDRTYPE value.

<email address> :
    <nonnull string>    // Must be a valid PR_EMAIL_ADDRESS value.

<folder path> :
    {<folder namestring>{\<folder namestring>}...}
        // See the following section "Folder Path Usage."

<string> :
    {<char>}...

<file path> :
    <nonnull string>    // Must be valid filename param of fopen() API.

<date> :
    YYYY-MM-DD    // year-month-day, as digits.

<time> :
    HH:MM{:SS}    // hour:min{sec} as digits.

<encryption state> :
    ON | OFF

<priority> :
    HIGH | NORMAL | LOW

<nonnull string> :
    <char>...

<char> :
    Any char other than '\n'.

<digit> :
    0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

<folder namestring> :
    <nonnull string>
        // Must be a valid PR_DISPLAY_NAME value for a mailstore folder.


Folder Path Usage

A null folder path is used to specify the root folder of a mail store. To add a message to the user inbox, the correct folder path is Microsoft Personal Information Store\Inbox.


Creation of Message Properties

The properties that are created for each entry line in a message section are documented in the following table. In general, POPPST uses properties that enable Microsoft Exchange Client to display the message.

The lines TO:, CC:, and BCC: are used to set up the recipient table in the message. If the address book is available and <user name> can be resolved, PR_DISPLAY_NAME is used to derive PR_ADDRTYPE, PR_EMAIL_ADDRESS, and PR_ENTRYID.

If the address book is available, PR_ADDRTYPE and PR_EMAIL_ADDRESS may also be provided explicitly by using a <user name> of form <user display name>[<address type>:<email address>]. All names provided in <user display name> are also used to set the values of PR_DISPLAY_TO, PR_DISPLAY_CC, and PR_DISPLAY_BCC.

Entry Lines in POPPST.INI

Entry Notes
FROM: PR_SENDER_NAME = <user name>
PR_SENT_REPRESENTING_NAME = <user name>
Only one user name is allowed in the FROM: field.
TO: PR_RECIPIENT_TYPE = MAPI_TO;
PR_DISPLAY_NAME = <user name> for each <user name>;
CC: PR_RECIPIENT_TYPE = MAPI_CC;
PR_DISPLAY_NAME = <user name> for each <user name>;
BCC: PR_RECIPIENT_TYPE = MAPI_BCC;
PR_DISPLAY_NAME = <user name> for each <user name>;
FOLDER: Finds the folder that the message should be placed in. If it does not exist, it will be created.
SUBJECT: Sets PR_SUBJECT.
XTEXT: Contents of <file path> used to set PR_BODY.
DATE: Sets PR_MESSAGE_DELIVERY_TIME.
TIME: Sets PR_MESSAGE_DELIVERY_TIME.
PRIORITY: Sets PR_PRIORITY (not visible in Microsoft Exchange Client frontend).
XATTACH: Contents of <file path> used to set PR_ATTACH_DATA_BIN.
PR_ATTACH_METHOD = ATTACH_BY_VALUE.
PR_ATTACH_FILENAME = <file path>.
PR_ATTACH_LONG_FILENAME = <file path>.


Sample .INI File

The following .INI file was used by POPPST to create a new PST and place a single test message in it:

; [profile]
; NAME=Jerry Wheeler
; PASSWORD=

[newpst]
NAME=Personal Folders
ENCRYPTION=OFF
PASSWORD=
PATH=\WINNT\POPPST.PST

[message 1]
FROM=Jerry Wheeler
TO=None Two
BCC=Jerry Wheeler
FOLDER=Top of Personal Folders\Inbox
SUBJECT=POPPST Test Message 02/21/95-1
XTEXT=\PST\BODY.TXT
DATE=1995-02-21
TIME=10:25
PRIORITY=NORMAL
XATTACH=\PST\POPPST.INI

This example .INI file illustrates several points:

  • If you include both a [PROFILE] and a [NEWPST] section in an .INI file, one of them must be commented out.
  • Following the [NEWPST] section is a single [MESSAGE] section, which results in the creation of a single message in the new PST called POPPST.PST. (The "1" in the [MESSAGE] section header line is ignored by POPPST.EXE.)
  • POPPST does not ignore whitespace after the equals sign in a section entry line, such as the name of the mailbox (Personal Folders) in the new PST.
  • The body of the message to be created consists of the contents of the \PST\BODY.TXT file.
  • The \PST\POPPST.INI file is included in this new message as an attachment.


Migration Files

This section describes the file format required for migrating directory information, PAB entries, messages, public folders, documents, and schedule information (for Microsoft Schedule+). The actual migration procedure is described in About Source Extractors, where you can find definitions for migration concepts and terms such as packing list and primary file.

The packing list, primary, and secondary files share some common formatting rules, which help you quickly parse migration files. The packing list and primary files use comma-separated value (CSV) format. The secondary files use CSV format for header information, but raw data uses its own format. This allows you to edit the primary file, regardless of the source of the data.

You should use the file extension .PKL for packing list files, .PRI for primary files, and .SEC for secondary files. If you have multiple primary or secondary files, give similar root names to similar files. For example, you could use the names of postoffices or servers, appended with numbers.

All files must be in the same directory as the packing list file. Names of secondary files cannot contain any of the following characters:

# ( ) ; , \ / : * ? " < > |

Rules for Field Entries

Field entries are governed by various rules. Fields that contain any of the following characters must be enclosed in quotation marks:

# ! , \ " % .

The entire entry must be enclosed in quotation marks, not just the embedded character. The following two examples show how the entries should appear in the primary or secondary files.

Entry | Appearance in file
Lee, Bill | "Lee, Bill"
my name is "Sherry" | "my name is ""Sherry"""

In the second example, two quotes represent a single quote, and the last quote shows that the entire entry is quoted.

Any fields in a directory section of the primary file that have a backslash (\) character need to have a second \ character in addition to being enclosed in quotation marks.

For multivalued fields, such as distribution list members or e-mail addresses, each value can be quoted, but delimiters cannot be within quotes. In the following example, the semicolon (;) delimiter is not inside quotes.

"Jim_Hance@NorthWind";"Stephen Gray@NorthWind"

The following table lists other entries and their accompanying rules.

Entry | Rule
Spaces | No extra spaces at the beginning of a line, or before or after field-delimiting commas, unless part of the data to be migrated.
End of line | Each line of data ends with a carriage return and line feed.
Blank lines | Must consist only of a carriage return and line feed. They will be ignored.
Comment lines | Begin with an exclamation point (!). Comment lines are useful for storing information, such as when the data was extracted and what parameters were set for extracting the data.
Continuation character | If system supports a limited number of columns in a file, use a double backslash (\\), followed by a carriage return and line feed. It will be placed anywhere in a primary file, and it signals that the next line in the file must be appended to the current line. Line continuations will not work within comments, inside quotation marks, directory sections of primary files, or secondary files.
Code-page | No default code-page. Files can be in any code-page supported by Windows NT Server. Only one code-page for each set of primary and secondary files. You must specify the code-page on the first line of the packing list file. UNICODE is not supported as a valid code-page.
Case sensitivity | Header lines and parsing text are not case sensitive.
Dates, times, and durations | Represented by 14-digit numbers: first 4 digits = year, second 2 digits = month, third 2 digits = day, fourth 4 digits = time on a 24-hour clock, fifth 2 digits = seconds. For example, May 1, 1995, at 10:00:05 P.M. = 19950501220005. One year, 4 months, 3 days, 22 hours, and 2 seconds = 00010403220002. (Local times, not Greenwich Mean Time.)
Carriage returns without line feeds | Converts to carriage returns with line feeds. When you move the migration file from the source system to Windows NT Server, the conversion is likely to add line feeds, which may be unacceptable.


Formatting for Addresses Delimited by Semicolons

Multivalued fields that are delimited by semicolons — such as X.400 addresses, distribution list members, and e-mail addresses — must follow these formatting conventions:

  • The entire distribution list membership field must be placed within a pair of double quotation marks.
  • The e-mail address mini-field that contains semi-colons must be placed within a pair of double quotation marks.
  • All quotation marks that are part of the field entry must themselves be placed within a pair of double quotation marks.

For example:

dl,Friends,\\
"SMTP:mariab@litware.com;""X400:C=US;A= ;P=NWTraders;G=Joe;S=Parkes"""\\
,,,,,,,,,,,,,,,,,,,,,

If your existing system requires that you avoid these formatting rules with semicolons, it's recommended that you specify X.400 addresses by using a slash ( / ), as shown in the following example:

dl,Friends,\\
SMTP:mariab@litware.com;X400:/C=US/A= /P=NWTraders/G=Joe/S=Parkes\\
,,,,,,,,,,,,,,,,,,,,,


Formatting the Packing List File

The packing list file reports the code page in which the files are stored and lists all primary and secondary files. The first bytes of the packing list file specify the standard code-page number used in all of the primary and secondary files. The code-page number is on a line by itself and is followed by a blank line. The following sample packing list file illustrates the format:

850

Filename,Filetype
SALESPO1.PRI,Primary
SALESPO1.SEC,Secondary
SALESPO2.SEC,Secondary

The code-page number in this example is 850. The suggested code pages are 850 and 1252, but the code page that you use depends on your existing system, file transfer to the Microsoft Exchange Server, and the languages supported.


Formatting the Primary Files

The primary files contain one or more sections. Each section contains one of the following types of data:

Directory Information

Each line of data can create or modify any mailbox, custom recipient, or distribution list in the Microsoft Exchange Server directory. The data is in directory import format, which is described in Formatting Directory Information. For general information on directory data format, see Directory Access Function Files.

PAB Entries and Personal Distribution Lists

Each line of data creates a personal address book (PAB) or personal distribution list entry. There is one section for each mailbox. A mailbox must be created before entering this data. See Formatting PAB Entries and Personal Distribution Lists.

Messages and Public Folders

Each line of data creates a message or an item in a mailbox or public folder. Each section holds entries for one mailbox or for any number of public folders. Sections must be separated by a blank line. Messages can be imported to create a mailbox.

Each line of data has one or more comma-separated values (CSVs). If any of these values has a carriage return or line feed character, put it into a secondary file. (The same parsing rules apply in the secondary file: strings with special characters need to be in quotes.)

Replace the value with a pointer to the secondary file and an offset to where the header of the data begins. For example: #SALESPO2.SEC(43232). The # sign indicates that the data is stored in another file, the SALESPO2.SEC secondary file. The data is located 43232 bytes from the beginning of that file, and this offset counts end-of-line characters such as carriage returns and line feeds. For more information, see Formatting Messages and Public Folders.

Note It is important that transferring the secondary files from another platform or system does not introduce new characters. If this happens, the offsets in the primary file could be inaccurate.


Formatting Directory Information

Each directory import section of the primary file begins with DIRECTORY. This is followed by a header line. Each line thereafter is one object. For example:

DIRECTORY
Obj-class,Mode,Common-Name,Display-Name,Last Name,First
Name,Secondary-Proxy-Addresses,Home-Server
mailbox,create,ElizaB,Elizabeth
Brown,Brown,Elizabeth,MIGRATE:PROFS:Sydney(EBrown),~Server
mailbox,create,PatPa,Pat
Parkes,Parkes,Pat,MIGRATE:PROFS:Sydney(PParkes),~Server
mailbox,create,MiguelF,Miguel
Fernandez,Fernandez,Miguel,MIGRATE:PROFS:Sydney(MFernan),~Server

Important Items in the directory section cannot have pointers to data in the secondary file. All data in the directory section must be in the primary file.

The format of the directory import section in the primary file is slightly different from Directory Import in the Administrator program. In the primary file the mode header field is required and must always be set to create. If the object already exists, an error will be reported. In the Administrator program, the mode header field is optional and can be set to create, modify, or delete. For information on additional attributes, see Appendix D in the Microsoft Exchange Server Migration Guide.

Backslash Characters in Directory Sections of Migration Files

The Migration Wizard tries to import all directory sections in the migration files without modifications. If there is a single backslash (\) character, this is interpreted as an escape character. If the next character is a 'r' or 'n,' the two characters are interpreted as a carriage return or new line character, respectively. If the next character after the backslash is not an 'r' or 'n', an error is logged in the application log.

If you are creating a source extractor, you can avoid this problem by replacing all backslash characters with two backslashes (\\) in the directory section. If you encounter the error in the application log, you can modify the directory section in the primary file by either deleting the backslash, or replacing it with two backslashes.

This is not a problem with mail messages, attachments, schedule information or personal address books.


Formatting PAB Entries and Personal Distribution Lists

You can enter new personal address book (PAB) or personal distribution list data or you can move existing data into the migration file. The following example illustrates the formatting of each PAB data section:

PAB,migrate:PROFS:SANFRN(HOWARDS)
Obj-class,Display-Name,Email-Address,First,Last,Address,City,\\
State,Zip,Country,Title,Company,Department,Office,Assistant,\\
Bus-Num,Bus2-Num,Assist-Num,Fax-Num,Home-Num,Home2-Num,\\
Mobile-Num,Pager-Num,Note
entry,Pat Parkes,SMTP:patp@Litware.com,Pat,Parkes,,,,\\
,,,"Litware, Inc.",,,,,,,,4155551212,,,,
entry,Dad,X400:cn=ronar;p=NWTraders;a= ;c=JP,,,,,,,,,,,,,,,,,,,,
dl,My Friends,Dad;Pat Parkes,,,,,,,,,,,,,,,,,,,,,\\
Personal Distribution List of my friends

The following table describes the fields in the header line. Only the first three fields (Obj-class, Display-Name, and Email-Address) are required, but the header line must have all the fields in the order shown. Only the first three fields and the Note heading are valid for personal distribution lists.

Heading | Description
Obj-class | Required. The type of entry. For a single recipient, entry. For personal distribution lists, dl.
Display-Name | Required. Friendly name.
Email-Address | Required. E-mail address or addresses. For personal distribution lists, use a semi-colon to separate addresses. (If the source system doesn't support this information, put in the invalid data: USER: Display-Name)
First | Given name.
Last | Surname.
Address | Street address.
City | City name.
State | State or province.
Zip | Zip or postal code.
Country | Recipient's country.
Title | Position in the company.
Company | Company name.
Department | Department name or number.
Office | Office location.
Assistant | Assistant's name.
Bus-Num | Primary business telephone number.
Bus2-Num | Secondary business telephone number.
Assist-Num | Telephone number of the recipient's assistant.
Fax-Num | Fax number.
Home-Num | Primary home telephone number.
Home2-Num | Secondary home telephone number.
Mobile-Num | Cellular telephone number.
Pager-Num | Pager number.
Note | Description or note for this entry or distribution list.


Formatting Messages and Public Folders

The migration files can include messages, attachments, documents, and public data. Public folder data is imported as a special kind of message. The header line of each section starts with MAILMESSAGE and is followed by the source e-mail address or PublicMessage.

Messages

The following example illustrates the format of each message section:

MAILMESSAGE,PROFS:SANFRAN(HOWARDS)
Folder,Sender,To,Cc,Bcc,Subject,Send-Date,Received-Date\\
,Priority,Unread,Unsent,Body
Inbox,Pat Parkes,Elizabeth Brown,,,"Let's make plans for this
Friday",19950321093421,19950321093421,-1,,,#SALESPO1.SEC(50)
Phoenix Project,Pat Parkes,Ali Gobi,,,Review of Back Office\\
,19950321063321,19950321063321,,,,#SALESPO1.SEC(161)
Filed Mail\FYI,Jon Grande,Gamers[SMTP:gamers@Litware.com],\\
,,Solo Mission,19950218234539,19950218234539,,,,#SALESPO1.SEC(575)

Public Folders

The following example illustrates the public folder format:

MAILMESSAGE,PublicMessages
Folder,Sender,To,Cc,Bcc,Subject,Send-Date,Received-Date\\
,Priority,Unread,Unsent,Body
Social\Gamers,Pat Parkes,Games Groups,,,"Plans for this
Saturday",19950320092421,19950320092421,-1,,,#SALESPO2.SEC(693)
Business\Phoenix Project,Karl Buhl,Phoenix Project,,,\\
Reviews,19950320093221,19950320093221,,,,#SALESPO2.SEC(798)

Public folder data is migrated from shared folders, bulletin board systems, and databases. If formatting will be lost or if the data would be unreadable in Microsoft Exchange Server, convert the information to text.

The following table describes the fields in the header line for messages and public folders. All fields are required and must be in this order.

Heading | Description | Values
Folder | Path to destination folder. Use backslash to indicate subfolders. | Default = Inbox. Inbox, Deleted Items, Outbox, and Sent Items get mapped to special folder identifier numbers. Display name of folders depends on language of client.
Sender | Display name of sender. | Display name or display name [e-mail address].
To | Display name of To recipients, separated by semicolons. | Display name or display name [e-mail address].
Cc | Display name of Cc recipients, separated by semicolons. | Display name or display name [e-mail address].
Bcc | Display name of Bcc recipients, separated by semicolons. | Display name or display name [e-mail address].
Subject | Subject of message. | Single line of text.
Send-Date | Date message sent. | Date and time.
Received-Date | Date message received. | Date and time.
Priority | Priority of message. Default = 0. | Low priority = -1. Normal priority = 0. High priority = 1.
Unread | Boolean value to indicate read status of message. | TRUE if message was not read. FALSE if message was read. (Default = FALSE.)
Unsent | Boolean value to indicate sent status of message. | TRUE if message was not sent. FALSE if message was sent. (Default = FALSE.)
Body | One pointer to body of message. You must use the secondary file for message bodies and attachments. Attachments are referenced from bodies of secondary file. | #filename(offset)

For systems that support only sent dates or only received dates, the source extractor should set the received date and sent date to appropriate date values. For systems that support neither sent nor received dates, the source extractor can leave the fields blank or substitute the current date and time.


Specifying X.400 Addresses in the Primary Files

The "Formatting the Migration Files" topic in the Microsoft Exchange Server Migration Guide states a rule for enclosing multivalued fields within quotation marks. For X.400 addresses, that rule does not apply in certain cases. Instead, multivalued fields (such as distribution list members or e-mail addresses) that are separated by semicolons follow the following formatting conventions:

  • The entire distribution list membership field must be within quotation marks.
  • The e-mail address field that contains semi-colons must be within quotation marks.
  • All quotation marks that are part of the field entry must be within quotation marks.

Note These rules do not apply for fields separated by a slash ( / ).

For example:

dl,Friends,\\
"SMTP:mariab@litware.com;""X400:C=US;A= ;P=NWTraders;G=Joe;S=Parkes"""\\

To avoid the formatting rules with semicolons, you can specify X.400 addresses by using the slash ( / ) as shown in the following example:

dl,Friends,\\
SMTP:mariab@litware.com;X400:/C=US/A= /P=NWTraders/G=Joe/S=Parkes\\

Because of the formatting rules for X.400 addresses, the example in the Microsoft Exchange Server Migration Guide under "PAB Entries and Personal Distribution Lists" should read as follows:

PAB,PROFS:SANFRN/HOWARDS
Obj-class,Display-Name,Email-\\
Address,First,Last,Address,City,State,Zip,Country,Title,Company,Depart\\
ment,Office,Assistant,Bus-Num,Bus2-Num,Assist-Num,Fax-Num,Home-\\
Num,Home2-Num,Mobile-Num,Pager-Num,Note
entry,Pat Parkes,SMTP:patp@litware.com,Pat,Parkes,,,,,,,\\
"Litware,Inc.",,,,,,,,415-555-1212,,,,
entry,Dad,X400:/C=US/A= /P=NWTraders/G=Joe/S=Parkes,,,,,,,,,,,,,,,,,,,,
dl,My Friends,X400:/C=US/A= \\
/P=NWTraders/G=Joe/S=Parkes;SMTP:patp@litware.com,,,,,,,,,,,,,,,,,,,,,


Formatting the Secondary Files

A secondary file is a collection of one or more sections that each contain a description of the data, followed by the actual data. A message body and its attachments are in separate sections.

The offset in the primary file specifies the first section in the secondary file for messages with multiple sections. Sections are separated by blank lines. The following example shows the format of secondary files:

Type,Length,Encoding,Islast,Name,Position,Format
Body,91,,TRUE,,,
Do you want to play a game of racquetball after work tonight?

Pat

Body,70,,FALSE,,,
I saw this short review of Microsoft Back Office products.

Pat

Attachment,205,,TRUE,backoffi.txt,0,
Microsoft BackOffice package includes Windows NT Server, Microsoft Exchange Server, SQL Server, and System Management Server.

Other,51,,TRUE,,,
leslied;sallys;marck;louisej;robinh;bobbyq;gregoryc

The following table describes the fields in the header line of secondary files.

Heading | Description | Values
Type | Required. Type of data. | Body, Attachment, Schedule, Document, or Other.
Length | Required. Length of data in bytes, including end-of-line characters. | Integer. If message is body part of a free document, the length must = 0.
Encoding | Reserved field. | Leave blank.
Islast | If TRUE, body or attachment is the last in the file for this message. If FALSE, the next section in file is either body or attachment for this message. | TRUE or FALSE.
Name | File name of attachment. | Required for sections that are attachments and documents, and ignored otherwise.
Position | Optional. Location, in bytes, where icon for attachment should be placed. Valid only for attachments. | Default is to end of the body. Required for sections that are attachments and ignored otherwise. Must be between -1 and the number of bytes in the body.
Format | File format of attachment. | None or Macbinary. Defaults to None. Required for sections that are attachments and ignored otherwise.


Formatting Free Documents

Documents or files can be migrated even if they are not associated with messages. In the primary file, they appear as standard messages. In the secondary file, the length of the body of the message = 0. The subject for this message is ignored, and the Islast field is set to FALSE. The Document section is next in the secondary file.

It is very important that the file name in the Document section include an extension. If none exists, add an extension that can launch a viewer application. Here is an example of a free document in the secondary file:

Type,Length,Encoding,Islast,Name,Position,Format
Body,0,,FALSE,,,
Document,205,,TRUE,backoffi.txt,0,
Microsoft BackOffice package includes Windows NT Server, Microsoft Exchange Server, SQL Server, and System Management Server.


Formatting Schedule Data

Schedule data is moved to the user's mailbox as an attachment to a new mail message. The user opens the message and imports the data by double-clicking the attachment. You must install Microsoft Schedule+ to import the data.

In the primary file, the schedule data appears to be another message in the message section. In the following example, the third message (in bold) is the schedule message, which is placed in the Inbox.

MAILMESSAGE,PROFS:SANFRAN(HOWARDS)
Folder,Sender,To,Cc,Bcc,Subject,Send-Date,Received-Date,Priority,Unread,Unsent,Body
,Bill Lee,Howard Snyder,,,"End of Month Report",19950321093421,,-1,,,#SALESPO1.SEC(54)
Phoenix Project,Pat Parkes,Howard Snyder,,,Back Office Review,,,,,,#SALESPO1.SEC(161)
,Howard Snyder,Howard Snyder,,,Schedule+,19951005022543,,1,TRUE,,#SALESPO1.SEC(356)

In the secondary file, set the body of the message to a length of 0. The Migration Wizard automatically adds instructions for importing the schedule file in English, German, French, or Japanese, depending on the language of your Microsoft Exchange Server.

Type,Length,Encoding,Islast,Name,Position,Format
Body,0,,FALSE,,,
Schedule,298,,True,HOWARDS.SC2,-1,
SCHEDULE+2 EXPORT VERSION 103
...

The first line in the schedule file must be a header line as follows:

SCHEDULE+2 EXPORT VERSION 103

Each line thereafter has schedule properties and values. The following table describes the differences between the schedule file format and the standard migration file format.

Property | Description
Object | Starts with line that describes type of data (for example: "Projects"), followed by a colon. Next line has open brace ({). Each line thereafter has a property, followed by a colon and the value. Last line of table has close brace (}). Comparable to a header line and row of data in the migration file format.
Object containing an object | An object can contain another object. Within open and close braces of an object, another set of braces can designate another object. For example, recurring appointments can contain exception objects to describe modified or deleted single appointments in the recurring appointment schedule.
Separator | Schedule file format uses a colon instead of a comma to separate schedule property names from values. A colon must be followed by a space.
Space | A space after a colon and before a value are ignored. You can use spaces to make the file more readable.
Line continuation character | Schedule file format uses a backslash (\), followed by a carriage return and line feed, to indicate that the line continues. Lines cannot exceed 80 characters. You can use two line continuation characters to make a line break in appointment or task descriptions.
Quotation mark | Schedule file format encloses all strings and binary data in quotation marks. Quotation marks inside these values are represented by a backslash followed by a quotation mark (\").
Date/Time | Date = mm-dd-yyyy. Time = hh:mm, 24-hour format. You can join date and time with a space: mm-dd-yyyy hh:mm. For example, 9:00 AM on New Years Day = 01-01-1996 09:00. All times and dates are imported in the time zone of user.

Tip To see examples of the schedule file format, create examples in Schedule+ and export the calendar.

The following Schedule+ objects can be created in the schedule file format.

Property | Description
Projects | Table of all projects.
Contacts | Table of contacts.
SingleAppointments | Appointments that occur only once.
SingleEvents | Events that occur only once.
SingleTasks | Tasks that occur only once.
RecurringAppointments | Recurring appointments.
RecurringEvents | Recurring events.
RecurringTasks | Recurring tasks.

Each type of property can occur multiple times within the file. If objects of the same type are kept together, import performance is improved.

SCHEDULE+2 EXPORT VERSION 103
Projects:
{
    data
}
Projects:
{
    data
}
Contacts:
{
    data
}
RecurringAppointments:
{
    data
}
RecurringEvents:
{
    data
}
RecurringTasks:
{
    data
}
SingleAppointments:
{
    data
}
SingleEvents:
{
    data
}
SingleTasks:
{
    data
}

Schedule+ Projects

The following examples illustrate the projects format:

Projects:
{
    Priority:     16945
    Text:     "Colossus Project"
}
Projects:
{
    Priority:     16689
    Text:     "Region 6 Spring Sales Drive"
}

The following table describes the properties of projects.

Property | Description
Priority | Urgency of project.
Text | Description of project.

For more information on priorities, see the Priority Property topic later in this section.

Schedule+ Contacts

Schedule+ contacts are separate from Microsoft Exchange Client PAB entries. There is no link between them. Depending on the configuration of your source system, contacts can be imported into Schedule+ if contact entries are created in the schedule migration file.

You can also create contacts from PAB entries in the source system. Users can delete contacts created this way, but they cannot add information from PAB entries to the contacts list.

The following example illustrates the contact format:

Contacts:
{
    LastName:     "Lee"
    Department:     "MIS"
    AddressBusiness:     "12 Main St"
    CountryBusiness:     "USA"
    PhoneBusiness:     "415 555-9839"
    CityBusiness:     "San Francisco"
    Office:     "16/2102"
    Company:     "Ferguson & Bardell"
    Assistant:     "Sarah"
    ZipCodeBusiness:     "94105"
    CurrentPhone1:     4
    FirstName:     "William"
    StateBusiness:     "CA"
    JobTitle:     "Team Manager"
}

The following table describes the properties of contacts.

Property | Description
AddressBusiness | Business address.
AddressHome | Home address.
Assistant | Assistant of the contact.
CityBusiness | City for the business address.
CityHome | City for the home address.
Company | Company.
CountryBusiness | Country for the business address.
CountryHome | Country for the home address.
Department | Department.
FirstName | First name.
JobTitle | Job title.
LastName | Last name.
Notes | Miscellaneous information.
Office | Office location.
PhoneAssistant | Phone number of the contact's assistant.
PhoneBusiness | Business phone number.
PhoneBusiness2 | Second business phone number.
PhoneFax | Fax phone number.
PhoneHome | Home phone number.
PhoneHome2 | Second home phone number.
PhoneMobile | Mobile phone number.
PhonePager | Pager phone number.
Spouse | Name of the contact's spouse.
StateBusiness | State/province of business address.
StateHome | State/province of home address.
User1 | User-defined string for contact information that doesn't fit any other field.
User2 | User-defined string for contact information that doesn't fit any other field.
User3 | User-defined string for contact information that doesn't fit any other field.
User4 | User-defined string for contact information that doesn't fit any other field.
ZipCodeBusiness | Business address postal code.
ZipCodeHome | Home address postal code.

Schedule+ SingleAppointments

If attendees are invited to a migrated appointment, put their names into the Notes or Text property of the appointment. To make it easier for the user to send mail to the attendees or to add the attendees to the attendees list, use a semicolon to separate the names. The user can then copy the list of names into the To line of a message or to the attendees list and resolve them against the Address Book.

Schedule+ appointments can list outside attendees. Their unique MAPI identifier is stored with the appointment and is used to verify responses to meeting requests. Without an attendee's MAPI identifier, the display name cannot be added to the attendees list.

The following example illustrates the SingleAppointment format:

SingleAppointments:
{
    Ring:     T
    AlarmAmount:     15
    Text:     "Attend training class."
    AlarmTypeUnit:     0
    AlarmAmountOriginal:     15
    BusyType:     0
    Start:     3-5-1996 15:00
    End:     3-5-1996 17:00
}
SingleAppointments:
{
    Where:     "Rona's office"
    Text:     "Meet with Rona about shifting contacts to new employees.\
\
Rona Rumalski"
    Ring:     T
    AlarmAmount:     15
    Start:     3-5-1996 09:00
    BusyType:     1
    End:     3-5-1996 10:30
    AlarmTypeUnit:     0
}

The following table describes the properties of SingleAppointments.

Property | Values | Description
AlarmAmount | Integer | Amount of time before meeting date to issue alarm.
AlarmTypeUnit | 0 = Minute 1 = Hour 2 = Day 3 = Week 4 = Month | Type of unit for AlarmAmount.
BeforeEnd | T or F Default = F | Alarm is set relative to end rather than to start of SingleAppointment.
BusyType | 0 = Tentative 1 = Busy | If SingleAppointment should appear busy or tentative.
End | Required. mm-dd-yyyy hh:mm | End date and time for SingleAppointment.
IsRecurringInstance | T or F Default = F | If SingleAppointment is instance of recurring series.
Notes |  | Miscellaneous information. Text appears in Notes property page for appointment.
Ring | T or F Default = T | If alarm was set for SingleAppointment.
Start | Required. mm-dd-yyyy hh:mm | Start date and time for SingleAppointment.
Text |  | Description for SingleAppointment. Text appears on calendar.
Where |  | Location for appointment.

Schedule+ SingleEvents

Events are different from appointments in the following ways:

  • Events appear above the day's calendar.
  • Events do not have attendees.
  • Alarms for events are based on midnight.

The following example illustrates the SingleEvents format:

SingleEvents:
{
    Ring:     T
    AlarmAmount:     2
    Text:     "River City 10 mile hike and camp. (Weather permitting.)\
Call Josh at 555-1232 to make sure it is happening."
    AlarmTypeUnit:     2
    AlarmAmount:     2
    StartDate:     3-2-1996
    EndDate:     3-3-1996
}

The following table describes the properties of SingleEvents:

Property | Values | Description
AlarmAmount | Integer | Amount of time before midnight to issue alarm.
AlarmTypeUnit | 0 = Minute 1 = Hour 2 = Day 3 = Week 4 = Month | Type of unit for AlarmAmount.
BusyType | 0 = Tentative 1 = Busy | If event should appear busy or tentative.
EndDate | Required. mm-dd-yyyy | End date for event.
IsRecurringInstance | T or F Default = F | Indicates if event is instance of recurring series.
Notes |  | Miscellaneous information.
Ring | T or F Default = T | If alarm was set to ring for event.
StartDate | Required. mm-dd-yyyy hh:mm | Start date for event.
Text | String | Text (description) for event.

Schedule+ SingleTasks

Schedule+ relates tasks to projects by using the ProjectID number. Without a ProjectID number, tasks are imported without being related to a project.

The following example illustrates the SingleTask format:

SingleTasks:
{
    Priority:     16672
    Text:     "Update summer catalog."
    AmountActualEffort:     0
    AmountEstimatedEffort:     1
    IsTaskAutoDone:     T
    StartDate:     3-6-1996
    AmountStartWork:     4
    TypeUnitStartWork:     2
    EndDate:     3-10-1996
    TypeUnitEstimatedEffort:     2
    TypeUnitActualEffort:     2
}

The following table describes the properties of SingleTasks.

Property | Values | Description
AmountActualEffort | Number | Amount of time of actual effort, in units set by TypeUnitActualEffort.
TypeUnitActualEffort | 0 = Minute 1 = Hour 2 = Day 3 = Week 4 = Month | Type of unit for measuring actual effort for task.
AmountEstimatedEffort | Number | Amount of estimated time effort, in units set by TypeUnitEstimatedEffort.
TypeUnitEstimatedEffort | 0 = Minute 1 = Hour 2 = Day 3 = Week 4 = Month | Type of unit for measuring estimated effort for task.
AmountStartWork | Number | Amount of time before end date to start work on item, in units set by TypeUnitStartWork.
TypeUnitStartWork | 0 = Minute 1 = Hour 2 = Day 3 = Week 4 = Month | Type of unit for amount of time before end date to start work.
Billing | String | Billing information.
CompletedDate | mm-dd-yyyy | Date task was completed.
StartDate | mm-dd-yyyy | Date task starts.
EndDate | mm-dd-yyyy | Date task ends.
IsTaskAutoDone | T or F | If task should appear as automatically completed on end date.
Mileage | String | Mileage associated with task.
PercentCompleted | Number | Percentage of task completed.
Priority | See the following explanation. | Priority of task.

Priority Property

Schedule+ prioritizes tasks by using numbers (1 through 9) and/or letters (A through Z). For example, "A1," " 3," and "B" are valid priorities. The migration file format converts this priority to a decimal.

The following table illustrates how priorities are converted to decimal versions. The ASCII value of the letter or number is converted to a hexadecimal, the number 20 is prefixed or appended as a space and place holder, and this number is converted to a decimal.

Priority | Convert to Hexadecimal | Prefix or Append 20 | Convert to Decimal
1 | 31 | 2031 | 8241
2 | 32 | 2032 | 8242
3 | 33 | 2033 | 8243
4 | 34 | 2034 | 8244
5 | 35 | 2035 | 8245
6 | 36 | 2036 | 8246
7 | 37 | 2037 | 8247
8 | 38 | 2038 | 8248
9 | 39 | 2039 | 8249
A | 41 | 4120 | 16672
B | 42 | 4220 | 16928
C | 43 | 4320 | 17184
D | 44 | 4420 | 17440
E | 45 | 4520 | 17696
F | 46 | 4620 | 17952
G | 47 | 4720 | 18208
H | 48 | 4820 | 18464
I | 49 | 4920 | 18720
J | 4A | 4A20 | 18976
K | 4B | 4B20 | 19232
L | 4C | 4C20 | 19488
M | 4D | 4D20 | 19744
N | 4E | 4E20 | 20000
O | 4F | 4F20 | 20256
P | 50 | 5020 | 20512
Q | 51 | 5120 | 20768
R | 52 | 5220 | 21024
S | 53 | 5320 | 21280
T | 54 | 5420 | 21536
U | 55 | 5520 | 21792
V | 56 | 5620 | 22048
W | 57 | 5720 | 22304
X | 58 | 5820 | 22560
Y | 59 | 5920 | 22816
Z | 5A | 5A20 | 23072

For a number priority of 3, for example, use the hexadecimal 33 and prefix 20. The value 2033 converts to decimal 8243. For a letter priority of C, for example, take the hexadecimal 43, and append 20. The value 4320 converts to 17184.

If your existing system prioritizes by requiring both letters and numbers (for example: A1, B3, or Z9), use this procedure. Convert both to hexadecimal, concatenate (link together) the values of the letter and number, and then convert that value to decimal. For a priority of A3, for example, use the hexadecimal of A (41) and concatenate it with the hexadecimal of 3 (33). The value 4133 converts to 16691.

Schedule+ Recurring Appointments, Events, and Tasks

The following examples illustrate the format for recurring appointments, events, and tasks:

RecurringEvents:
{
    Text:     "Yearly tax audit. Start preparations early."
    Ring:     T
    AlarmAmount:     21
    AlarmTypeUnit:     2
    StartDate:     3-4-1996
    EndDate:     3-4-1996
    RecurringType:     7
    YearInterval:     1
    DayOfMonthMask:     8
    MonthOfYearMask:     4
}
RecurringAppointments:
{
    Text:     "SATR meeting.\
\
Big Sale."
    Ring:     T
    AlarmAmount:     15
    DayOfWeekStart:     0
    StartRecurringTime:     12:00
    YearInterval:     1
    WeekInterval:     1
    BusyType:     0
    RecurringType:     51
    StartRecurringDate:     2-26-1996
    DayOfWeekMask:     32
    EndRecurringDate:     3-4-2000
    DayOfMonthMask:     8
    EndRecurringTime:     13:00
    MonthOfYearMask:     4
    AlarmTypeUnit:     0
}
RecurringTasks:
{
    Text:     "Check online mailbox for new mail."
    Priority:     8243
    TypeUnitActualEffort:     2
    AmountEstimatedEffort:     1
    TypeUnitEstimatedEffort:     2
    Billing:     "Billed at higher rate"
    BeforeEndOriginal:     F
    AmountStartWork:     0
    StartRecurringDate:     3-2-1996
    RecurringType:     64
    WeekInterval:     1
    DayOfWeekMask:     16
    DayOfWeekStart:     0
    DayInterval:     1
    EndRecurringDate:     8-10-1996
    TypeUnitStartWork:     2
    Ring:     T
    AlarmAmount:     0
    AlarmTypeUnit:     2
    BeforeEnd:     F
    Exceptions:
    {
        InstanceDate:     3-3-1996
        StartDate: 3-3-1996
        EndDate:     3-4-1996
        Deleted:     F
        Text: "Check online mailbox for new mail. Check for new rates."
        Priority:     8241
        TypeUnitActualEffort:     2
        AmountEstimatedEffort:     1
        TypeUnitEstimatedEffort:     2
        BeforeEndOriginal:     F
        AmountStartWork:     0
        TypeUnitStartWork:     2
        Ring:     T
        AlarmAmount:     5
        AlarmTypeUnit:     2
        BeforeEnd:     F
    }
}

The following table describes the properties shared by recurring appointments, events, and tasks.

Property | Values | Description
DayInterval | 1 through 999 | Number of days between instances. Used only if RecurringType is 64.
DayOfMonthMask | 1st day of month = bit 0 31st day of month = bit 30 | Bit field indicating which days of the month are valid for recurrence pattern. Used only if RecurringType is 7 or 12.
DayOfWeekMask | Sunday = bit 0 Saturday = bit 6 | Bit field indicating which days of the week are valid for recurrence pattern. Used only if RecurringType is 48, 51, or 56.
DayOfWeekStart | 0 through 6 Sunday = 0 | Start of week preference. Used only if RecurringType is 48. For recalculating biweekly meetings.
EndRecurringDate | mm-dd-yyyy | End date for recurrence pattern.
EndRecurringTime | Required. hh:mm | End time for a recurring item.
Exceptions | See Exceptions Property topic later in this section. | Exceptions to a recurring item.
FirstRecurringAlarmDate | Today's date in mm-dd-yyyy format. | First recurring item with alarm. Recalculated during import into Schedule+.
MonthInterval | 1 through 99 | Interval between months for recurrence pattern. Used only if RecurringType is 12 or 56.
MonthOfYearMask | January = bit 0 December = bit 11 | Bit field indicating which months of year are valid for recurrence pattern. Used only if RecurringType is 7 or 51.
RecurringType | Required. 7 = Yearly on specific day 12 = Monthly on specific day 48 = Weekly 51 = Yearly on a pattern 56 = Monthly on a pattern 64 = Daily | Type of recurrence pattern.
StartRecurringDate | Required. mm-dd-yyyy | Start date for recurrence pattern.
StartRecurringTime | Required. hh:mm | Start time for recurring item.
WeekInterval | Positive integer | Interval between weeks for recurrence pattern. Used only if RecurringType is 48, 51, or 56.
YearInterval | Positive integer | Interval between years for recurrence pattern. Used only if RecurringType is 7.

The following table describes additional values required for the RecurringType property.

RecurringType | Required values
7 = Yearly on specific day | DayOfMonthMask, MonthOfYearMask, YearInterval
12 = Monthly on specific day | DayOfMonthMask, MonthInterval
48 = Weekly | DayOfWeekMask, DayOfWeekStart, WeekInterval
51 = Yearly on a pattern | DayOfWeekMask, MonthOfYearMask, WeekInterval
56 = Monthly on a pattern | DayOfWeekMask, MonthInterval, WeekInterval
64 = Daily | DayInterval

Exceptions Property

Exceptions are deleted or modified properties of a recurring appointment or task. To delete, only two properties are required: Deleted and InstanceDate. To modify, the appointment or task must be redefined as a single appointment or task, and you must redefine the StartDate and EndDate, even if only the Location property is modified.

Property | Values | Description
Deleted | T or F | If instance was marked "deleted." If FALSE, instance has been modified.
InstanceDate | mm-dd-yyyy | Date that original instance would have occurred.


A

access control list (ACL)
A list that is used by a Microsoft Exchange Server information store to controls access to its objects. Most information store objects — including servers, sites, containers, mailboxes, and folders as represented within the information store — can have an associated ACL that lists members and their associated security privileges. Each member of an ACL is one of four entities: a user from the Microsoft Exchange Server address book, a distribution list (DL) from a Microsoft Exchange Server address book, a public folder, or a defined role with a set of privileges such as Administrator or Default. For more information, see About Access Control Lists.
ACL
See access control list.
ACL object
Any object for which a user can have access rights, including a server, a site, a container, a mailbox, or a public folder.
Active Messaging Library
An Automation programming interface used primarily by Visual Basic and Visual C/C++ messaging client developers. Active Messaging Library provides programmable objects for messages, folders, recipient addresses, and other messaging components.
add-in application
A Microsoft Exchange Server application that does not communicate by means of a mailbox.
address book
A subset of the Microsoft Exchange Server directory that includes mailboxes, custom recipients, distribution lists, and public folders. It is available to users so they can access information about the organization as they would in a printed directory. The address book can contain one or more address lists. See also global address list, personal address book.
address space
The address information for a mail connector or gateway that identifies the type of messages handled by that connector or gateway. Address spaces are typically a subset of a complete address — they contain only the elements necessary to identify the route that a message should take.
address template
A component of an Addr-Type object. The address template consists of the controls for a dialog box that allows administrators to enter a new custom address. Using the custom address template is not required for running a gateway. However, it provides a friendly interface that the administrator can use to create custom recipients for the foreign system.

addressable object class
A class of objects that share a common set of attributes and behaviors and that can be addressed as such. Object classes derived from other object classes inherit all the attributes of the original object class. The directory schema consists of addressable object classes, as well as directory objects.
Administrator extension
An extension to the Microsoft Exchange Server Administrator program that adds one or more custom property pages to the property sheet of an object. These new property pages are implemented through an Administrator extension DLL.
Administrator extension DLL
A DLL (dynamic link library) used to control property pages that display extension data.
Administrator program
See Microsoft Exchange Server Administrator program.
Administration Management Domain (ADMD)
A message transfer system (usually a large public carrier, such as AT&T and MCI).
agent
Within ICS, the process that pairs a synchronizer to a collector and manages the synchronization process.
ambiguous name resolution (ANR)
Resolution of a partial user display name to a name that actually exists in the global address book.
applications program interface (API)
A set of functions used to manipulate an object or set of objects.
attribute
A piece of data that stores information that is specific to an object. A set of attributes store the data that define an object. An attribute of a MAPI object is called a property.
AutoAssistant
A user-interface option that is used to create rules for managing and organizing information. The Inbox Assistant is used to create rules that automatically filter incoming mail and take a variety of actions such as moving messages to a particular folder, forwarding messages to another user, or automatically deleting mail. The Out of Office Assistant is used to respond to e-mail when the user is out of the office.
Automation
The Automation interface (formerly known as OLE Automation) allows you to create and manipulate Schedule+ objects.


B

backboning (backbone)
The process used to transmit messages between two Microsoft Exchange Server systems through a foreign system. The foreign system is called the backbone. Backboning can also provide connections between different Microsoft Exchange Server organizations.
bulk operation
An operation that is performed simultaneously on multiple objects with optional line-by-line control. Batch import and export operations are two examples of bulk operations.


C

client application
An application that employs Microsoft Exchange Server services, offers no services of its own, and is associated with one or more users. A client application may reside on a server or on a user’s computer.
client extension
Functionality that is added to the basic Microsoft Exchange Client as an alternative to developing a stand-alone client application. A client extension usually takes the form of an added menu item or button.
collector
Within ICS, a set of methods that imports changes into an information store.
common messaging calls (CMC)
An alternative to MAPI calls for messaging. CMC is a cross-platform messaging function set that enables client applications to be independent of the actual messaging system, operating system, or hardware used.
connector
A software service that allows users at one Microsoft Exchange Server site to connect to users at other Microsoft Exchange Server sites using specific protocols such as X.400, SMTP, and Microsoft Mail. Microsoft Exchange Server includes an Internet connector, a Site Connector for linking two Microsoft Exchange Server sites, and a RAS connector. A connector can perform all the functions of a gateway. See also backboning (backbone).
container
An object in the Microsoft Exchange Server directory whose main purpose is to hold other objects. Container objects simplify the directory information tree (DIT) structure and avoid name collisions by grouping various objects under different containers.
custom recipient
An address book entry that represents a recipient from a foreign system. A custom recipient is created by the user of a client application with a template supplied by the address book provider. The address of a custom recipient is also referred to as a one-off address.


D

deferred action
The deferral of an action when a rule is applied because a resource (typically the client) is unavailable. Deferred action processing consists of collecting and storing these actions until the resource becomes available, at which time the action is performed.
deferred action message (DAM)
A message that indicates an action has been requested by a rule, but the action cannot be performed because the resource (usually the client) is not available. This message is received by the affected resource when it becomes available. Reception of the message triggers the action that was deferred.
delegate access
Access to another user’s mailbox that is assigned by the owner of the mailbox. Delegate access can be of several types, such as create and send messages or read-only.
delivery report (DR)
A report sent to the originator of a message when the message is successfully delivered to one of its intended recipients.
directory
A Microsoft Exchange Server component that serves as the central repository of user information and Microsoft Exchange Server information for an organization. The directory for Microsoft Exchange Server consists of the directory information tree (DIT) and the directory schema.
directory access functions
A set of functions included with the Microsoft Exchange Server SDK that are used to manage information in the directory. Directory access functions are typically used for managing objects when creating and maintaining custom add-on services, managing a large number of directory objects at one time, synchronizing Microsoft Exchange Server directory objects with other directory services, and automatically updating Windows NT user accounts as directory objects are updated.
directory exchange agent (DXA)
A Microsoft Exchange Server component that handles the transfer of directory information between the Microsoft Exchange Server directory and foreign mail systems such as Microsoft Mail 3.2 post offices. It also maintains synchronization between these objects.
directory information tree (DIT)
A graphical display of an organization’s directory structure, sites, and servers, shown as a branching structure. The top-level (root) directory usually represents the organization level.
directory replication
The copying of a master set of directories from an export server to specified servers in the same or other domains. Replication simplifies the task of maintaining identical sets of directories and files on multiple computers because only a single master copy of the data must be maintained.
directory schema
The description of all object classes and objects within a directory, along with their attributes and inheritance structure. A Help file containing all the descriptions in the schema is included with the SDK.
directory service agent (DSA)
A Microsoft Exchange Server component that handles the storage, maintenance, replication, and routing of addressing and other information.
directory synchronization
An automatic process of directory replication between Microsoft Exchange Server and a foreign system that is executed on a regular basis by the directory exchange agent (DXA) for a Microsoft Exchange Server organization. Directory synchronization allows the two systems to keep all copies of the directory identical. Synchronization between Microsoft Exchange Server sites and foreign mail systems can be performed using an application such as the DIRSYNC sample application.
discretionary access control list (DACL)
A list used by the Microsoft Exchange Server directory to control access to its objects. A DACL consists of a list of security identifiers (which identify users) and specific permissions for each.
display name
The name of an object as it appears in the address book. For example, the Display-Name (an attribute in the Microsoft Exchange Server directory) of a recipient-class object is constructed of the strings Given-Name and Surname.
distinguished name (DN)
The combination of an object’s name and its entire path. Each distinguished name is unique. A DN allows users and applications to access objects without knowing their physical location.
distribution list (DL)
A MAPI address book object that represents a set of individual recipients addressed as a group and that implements the IDistList interface. Distribution lists can contain other distribution lists and individual recipients. A distribution list is one of two types of MAPI address book objects: either an object that can receive messages or a mail user object.
DLL (dynamic link library)
A library of functions that uses dynamic linking. This allows an executable module to include only the information needed at run time to locate the executable code for a DLL function. Dynamic linking can be either load-time linking, causing the inclusion of the DLL code at load time, or run-time loading, causing its loading only when actually called by using the Windows LoadLibrary and GetProcAddress functions to get the starting address of a DLL function.


E

embedded object
One object that is included in a second object. An object embedded in a Microsoft Exchange Server message and represented as an icon is called an attachment.
event log
A file that records any significant occurrences in the system or in an application.
extension data
Data with fields other than the standard configuration data provided by the Microsoft Exchange Server Administrator program that are stored by a directory object. One extension-data attribute can contain a number of extension-data fields of varying data types. Extension data is commonly used when an application must expose information that is outside the application’s schema.
EX
The address type for native Microsoft Exchange Server addresses.


F

Favorites folder
A user-customized folder in the public information store that contains links to public folders for quick access. The Favorites folder is also used for synchronization with offline folders and as a means to provide an unread count on public folders. See also About the Favorites Folder.
Find window
A dialog box accessible from the Microsoft Exchange Client user interface that allows users to search for a specific text string or other message attributes in message properties.
folder
A MAPI object in an information store that is accessible for sharing. Folders can contain objects such as messages, files, and other folders.
folder hierarchy
Tree of public folders, private folders, and messages in the information store.
folder replication
foreign address
The address of an object in a foreign system, which is any mail system that is not a Microsoft Exchange Server system.
form
A MAPI object that is used to display a message of a particular message class in a structured format based on MAPI properties. User interaction with the form is controlled with a form server application. MAPI form objects implement the IMAPIForm and IMAPIFormInfo interfaces.
form manager
A MAPI service provider implemented as a DLL that manages form libraries using the IMAPIFormMgr interface.
form server
An application that manages a user’s interaction with a form, such as responding to menu commands.


G

gateway
A software service that allows Microsoft Exchange Server users to communicate with other mail systems, such as IBM PROFS. Gateways are used to send messages between two Microsoft Exchange Server sites through an intermediate mail system using a process called backboning, but do not support directory replication.
global address list
The directory of all Microsoft Exchange users and distribution lists (DLs) to whom messages can be addressed. The administrator creates and maintains this list. The global address list may also contain public folder names. Entries from this list can be added to a user’s personal address book.
globally unique identifier (GUID)
A Microsoft implementation of the DCE UUID. UUIDs uniquely identify objects, such as interfaces, manager entry-point vectors, and client objects. The RPC run-time libraries use UUIDs to check for compatibility between clients and servers and to select among multiple implementations of an interface.
GUID
See globally unique identifier.


I

incremental change synchronization (ICS)
A mechanism to monitor, export, and import changed items (both hierarchy and content) between a database and an information store or between two information stores. ICS is used within Microsoft Exchange Server for local replication and for backup of information store data. The collector and synchronizer that ship with Microsoft Exchange Server can be used to provide customized incremental change synchronization, using an external agent.
information store
The default message store provider for Microsoft Exchange Server. The information store consists of three implementations of MAPI message stores: the public information store, the private information store, and the personal folder store (PST). The information store organization of public folders, private folders, and messages is referred to as the organization hierarchy. Another implementation of a MAPI message store is configured when a user works offline. It is called the offline folder store (OST) and mirrors the structure of the mailbox while offline.


K

key
A string that is used to digitally sign and encrypt data. Each mailbox has two key pairs. One key pair is used for signing and verifying operations, the other pair is used for encrypting and decrypting operations. Each key pair consists of a public key which is publicly known, and a private key which is known only to the key’s user.


L

leaf object
An object in the Microsoft Exchange Server directory that is not capable of containing other objects.
least-cost routing
The assignment of costs to communication lines, so that the associated message transfer agent (MTA) intelligently routes information over the line with the lowest cost. This capability works closely with the load-balancing feature.
Lightweight Directory Access Protocol (LDAP)
An on-the-wire protocol used to perform directory operations such as read, search, add, and remove.
Lightweight Remote Procedure Call (LRPC)
An OLE method for implementing an RPC, which changes the objects semantics to apartment model threading.
list server
An application that processes lists of items, such as addresses, recipients, or objects. For example, a list server can gather a list of topics from users, receive a list of messages that apply to a specific topic, and distribute these to a list of other users who have expressed an interest.
load balancing
The use of multiple communication lines for re-routing traffic to less busy lines, which improves the overall efficiency of information routing through the organization.
local replication
The ability to synchronize directories between the user’s computer and the network copies. This allows users to work offline with public folders and mailboxes. See also offline folders.


M

mailbox
The delivery location for all incoming mail messages addressed to a designated owner. Information in a user’s mailbox is stored in the private information store on a Microsoft Exchange Server computer. A mailbox can contain received messages, message attachments, folders, folder hierarchy, and more. Server applications for Microsoft Exchange Server are often designed with a mailbox for communication.
mailbox agent
Any Microsoft Exchange Server application that uses a mailbox as its interface and performs functions for specific mailboxes. Mailbox agents are one of the chief types of server applications, with gateways being the other.
MAPI
The Messaging Application Programming Interface (MAPI) is a medium-independent messaging architecture that enables multiple applications to interact with multiple systems across a variety of hardware platforms. As a client interface component, MAPI is the complete set of functions and object-oriented interfaces that forms the foundation for the MAPI subsystem’s client application and service provider interfaces.
MAPI address book
An object consisting of an information tree and a service agent that provides routing information and keeps track of the addresses and attributes of objects within the hierarchy. The MAPI address book is the basis for the Microsoft Exchange Server directory.
MAPI idle engine
A set of functions that improves performance by making efficient use of idle time. An application uses the MAPI idle engine for tasks that are less time-critical by deferring them until the processor is idle. A callback function is created that executes when called by the MAPI idle engine.
MAPI notification
A system of communication implemented by MAPI and used by Microsoft Exchange Server. One object registers to learn of a change or error (called an event) that may take place in the other object. After the event occurs, the first object is notified. The object receiving notification is called the advise sink. The object responsible for the notification is called the advise source.
MAPI service provider
A set of functions that connect MAPI client applications to an underlying message system. Microsoft Exchange Server (like most messaging systems) includes three types of services: message store, address book or directory, and message transport. MAPI supports each provider independently, allowing a vendor to offer one or more custom service providers.
MAPI session
A connection with a MAPI subsystem that must be established before a client application can call the underlying messaging system.
MAPI spooler
A MAPI process that handles the sending and receiving of messages between client applications and most messaging systems. A tightly coupled information store and transport provider does not use the spooler. See also client application.
marshal
The act of passing the function calls and parameters of an OLE object across process boundaries.
message body
See message text.
message content
The collection of all parts of a message that are not headers or footers, including the message text and attachments.
message store viewer
A MAPI client application that provides a view of a message and its attachments. The message store viewer displays a message or any other object in the exact format to be used in an application, showing it as a set of properties and a collection of calls that can be performed on the object.
message text
The main portion of the message content, typically displayed to each recipient as an immediate result of opening the message. It excludes any attachment objects. Also referred to as the message body.
message transfer agent (MTA)
A component of Microsoft Exchange Server that provides the engine for sending messages and distributing information between Microsoft Exchange Server systems or between Microsoft Exchange Server and a foreign system. Each MTA is associated with one information store. It is accessed using MAPI calls only and has no direct programmer interface with Microsoft Exchange Server. The MTA conforms to the 1988 X.400 specification.
message transfer envelope
The set of addressing, routing, and network protocol information that surrounds a message as it is transported across Microsoft Exchange Server.
messaging user object
A MAPI object that describes an individual recipient of a message. Messaging user objects implement the IMailUser interface, which inherits from the IMAPIProp interface.
Microsoft Exchange Server
The correct term to used when referring to both the Microsoft Exchange Server system and its server component.
Microsoft Exchange Server Administrator program
A graphical interface that is used for configuring and maintaining the sites and servers of an organization from a single location.


N

name space
A hierarchy of values that comprises an X.400 Originator/Recipient Name used for a Microsoft Exchange message address. This hierarchy contains address information including country, organization, common name, and personal name.
named pipe
An interprocess communication mechanism that allows one process to communicate with another local or remote process.
naming context
In the Microsoft Exchange Server DIT, a subtree that starts at one object (the naming context master object) and is bounded by leaf objects or the start of another naming context. Naming contexts affect both inheritance of permissions within the DIT and replication of directory information.
naming context master object
A object that defines the boundaries of a naming context in the Microsoft Exchange Server DIT. The four types of naming contexts are designated NC1, NC2, NC3, and NC4. See Inheritance of Permissions.
nondelivery report (NDR)
A report sent to the originator of a message to indicate that the message could not be delivered to one or more of its intended recipients.


O

object
Microsoft Exchange Server objects are instances of MAPI objects. 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. A MAPI interface can only be instantiated through an inherited class.

Every type of MAPI object is inherited from an interface that is ultimately inherited from the IUnknown interface.

object identifier (OID)
A value specifying the nature of an X.400 object. OIDs are used by MAPI for various purposes, such as indicating the types of attached files.
offline folders
A feature of Microsoft Exchange Server that makes public folders and mailbox folders available to users when they are offline. Folders configured for offline availability are stored in an OST file on the user’s disk. When users log on to their home server and the network connection is reestablished, Microsoft Exchange Server automatically propagates changes that have been made to the offline copy to the copy on the server.
offline folder store (OST)
An information store that is used to store folder information that can be accessed offline. An OST is similar to a PST except that it is RTF aware, while a PST is not.
one-off address
Address of a foreign system as expressed by an address template.
organization
A collection of servers, grouped into sites, that are linked together to provide workgroup connectivity, information, and messaging services. The organization is the highest level object in the directory information tree (DIT).
organization forms library
A programming interface that stores electronic forms for use by an entire organization. The forms library architecture is defined by MAPI. It functions independently of any specific forms technology and can store forms from multiple forms-development environments. It resides in the public information store as a hidden public folder and is replicated throughout the organization for user access to forms.


P

PAB
See personal address book (PAB).
partial e-mail address
See site proxy address.
Performance Monitor
See Windows NT Performance Monitor.
permission
A rule associated with an object (usually a directory object) that regulates which users have access to the object and in what manner. Rules associated with the system as a whole are called rights.
personal address book (PAB)
A list of recipients created and maintained by an individual user for personal use. The personal address book is a subset of the global address list.
personal folder
A folder used to store an individual’s personal information, such as incoming mail messages and local documents.
personal folder store (PST)
An information store at the client used to store an individual’s personal folders if directed to do so by a rule. PSTs are often used so that messages will be accessible while the user is offline.
private information store
The MAPI message store implementation (part of the Microsoft Exchange Server information store) that stores mailboxes for users. While the public information store contains information to be shared between users, the private information store contains information to be secured from other users.
privileged service
A service that is allowed privileges usually reserved for administrators. To establish the service, the MAPI profile must already have these rights.
profile
A file containing essential information used by the Microsoft Exchange Client, which includes the location of a recipient's Inbox, Outbox, address lists, information stores, and other information services.
property
An attribute common to all instances of a MAPI object type. Examples of mailbox object properties are owner name and out-of-office state. MAPI properties are included as part of the message objects or other objects they describe, and they derive from the IMAPIProp interface. Each property is a structure that consists of identifier, data type, and value.
property page
A dialog box that displays configuration information to the user and enables the user to modify the information. One or more property pages makes up a property sheet.
property sheet
A dialog box that displays configuration information to the user and enables the user to modify the information. A property sheet is composed of one or more property pages.
proxy address
The Microsoft Exchange Server address for an object that resides in a different mail system. This address is used by the gateway to deliver mail from a foreign system to a recipient on the Microsoft Exchange Server system. In the Microsoft Exchange Server Administrator program, these addresses are called e-mail addresses.
pseudo-attribute
Attributes that are not part of the Microsoft Exchange Server directory schema and that exist alongside the directory schema attributes to provide additional functionality. Pseudo-attributes are available for use only by directory access functions.
public folder
A folder located on Microsoft Exchange Server computers that facilitates the exchange of all types of information between groups of people in an organization.
public information store
The MAPI message store implementation (part of the Microsoft Exchange Server information store) that stores public folders. While the private information store contains information to be secured from other users, the public information store contains information to be shared between users.


R

raw mode
An import mode or display mode where lines are expressed literally. No properties are inherited or constructed. Aliases for property and class names are not recognized.
RDN
See relative distinguished name (RDN).
recipient
An object in the directory that can receive messages and information. Microsoft Exchange Server recipients are mailboxes, distribution lists (DLs), public folders, and custom recipients.
relative distinguished name (RDN)
The name of an object within its current level in the directory hierarchy. For example, from its own mailbox, “v-rossl” is the RDN of the v-rossl mailbox object, while its distinguished name (DN) might be O=Trager /CN=Boston /CN=recipients /CN=v-rossl.
remote access service (RAS)
The Windows NT Server capability that lets users at remote locations work as if connected directly to a computer network, accessing one or more RAS servers.
remote address
The address for a recipient in the format of the mail system used by that individual.
remote procedure call (RPC)
A message-passing facility that is independent of the underlying network and allows a distributed application to call services available on various computers in a network. Microsoft Exchange Server uses RPC for client-server communications.
replication
See directory replication.
resolution
The conversion of a message-class name into a class identifier to locate the code that handles the message class.
rights
The rules that control access that are associated with the system as a whole and that can be granted to local groups, global groups, and individual users. Rules that control access and are associated with individual objects are called permissions.
role
A predetermined set of permissions that defines the access of a user or group to an object. Microsoft Exchange Server provides several default roles for directory access. Administrators can define custom roles to suit the needs of the site or organization.
routing table
A table that defines how information should be routed between message transfer agents (MTAs) in an organization.
RPC
See remote procedure call (RPC).
RTF-Aware
An information store is known as RTF-aware if it keeps the body and the RTF text of a message synchronized. The server-based information store and the offline folder store (OST) are RTF-aware. The personal folder store (PST) is not RTF-aware. See also About Information Store Client and Server Components.
rule
A feature of Microsoft Exchange Server that filters incoming mail and takes specified actions, such as moving it to a particular folder, forwarding it to another user, or deleting certain types of information. Also refers to administrative policies associated with the system as a whole or with individual objects such as public folders or mailboxes. See also permission, rights.
rule table
A table with each position defined that contains all the rules applied to a folder.


S

schema
See directory schema.
security identifier (SID)
A unique name that identifies a user logged on to the Windows NT security system. A security identifier can identify an individual user or a group of users.
server
A computer that provides shared resources to network users.
server application
An application written to run as a service of Windows NT Server on Microsoft Exchange Server. These applications are usually gateways, add-ins, or mailbox agents.
service
The services of Microsoft Exchange Server include the information store, the directory service, the message transfer agent (MTA), and the directory exchange agent (DXA). New services are also provided by new applications.
service provider
A component that allows client applications to use the services of the messaging system. A service provider typically offers address book, form management, message store, or transport services.
service control manager
A Windows NT Server process that manages all the services in the Windows NT Registry. See the Win32 Programmer’s Reference.
site
One or more Microsoft Exchange Server servers that provide services to a set of users. Sites can be centrally managed and can span physical locations.
site proxy address
The portion of a proxy address that corresponds to the site rather than to an individual user. For example, @trager.com might be the site proxy address for the Trager company.
Simple Mail Transfer Protocol (SMTP)
The messaging standard used by the Internet to transfer mail.
SMTP address
An address within a foreign system whose type is SMTP.
source extractor
A program that reads directory, information store, or scheduling information from a foreign system and writes it into an intermediate file format (or into memory) so that it can be imported into a database of Microsoft Exchange Server.
synchronizer
Within ICS, a set of methods that export changes from an information store. See IExchangeExportChanges.
synchronization
See directory synchronization and incremental change synchronization.
synchronization state
A list of the hierarchy and content changes exported from and imported to a public folder. Using the synchronization state, the synchronizer can send any necessary delete requests for, and prevent duplicate exports of already exported data. This mechanism also lets the information store track imported data to prevent duplicate imports and re-exporting of imports. The developer of the synchronization system must choose a format for storing synchronization state information designed for use by both the collector and the synchronizer. The synchronization state should be supported through the Win32 IStream interface.


T

template object
See address template.
tombstone
An object with the Is-Deleted attribute set that remains in the Microsoft Exchange Server for a set period of time. See also Exporting and Importing Changed Objects.
Transport-Neutral Encapsulation Format (TNEF)
A standard method defined by MAPI of passing textual and binary message data. The method involves wrapping unsupported MAPI properties in a binary attachment file that accompanies a message through the transport and decoding the file on the receiving side to reconstitute the MAPI properties.


U

Unicode
A worldwide character-encoding standard that allows more information to be contained in each string by defining 16-byte character strings rather than the standard 8-byte character strings. Unicode allows universal data exchange and improves multilingual text processing. Unicode strings are also called wide strings. A Unicode string is left-padded with zeroes.
update sequence number (USN)
A property that monitors changes in directory objects as they occur. USNs are used in export operations from a specified server so that only the changed objects will be exported. Only those objects with a USN larger than the largest USN returned during a previous export are exported. USNs are server-specific.
Universal Naming Convention (UNC)
A standard naming convention for applications that enables users to browse documents on the network directly and to open an application’s files on remote machines without requiring the user to specify the location of the file on the network or connect to that network. Universal names are location-independent. They also allow users to transfer files to other computers.


V

view
A combination of settings in Microsoft Exchange Server for displaying and organizing the contents of a folder. Views allow users to view messages in folders by date, sender, recipient name, file size, or using a customized view.
Viewer
The graphical user interface that most users see when they start the Microsoft Exchange Client. It is also called a view window and has a standard format including several default folders.


W

Windows Messaging System (WMS)
The MAPI subsystem that is part of the Microsoft Windows 95 operating system.
Windows NT Performance Monitor
A utility that enables you to look at resource use for specific components and application processes using charts and reports. The Performance Monitor can also be used to gauge your computer's efficiency, identify and troubleshoot possible problems (such as unbalanced resource use, insufficient hardware, or poor program design), and plan for additional hardware needs.
Windows NT Registry
The control mechanism for services of Windows NT Server. Each service is registered and from that time it is controlled by the service control manager.
Windows NT security descriptor
A security descriptor contains the security information associated with an object. This information can include elements such as an owner, a primary group, and a discretionary access-control list (DACL). This information is stored in the form of security identifiers (SIDs) and access-control lists (ACLs).
Windows NT Server security
The security functions of the Win32 application programming interface that allow an application to selectively grant or deny security to an object. The impact on most Windows functions is minimal, and a Windows-based application not requiring security functionality usually does not need to incorporate any special code. Generally, any application that manipulates a system-wide resource such as the system time must use the security system to gain access to that resource.


X

X.400
An international message-handling standard for connecting e-mail networks and for connecting users to e-mail networks. X.400 is published by the X.400 Application Programming Interface Association. MAPI applications are fully compatible with X.400 messaging applications.
X.500
An international message-handling standard for directory services, published by the International Telegraph and Telephone Consultative Committee (CCITT) standards body.


Legal Information

Microsoft Exchange Server Gateway Programmer's Reference

Information in this document is subject to change without notice. This document is provided for informational purposes only and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Microsoft.

© 1996-1998 Microsoft Corporation. All rights reserved.

Microsoft, Microsoft Press, MS, MS-DOS, Windows, Windows NT, and Win32 are registered trademarks of Microsoft Corporation.


Using the Gateway Programmer's Reference

Using the Gateway Programmer’s Reference

This reference provides conceptual information about Microsoft® Exchange Server gateways and describes the gateway development tools that are included in the Microsoft Exchange Server Software Development Kit (SDK). Microsoft developers and third parties, including Microsoft Exchange Server customers with in-house customization expertise, can use these tools to create gateways between Microsoft Exchange Server and foreign e-mail systems.

The primary goal of this documentation is to provide gateway developers with the concepts and instructions needed to design and implement a Microsoft Exchange Server gateway.

For successful application development, this guide should be used in conjunction with the Messaging Application Programming Interface (MAPI) Programmer’s Reference, the Microsoft® Win32® SDK documentation, and the Microsoft Exchange Server Programmer’s Reference.


Intended Audience

To develop gateways for the Microsoft Exchange Server environment, your background should include:

  • Extensive knowledge of the messaging system for which you are developing the gateway.
  • Proficiency with C or C++ programming in the Microsoft® Windows NT® Server network operating system environment.
  • Familiarity with basic features and capabilities of Microsoft Exchange Server and Microsoft Exchange Client. Reviewing the Microsoft Exchange Server Administrator’s Guide and the Microsoft Exchange Server Concepts and Planning Guide is highly recommended.
  • Familiarity with MAPI.
  • Familiarity with network environments.


Document Conventions

This documentation uses the following typographic conventions:

Convention | Description
monospaced text
 Examples and program code appear in a non-proportional typeface.
Bold text | Literal expressions that must be typed exactly as shown, such as function names, structure names, and keywords, appear in this bold typeface.
Italic text | Italic text indicates new terms and variable expressions, such as parameters, where you fill in the actual value.
CAPITAL LETTERS | Filenames, directory names, paths, function flags, and error messages appear in capital letters.
( ) In syntax statements, parentheses enclose one or more parameters that you pass to a function.
[ ] Brackets enclose optional syntax items. Type only the syntax within the brackets, not the brackets themselves.


For More Information

For more information about MAPI programming, see the MAPI Programmer’s Reference in the Microsoft Win32 SDK.

To learn more about Microsoft Exchange Server, see:

  • Microsoft Exchange Server: Getting Started
  • Microsoft Exchange Server Concepts and Planning Guide
  • Microsoft Exchange Server Administrator’s Guide
  • Microsoft Exchange Server Application Designer’s Guide
  • Microsoft Exchange Server Programmer’s Reference in the Microsoft® BackOffice™ SDK

For more information about the Microsoft Windows programming environment:

  • Microsoft Win32 SDK
  • Programming Windows 95, by Charles Petzold (Microsoft Press, Redmond, WA)

For more information about Microsoft Windows NT Server programming:

  • Microsoft Win32 SDK

· Microsoft Windows NT Server Resource Kit


Programming Tasks

This section provides a reference list of programming tasks covered in the Microsoft Exchange Server Gateway Programmer’s Reference. Tasks are arranged by programming area. Click a topic to view its complete task description.

Addressing Tasks

Installing a Custom Address Template

Creating an Address Entry Template

Creating an Address Syntax Program

Creating a Proxy Generation DLL

Creating Address Template Installation Code

Creating a Gateway Setup Procedure

About Gateway Setup Programs

Installing Gateway Components

ADDRINST: Installing an Addr-Type Object

EXTNINST: Installing an Administrator Extension

GWINST: Installing a Mail-Gateway Object

PERFINST: Installing Performance Monitoring

PROFINST: Installing a MAPI Profile

SERVINST: Installing a Service

TMPLINST: Installing an Address Entry Template

XLATINST: Installing a Message Conversion

Using the Sample Gateway

Installing the Sample Gateway

Running the Sample Gateway

Running Gateway Sample Programs

LOOKUP: Finding a Proxy Address

PERFTEST: Monitoring Performance

PROXYGEN: Generating a Proxy Address

QUEVIEW: Listing Gateway Folders

RPTDRIV: Monitoring Message Delivery

XLATDRIV: Translating Messages


Overview

In its simplest form, a gateway is an interface that connects one electronic messaging system to another electronic messaging system that has a different message and address format. The gateway receives the mail message, translates it from one format to the other format, maps addresses between the two systems, and then delivers the translated message.

A Microsoft Exchange Server gateway is a MAPI client application. This means that the gateway uses MAPI to communicate with Microsoft Exchange Server. The gateway can access MAPI folders, transports, and other MAPI-based services. Gateways run on computers using the Microsoft Windows NT Server operating system.

A Microsoft Exchange Server gateway

Two possible scenarios for using a gateway are:

  • Between mail systems within a single organization Suppose your company has been using the PROFS system for years and now plans to convert to Microsoft Exchange Server. You can avoid business disruption by installing a gateway to connect the old and new mail systems. With the gateway, you can gradually retrain and migrate your current users to Microsoft Exchange Server, upgrade their systems, and add new users to the system. During the migration process, all employees will be able to communicate by e-mail. In such a scenario, the old mail system is the “foreign” system connected by the gateway.
  • Between an organization and an external mail system Your users need the ability to send messages from Microsoft Exchange Server to users on another messaging system such as Internet mail. In this case, you need to install a gateway that translates messages and addresses from Microsoft Exchange Server format to the format of the other messaging system.

Note: The two scenarios are architecturally identical because, in both cases, Microsoft Exchange Server uses a gateway to transfer messages to and from a messaging system that is external to it. In the first scenario, it makes no difference that the external system is part of the same organization as Microsoft Exchange Server, nor that the external system is probably connected over a LAN rather than over the Internet.

The Microsoft Exchange Server SDK provides the tools for creating gateways (including sample code for gateway functions) and a fully functional sample gateway. You can use the code as a basis for your own gateway because the sample gateway supports much of the same functionality that all gateways should support.


Gateway Components

Gateways consist of several components, which are installed in several different places within Microsoft Exchange Server or a Microsoft Exchange Server site. Some components are Win32 programs that you must create. Some are data objects within Microsoft Exchange Server that you create using the Microsoft Exchange Server Administrator program. Other components are data objects within Microsoft Exchange Server that are automatically created for you (such as proxy addresses) by the programs you create (such as the proxy generation DLL). The components are listed in the following table.

Component | Location
Gateway service | Microsoft Exchange Server computer or separate computer
Administrator extension DLL | Microsoft Exchange Server computer
Proxy generation DLL | Microsoft Exchange Server computer
Mail-Gateway Object | Microsoft Exchange Server directory
Admin-Extension Object | Microsoft Exchange Server directory
Addr-Type Object | Microsoft Exchange Server directory
MTS-IN folder | Microsoft Exchange Server information store
MTS-OUT folder | Microsoft Exchange Server information store

  • The following illustration shows the location of the components related to gateways, both when a gateway is installed on the same computer as the server and when it is installed on a separate computer.

Gateway Service

The gateway service is the heart of a gateway. It is the component that does the conversion between the MAPI messages used by Microsoft Exchange Server and the foreign system’s message format.

Gateway services are usually implemented as Windows NT Server services, which are analogous to daemons on UNIX systems. By designing your gateway server application to run as a service of Windows NT Server, you can make it an extension of the computer running Windows NT Server. This enables the gateway to:

  • Start automatically when the computer starts.
  • Be controlled through the operating system instead of through a custom user interface.
  • Run in its own security context.

A gateway running as a service of Windows NT Server has no user interface of its own. However, you can use Windows NT Server components to provide information about the gateway for its users. You can use the Windows NT Application event log to provide event and diagnostic information, and the Windows NT Performance Monitor to monitor gateway performance.


Administrator Extension DLLs

You can provide an Administrator extension DLL with your gateway. This DLL provides code that enables the Microsoft Exchange Server Administrator program to support the gateway with features such as custom property pages. If you install an extension DLL, it is represented in the directory by an Admin-Extension object that points to the location of the DLL.


Proxy Generation DLLs

You must also provide a proxy generation DLL to be used with your gateway. The proxy generation DLL does the work of mapping between Microsoft Exchange Server addresses and addresses in the foreign system’s address format.

On outgoing messages, the sender’s address and any other Microsoft Exchange Server recipients’ addresses are converted to the foreign system’s address format so that the recipient on the foreign system will be able to reply to those people.

On incoming messages, the proxy generation DLL maps the Microsoft Exchange Server recipient’s address from the foreign system format to Microsoft Exchange Server format so that the server can actually deliver the message to the proper Microsoft Exchange Server mailbox. Additionally, addresses are converted for any other recipients listed in the message that also have mailboxes on the server.


Directory Objects

Three objects appear in the Microsoft Exchange Server directory to represent the gateway. The first is a Mail-Gateway object that represents the gateway service. The second is an Admin-Extension object that represents the administrator extension DLL. The third is an Addr-Type object that represents the family of addresses handled by the gateway, and the proxy generation DLL that converts between Microsoft Exchange Server addresses and foreign addresses.

The Mail-Gateway object represents the gateway service itself, whether it is running on the same computer as the server or on a separate computer.

To address mail to foreign systems, Microsoft Exchange Server uses an Addr-Type directory object that registers the existence of the foreign address type, and points to the location of the proxy generation DLL.

The Addr-Type object is associated with the Mail-Gateway object in the gateway address routing table (GWART). The GWART contains information about the gateways available to Microsoft Exchange Server and the address types associated with each one. When a message needs to be routed through a gateway, the GWART is used to determine the appropriate gateway to use based on the address type of the recipient. The Addr-Type object also points to the location of the proxy generation DLL.

Other directory objects are used to describe address entry templates to assist users in entering new addresses, and to describe templates for entering per-message and per-recipient message options, although these do not directly represent any components of the gateway.

For more information, see Objects, Addr-Type Object.


Folders

When a Mail-Gateway object is created in the directory, Microsoft Exchange Server creates a special mailbox in the server’s information store for the gateway. This mailbox includes two folders, MTS-IN and MTS-OUT, which are used as message queues. The server places mail addressed to the foreign system in the MTS-OUT folder, and the gateway service places messages from the foreign system in the MTS-IN folder. The gateway uses MAPI functions and methods to access these folders.


Gateway Tasks

The functionality you need to design for your specific gateway is determined by the characteristics of the mail systems it connects. The tasks performed by a typical gateway include the following:

  • Message transfer Delivery of messages to foreign message systems.
  • Address mapping Translating between Microsoft Exchange Server addresses and the address format of foreign message systems.
  • Message content translation Converting between the data formats used by Microsoft Exchange Server and foreign message systems. For example, performing RTF to plain text conversion.
  • Backboning Transparently connecting two Microsoft Exchange Servers by means of an intermediate foreign message system.
  • Performance monitoring Monitoring the performace of a gateway, both for self-tuning and for use by an administrator.
  • Event logging Recording events such as deliveries and error conditions to a log file.
  • Error handling Recovering gracefully from error conditions.
  • Message tracking Being able to generate appropriate delivery and non-delivery reports.
  • Configuration management Providing the administrator with a way to configure the gateway.
  • Directory synchronization Keeping the directories of two Microsoft Exchange Servers that are connected by the gateway synchronized with each other.

These tasks are described in the following sections.


Transferring Messages

To transfer a message between Microsoft Exchange Server and a foreign messaging system, a gateway must translate both the message content and the recipient addresses to or from the format of the foreign system, depending on whether the message is coming from Microsoft Exchange Server or from the foreign system.

The following figure illustrates the basic message transfer process.

The message transfer process

The following procedures show the steps in transferring messages between Microsoft Exchange Server and a foreign messaging system. These steps form the transferring algorithm you will have to implement in your gateway.

To transfer a message to a foreign system
  1. Microsoft Exchange Server places the message in the gateway’s MTS-OUT folder.
  3. The gateway maps the addresses of the message recipients to the format of the foreign system.
  4. The gateway translates the message content so that it can be processed by the foreign system.
  5. The gateway delivers the message to the foreign system.
To transfer a message to Microsoft Exchange Server
  1. The gateway receives the message from the foreign system.
  2. The gateway maps the message addresses to the corresponding Microsoft Exchange Server addresses.
  3. The gateway translates the message content.
  4. The gateway delivers the message to its MTS-IN folder on the server.


Mapping Addresses

A proxy address is a user’s Microsoft Exchange Server address translated to a foreign system address type. When an Addr-Type object is installed, its associated proxy generation DLL is called to generate new proxy addresses for all Microsoft Exchange Server users.

Using a hypothetical person named Pat Parkes, the following table shows examples of addresses a user might have on three different systems.

Mail system | Address
Microsoft Exchange Server | EX:/o=microsoft/ou=sales/cn=recipients/ cn=PatParkes
SMTP | SMTP:PatParkes@microsoft.com
MS Mail | MS:microsoft/sales/PatParkes

When a gateway transfers a message, it must convert all the recipient addresses from the format of the originating system into the format of the receiving system.


Translating Message Content

A gateway must translate the content of each message that passes through it into a form that can be understood by the system receiving the message. If the message contains an attachment, such as a document or spreadsheet, the gateway must also deliver the attachment.

The gateway can handle the message content in several ways, depending on the characteristics of the mail systems it serves. For example, Microsoft Exchange Server can generate rich text in its messages, but PROFS systems cannot properly display rich text. A gateway between these systems needs to convert the rich text into a binary stream that PROFS can use.

Microsoft Exchange Server gateways perform message content translation by using conversion DLLs. The Microsoft Exchange Server SDK provides conversion routines to handle some types of messages, such as those generated by Microsoft Schedule+. You can also write your own conversion routines for translating between Microsoft Exchange Server and other foreign systems.


Supporting Backboning

Backboning is the process in which two similar systems are connected by a dissimilar one. Backboning is more than simply enabling messages to flow between two sites that are not directly connected. The process can allow otherwise unconnected Microsoft Exchange Server sites to behave as part of the same organization. For example, two geographically separated Microsoft Exchange Server systems can set up a backbone over a foreign system. The two sites can then be part of the same Microsoft Exchange Server organization, even though the two sites exist on separate LANs.

Backboning over the Internet

The backboning process imposes special requirements on a gateway. The gateway must provide seamless addressing and communication throughout the entire backboning process, even when the message format of the foreign system cannot support some features used by Microsoft Exchange Server. In the scenario illustrated above, the messages might have features, such as rich text formatting, that the foreign system cannot handle. The MAPI SDK and the Microsoft Exchange Server SDK provide functions that enable gateways to encode such features so that they may pass safely through the foreign system.


Performing Support Functions

Gateways are complex and need to handle many situations, some of which may require troubleshooting efforts by the Microsoft Exchange Server administrator to reach peak performance. To support administrators in maintaining Microsoft Exchange Server sites, a gateway can be set up to perform the following support functions:

  • Performance monitoring You can design your gateway so it generates performance monitoring reports using functions provided with the Microsoft Exchange Server SDK.
  • Event logging Your gateway can use the Windows NT Application event log to record events that occur during the message transfer process.
  • Error handling When errors occur, your gateway can provide users with the information necessary to understand what went wrong. This can involve supplying reports to the originator about nondelivered mail, writing information to an error log, or alerting the administrator. These functions can be performed by the Windows NT Application event log.
  • Message tracking Your gateway can track the progress of messages as they travel through the gateway to or from Microsoft Exchange Server. Because message identifiers vary between systems, this function requires that you enable cross-references.
  • Configuration management You can design your gateway to detect changes in its configuration data.
  • Directory synchronization Some mail systems have directories containing user addresses. Directory synchronization is an optional process that lets you copy directory information between Microsoft Exchange Server and a foreign mail system. Foreign system recipients then appear to be part of the Microsoft Exchange Server directory, and users are unaware that their mail is delivered through a gateway. This process is useful when an organization is in the process of migrating employees between two e-mail systems. By using directory synchronization, identical user information can be maintained on both systems, so that employees on both the old and the new systems do not have to be aware of which employees are on which system.


Gateway Support Functions

The GWMAIN.H header file defines several functions that your gateway can use to perform tasks that are important to a gateway’s operation. They are:

FreeThreadParameter

GetAdrBookPtr

GetGWDefaultStore

GetGWExchangeServerName

GetGWFindData

GetGWFindDataSize

GetGWGAL

GetGWGALEntryId

GetGWGALEntryIdSize

GetGWMtsInFolder

GetGWMtsOutFolder

GetGWNewMailEvent

GetGWNewMailStatus

GetGWPath

GetGWRootFolder

GetGWSession

GetGWSRowSet

GetGWSubmitInterval

HrGWStartNewFileHandler

HrGWStartNewMailHandler

HrGWWaitForStop


Addressing

A gateway must be able to address mail to users in both the Microsoft Exchange Server system and in the foreign system it serves. The gateway accomplishes this by mapping addresses between Microsoft Exchange Server and the foreign system. The gateway must be able to map addresses in both directions to handle both incoming and outgoing messages.


Microsoft Exchange Server Addresses

Microsoft Exchange Server addresses have two parts: an address type and the address itself. EX is the address type for native Microsoft Exchange Server addresses. The unique address for each object in the Microsoft Exchange Server directory is the object’s distinguished name (DN). The DN starts with the Microsoft Exchange Server organization at the highest level and continues to the object being named. For example, the DN for John Jones might be:

/o=Trager/ou=New York/cn=Recipients/cn=JohnJ

corresponding to a Microsoft Exchange Server address of:

EX:/o=Trager/ou=New York/cn=Recipients/cn=JohnJ


Recipient Objects

Recipient objects represent all of the available delivery points on a Microsoft Exchange Server site. Anything that a message can be delivered to has a recipient object associated with it. Microsoft Exchange Server handles several types of recipient objects:

  • User mailboxes Native Microsoft Exchange Server users. Mailboxes are represented by objects in the Microsoft Exchange Server directory, and are visible in Microsoft Exchange Server address books. User mailboxes have storage allocated to them in the Microsoft Exchange Server information store.
  • Custom recipients Objects in the Microsoft Exchange Server directory that represent users of foreign mail systems. Custom recipients appear in Microsoft Exchange Server address books alongside native Microsoft Exchange Server user mailboxes. A foreign e-mail address, or target address, is associated with every custom recipient. Mail sent to a custom recipient is redirected to a gateway capable of delivering the mail to the appropriate foreign mail system.
  • One-off addresses Addresses of any type that do not appear in a Microsoft Exchange Server address book. One-off addresses are either constructed once and not saved, or are saved in a user’s Personal Address Book, inaccessible to Microsoft Exchange Server.
  • Distribution lists Collections of addresses that include any of the types listed above. Public distribution lists are saved on the server, where they can be made available to all users. Private distribution lists are saved in a user’s personal address book.


Proxy Addresses

A proxy address is the address by which a Microsoft Exchange Server recipient object is recognized in a foreign mail system. Proxy addresses are required not just for users, but for all recipient objects such as custom recipients, distribution lists, and public folders.

Each Microsoft Exchange Server recipient object will have several proxy addresses — at least one for each foreign address type known to the system. The proxy addresses for each foreign address type are created by a DLL provided with the Addr-Type directory object when the address type is installed.

The following table shows three proxy addresses associated with the native Microsoft Exchange Server user Pat Parkes. Each proxy address is prefixed with its address type. Mail originating in a foreign messaging system is addressed to Microsoft Exchange Server recipients by using the proxy address that corresponds to the foreign system. For example, Internet users address mail to PatParkes@microsoft.com, and when Pat Parkes sends mail to the Internet, it appears to come from PatParkes@microsoft.com.

Address type | Address
Microsoft Exchange Server | EX:/o=microsoft/ou=sales/cn=PatParkes
SMTP proxy | SMTP:PatParkes@microsoft.com
MS Mail proxy | MS:microsoft/sales/PatParkes
X.400 proxy | X400:c=US;a= ;p=Microsoft;s=Parkes;g=Pat

Users can have primary and secondary proxy addresses. The primary proxy address for a user is the one used when sending mail to the foreign system. The secondary proxy addresses are used when receiving mail from the foreign system. On outgoing messages, the primary proxy address is used as the sender’s address. On incoming messages, the recipient listed in the message is matched against the secondary proxy addresses in the Microsoft Exchange Server directory to find the proper recipient object for the message.

A user has only one primary proxy address but might have multiple secondary addresses. For example, if two companies merge and give new e-mail addresses to all their employees, secondary proxy addresses might be used so that employees can receive mail at both their old and new e-mail addresses. By maintaining the old e-mail addresses as secondary proxy addresses, incoming mail can be addressed to either the old or new address. Outgoing mail is always addressed using the primary proxy address.

A gateway should be able to generate proxy addresses for most types of recipient objects—user mailboxes, custom recipients, and distribution lists, and public folders. It does not need to generate proxy addresses for one-off addresses.

Note The term proxy address is equivalent to the term e-mail address used in the Microsoft Exchange Server Administrator program documentation. To view the proxy addresses for a Microsoft Exchange Server user, click the E-mail Addresses tab on the user’s property sheet. The following figure shows typical proxy addresses.

Proxy addresses


Creating a Proxy Address

Proxy addresses can be created either manually through the user interface or automatically by a proxy generation DLL. If your gateway serves a foreign system that does not already have proxy addresses in the Microsoft Exchange Server system, you will need to provide an Addr-Type object and an associated proxy generation DLL.

The proxy generation DLL implements a set of functions that the Microsoft Exchange Server calls to create proxy addresses. When a new address type is installed, the proxy generation DLL associated with the new foreign address type is called to generate a new, unique proxy address for each user. When a new user is added, the proxy generation DLLs for each known address type are called to create proxy addresses for the new user.

Because your proxy generation DLL must create a unique proxy address for each Microsoft Exchange Server recipient object, you should base your address generation algorithm on Microsoft Exchange Server address attributes that are already unique for each user. One unique attribute is the alias. Another possiblility is the pszCommonName member in the RECIPIENTINFO structure. You can combine unique attributes with other recipient information to form the proxy address.

Note The address type name is limited to eight characters. The proxy address itself is limited to 128 characters. Proxy addresses are limited to the 7-bit ASCII character set.

When you provide a proxy generation DLL, your gateway setup program must initiate the proxy address generation process. Microsoft Exchange Server automatically generates the addresses in the background while control is returned to the setup program. Gateway Setup Programs describes this process.


Using a Site Proxy Address

The site proxy address is the portion of a proxy address that corresponds to the site rather than to an individual user. For example, @trager.com might be the SMTP site proxy address for the Trager company. The site proxy address is treated as a separate entity to make it easier to create new proxy addresses in a case where, for example, a company changes its e-mail address. In such a situation, you would need to change only the site proxy address and then regenerate proxy addresses for all users at the company.


Address Spaces

When a gateway is installed, the Microsoft Exchange Server is informed of the address types for which the gateway can deliver messages. For example, an RFC-822 gateway would declare itself as able to deliver messages addressed to recipients with the SMTP address type. You can configure your gateway to accept mail only for a subset of the address type’s domain. For example, an organization might install two PROFS gateways, one to deliver mail to PROFS NODE1, and the other to deliver mail to PROFS NODE2. A gateway can also service more than one address type.

The set of address types and subtypes that the gateway can service is called the gateway’s address space.

Address space information is saved in the Routing-List attribute of the gateway’s Mail-Gateway directory object. It can be set programatically, or manually from the Address Space property page in Microsoft Exchange Server Administrator.

The gateway’s address space information is incorporated into the Microsoft Exchange Server’s Gateway Address Routing Table (GWART), which is then used to determine the routing of mail messages within the system.


Address Mapping

A gateway is responsible for delivering messages to the correct recipient. This usually involves translating between address types. For outgoing messages, your gateway must ensure that recipient addresses are in a form compatible with the foreign system. For incoming messages, it must be able to translate recipient addresses from the foreign system’s format into proxy addresses that it can look up in the Microsoft Exchange Server directory.


The Responsibility Attribute

When a message passes through a gateway, each recipient of that message has a Responsibility attribute that is set by the message transfer agent (MTA). When the gateway must deliver the message to a recipient, this attribute is set to TRUE. When the gateway needs to track the recipient but not deliver the message, the attribute is set to FALSE. Based on this attribute, recipients are referred to as Responsibility-TRUE or Responsibility-FALSE.

To illustrate how the Responsibility attribute is set, suppose that a native Microsoft Exchange Server user sends a message to three recipients:

  • R1 is a local recipient on the same server as the sender.
  • R2 is a Microsoft Exchange Server recipient on another site in the same organization, connected over X.400.
  • R3 is a recipient on a foreign system.

The following diagram illustrates this scenario.

Sending messages to several users

The message is delivered as follows:

  1. The message is originally submitted by the sender to the Microsoft Exchange Server information store. The information store can deliver directly to a local recipient, so it delivers a copy of the message to R1. It sends another copy to the MTA. On this copy R1 is Responsibility-FALSE, and R2 and R3 are Responsibility-TRUE.
  2. The MTA does not attempt to deliver to the local recipient because R1 is Responsibility-FALSE. The MTA looks in its routing tables and determines that it can deliver the message to R2 by sending the message to another MTA connected via X.400. For this message, R1 and R3 are Responsibility-FALSE and R2 is Responsibility-TRUE.
  3. The gateway connected to the server also appears in the MTA’s routing table. The MTA routes another copy of the message to the gateway, with R1 and R2 set to Responsibility-FALSE, and R3 set to Responsibility-TRUE.


Using the Address Lookup Functions

The Microsoft Exchange Server SDK provides functions that convert between foreign addresses and native Microsoft Exchange Server addresses. These functions are based on the standard MAPI methods IAddrBook::PrepareRecipients and IABContainer::ResolveNames, applied to the Microsoft Exchange Server global address list.

Address Lookup Functions from the Microsoft Exchange Server SDK

Function | Action | When called
HrFindExchangeGlobalAddressList | Returns the entry identifier of the global address list (GAL) container in the address book. The MAPI OpenEntry method is then used to open the GAL. | As the gateway starts.
HrGWResolveAddress (based on IABContainer::ResolveNames) | Converts a recipient’s proxy address into the entry identifier for a Microsoft Exchange Server recipient, by looking up the proxy address in the GAL. | For addresses in incoming messages to Microsoft Exchange Server.
HrGWResolveProxy (based on IAddrBook::PrepareRecipients) | Looks up a recipient’s proxy address. | For addresses in outgoing messages from Microsoft Exchange Server.

For outgoing messages, gateways call the HrGWResolveProxy function to convert all the native Microsoft Exchange Server addresses in a message into their corresponding proxy addresses for the foreign system that the gateway serves. For incoming messages, gateways call HrGWResolveAddress to convert the proxy addresses in the message into native Microsoft Exchange Server addresses. Both of these functions reference the native Microsoft Exchange Server addresses with the MAPI entry identifiers for those addresses.

The LOOKUP sample application illustrates simple address mapping using the address lookup functions.


Implementing Address Lookup Functions

Gateway developers are not restricted to using the HrGWResolveProxy and HrGWResolveAddress functions to look up addresses. You can implement your own versions of these functions if necessary because the provided implementations simply use MAPI methods to find address information. The ADDRLKUP sample code does this. The ADDRLKUP sample code is in the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\ADDRLKUP directory.

For simplicity, the provided implementations of HrGWResolveAddress and HrGWResolveProxy have been written to act on a single address at a time. However, the underlying MAPI methods IABContainer::ResolveNames and IAddrBook::PrepareRecipients can act on several addresses at a time, with better overall performance. The MAPI Programmer’s Reference gives detailed information about MAPI methods. If your gateway is often used to send or receive messages with large numbers of recipients, it may be necessary for you to implement your own versions of these functions to achieve better performance.

HrGWResolveProxy uses the IAddrBook::PrepareRecipients method to look up addressing information for outgoing recipients. Calls to IAddrBook::PrepareRecipients can return any specified set of recipient properties. If you are implementing your own version of HrGWResolveProxy you can optimize your IAddrBook::PrepareRecipients calls to return all recipient properties that you might need, not just address properties. This will avoid later GetProps calls to retrieve information like display names, and cut down on remote procedure calls generated by your gateway.

The following recipient properties are of particular interest to gateways, so you should request them all. For information about the following properties, see the MAPI Programmer’s Reference:

PR_ENTRYID
PR_DISPLAY_NAME
PR_OBJECT_TYPE
PR_ADDRTYPE
PR_DISPLAY_TYPE
PR_SEARCH_KEY
PR_EMAIL_ADDRESS
PR_TRANSMITTABLE_DISPLAY_NAME
PR_SEND_RICH_INFO

In addition, PR_EMS_AB_PROXY_ADDRESSES is useful to gateways.

HrGWResolveAddress uses the IABContainer::ResolveNames method to match foreign addresses on incoming mail with proxy addresses on Microsoft Exchange Server users. Like IAddrBook::PrepareRecipients, IABContainer::ResolveNames can return any set of properties for the recipients that it finds. If you are implementing your own version of HrGWResolveAddress, you should consider returning all of the following properties with each call to IABContainer::ResolveNames. (For information about specific properties, see the MAPI Programmer’s Reference.)

PR_ENTRYID
PR_DISPLAY_NAME
PR_OBJECT_TYPE
PR_ADDRTYPE
PR_SEARCH_KEY
PR_EMAIL_ADDRESS
PR_TRANSMITTABLE_DISPLAY_NAME
PR_SEND_RICH_INFO

The EMS_AB_ADDRESS_LOOKUP flag should be set when IABContainer::ResolveNames is used to match incoming foreign addresses with proxy address. When the EMS_AB_ADDRESS_LOOKUP flag is set, IABContainer::ResolveNames will only find exact matches on proxy addresses. Partial matches are ignored, as are any other search attributes. Any Microsoft Exchange Server directory object with defined proxy addresses can be found this way, including objects marked as hidden from the address book.

Most of these optimizations are used by the sample gateway provided with this SDK. The sample gateway source code is in the \BKOFFICE\SAMPLES\EXCHANGE\GWSAMPLE directory.

Finally, note that looking up proxy addresses is only one of several possible ways to associate foreign addresses on incoming mail with a Microsoft Exchange Server recipient. The two most common alternatives are algorithmic mapping and address encapsulation.

Algorithmic mapping can be used when there is a well-defined, fixed relationship between the format of an incoming foreign address and some equally well-defined, and preferably unique, attribute of the Microsoft Exchange Server user’s address. For example, if an organization’s Internet addresses are based on users’ mail aliases, the SMTP address “PatParkes@trager.com” can be mapped to the Microsoft Exchange Server user whose alias is “PatParkes.”

Address encapsulation is a more extreme version of algorithmic mapping in which an entire address is encapsulated within another address format. For example, an SMTP gateway might understand the address [PROFS:NODE1/PATP]@microsoft.com as an instruction to redirect the message to a PROFS gateway, addressed to NODE1/PATP. Microsoft Exchange Server gateways can use the IAddrBook::CreateOneOff method to implement support for address encapsulation.


Mapping Outbound Addresses

When a gateway receives a message from Microsoft Exchange Server, addresses for each recipient have the properties PR_ENTRYID, PR_ADDRTYPE, and PR_EMAIL_ADDRESS. The originator address has the PR_ORIGINATOR_ENTRYID, PR_ORIGINATOR_ADDRTYPE, and PR_ORIGINATOR_ADDRESS properties. These addresses are in Microsoft Exchange Server format and the gateway must translate them to the format of the foreign system.

Beginning with the PR_ENTRYID and PR_ADDRTYPE properties, the gateway can look up an existing proxy address for the foreign system using the address lookup function HrGWResolveProxy. When it finds the proxy address corresponding to the foreign system, it uses that address to deliver the message.

If the gateway cannot map an address from Microsoft Exchange Server to the foreign system, it must take appropriate action as follows:

  • Originator Generate a nondelivery report for each Responsibility-TRUE recipient, and send the nondelivery report to the originator. This is because the gateway cannot generate a return address for replies to the message. (See Reports for information about gateway reports.)
  • Responsibility-TRUE recipient Generate a nondelivery report for the recipient.
  • Responsibility-FALSE recipient Do not generate a nondelivery report, but preserve as much address information as possible by using encapsulation or a comment field.

The following figure illustrates a message being sent from a Microsoft Exchange Server originator to an SMTP recipient. The originator’s address is expressed in Microsoft Exchange Server format and the recipient’s address is in SMTP format. This tells Microsoft Exchange Server that the message must be sent through the SMTP gateway.

Outbound address mapping

In this scenario, the gateway looks up the originator’s SMTP proxy address and maps the originator’s EX address to SMTP format before delivering the message to the SMTP system.


Mapping Inbound Addresses

Mapping addresses on inbound messages is similar to mapping addresses on outbound messages. The gateway must convert every address in the message into a form that Microsoft Exchange Server understands. Ideally, this form is the native Microsoft Exchange Server (EX) address format. At least one recipient on an inbound message should have a native address that corresponds to it. If that is not the case then there are no recipients that the gateway can deliver the message to.

The gateway must deal with three classes of addresses in an inbound message:

  • Local recipients Local recipients are those for which there is a native Microsoft Exchange Server address corresponding to the recipient address in the inbound message. The gateway must convert these addresses to their native EX addresses before delivering the message to the server.
  • Foreign recipients Foreign recipients are those whose addresses in the inbound message do not correspond to any native Microsoft Exchange Server addresses. The gateway must create one-off addresses to represent these recipients before delivering the message to the server.
  • Originator The gateway must create a one-off address for the message’s originator before delivering the message to the server.

All MAPI-based systems, including Microsoft Exchange Server, require that the originator and each recipient of a message have a PR_ENTRYID property. However, the originator of a message from a foreign message system may not have entry ID in the server’s global address list. For a message coming from a foreign system to Microsoft Exchange Server, the gateway can:

  • Use the address lookup function HrGWResolveAddress with the proxy address and the foreign system address type to look up the PR_ENTRYID property for the originator and each recipient.
  • Attempt to generate a PR_ENTRYID property using the MAPI IAddrBook::CreateOneOff method if the previous action fails.

If the gateway cannot find or create the PR_ENTRYID property, it must take appropriate action as follows:

  • Originator Generate a nondelivery report for each Responsibility-TRUE recipient, and send the nondelivery report to the originator. This is because the gateway cannot generate a return address for replies to the message. (See Reports for information about gateway reports.) Create a nondelivery report for each Responsibility-TRUE recipient.
  • Responsibility-TRUE recipient Generate a nondelivery report for the recipient.
  • Responsibility-FALSE recipient Drop the recipient from the message or place it in a purely textual field.


Directory Addressing Objects

For Microsoft Exchange Server to support a foreign address type, several objects must be created in the Microsoft Exchange Server directory:

  • An Addr-Type object.
  • A proxy generation DLL.
  • An address entry template for the Microsoft Exchange Server Administrator.
  • Per-message and Per-recipient options for messages sent to addresses of the foreign address type, with online Help for those options.
  • A data file describing the dialog box to be displayed by the Address-Template object for creating and editing addresses in the remote system’s address format.
  • A data file describing a program for validating the data entered into the address template dialog and converting it into an address in the foreign system’s address format.


The Addr-Type Object

Every gateway has an associated address type that corresponds to the address format of the foreign system the gateway serves. This address type is represented by an Addr-Type directory object. The gateway and the Addr-Type object are associated by the Microsoft Exchange Server’s GWART. Your gateway’s setup program installs a the Addr-Type object and associated information when it installs the gateway.

The following components are associated with an Addr-Type object:

  • A proxy address generation DLL that enables the system to generate proxy addresses of this address type.
  • Address entry templates that assist the administrator or user in manually entering a recipient address of this address type. There are two types of templates: normal and MS-DOS.
  • Per-message and per-recipient options that enable users to set options in messages sent to addresses of this address type.
  • Online Help that provides instructions for using the property pages associated with per-message and per-recipient options.


Proxy Generation DLL Entry Points

The proxy generation DLL must provide the following entry points.

Proxy Address Generation Functions (from Microsoft Exchange Server SDK)

Function | Action | When called
RcInitProxies | Initializes a new proxy address generation session. | Before recipient objects or address types are created
RcGenerateProxy | Generates a user-level proxy address as a Unicode string. | As a recipient object is created, or as an address type is installed or updated for all recipients
RcValidateProxy | Validates that a proxy address string is a valid address in the foreign system. | As a proxy address is manually edited
RcUpdateProxy | Updates the site proxy portion of a proxy address. | As a proxy address is updated
RcValidateSiteProxy | Validates that a site proxy address string is a valid address in the foreign system. | As a site proxy address is manually edited
FreeProxy | Frees memory allocated for a proxy address string. | When generation of proxy addresses is complete
CloseProxies | Closes a proxy address generation session and frees any associated data. | As creation of recipient object is complete

Because proxy address generation is handled by a DLL, it is not portable to different platforms. If you are running Microsoft Exchange Server on multiple platforms, such as Intel and DEC-Alpha, you will have to compile your proxy generation DLL separately on each platform and install the appropriate version on at least one server of each type of platform at a site. Each server must have the proxy generation DLL available to it because proxy addresses are only generated when a recipient object is created on a server or when the DLL is installed. When information about the new address type is replicated to the other servers at the site, those servers will locate and copy the DLL to themselves and perform the normal proxy address generation.


Address Entry Template Objects

If your gateway provides an Addr-Type object, it should also provide an address entry template. This template displays a dialog box in which the user enters information to create an address of the type supported by the gateway.

Templates make the address type generally available to users and allow users to create addresses by simply entering information in the dialog box. In this way the user does not need to know the details of address type syntax. The address entry template works together with a corresponding Address Syntax Program which converts the data in the dialog box specified by the address entry teplate dialog box into an actual proxy address string.

The address entry template is used by:

  • The administrator using the Microsoft Exchange Server Administrator program to create a new custom recipient object. The Administrator program command for this is New Custom Recipient from the File menu.
  • Users of the Microsoft Exchange Client to create one-off addresses either directly in e-mail messages or for storage in their personal address books.

The following figure shows the dialog box presented by the X.400 address entry template.

X.400 address entry template

The X.400 proxy generation DLL would use the information in this dialog box to create the address

X400:c=US;a= ;p=Microsoft;ou=sales;s=Parkes;g=Pat;cn=PatParkes


Address Entry Template Binary Data

You create an address entry template by creating a binary file that describes the data entry fields in the address entry dialog box. This data file is used by the Microsoft Exchange Server address book provider to create the dialog box that users use to create new addresses of your gateway’s address type. The Microsoft Exchange Server SDK provides the TEMPLATE.EXE utility, which converts a text file describing dialog box controls into the binary file.

The text file input for TEMPLATE.EXE must be written in Unicode. You can use the Windows NT Server Notepad utility to enter the text file and save it in Unicode format. Save the file with a .WTX extension to distinguish it from ANSI .TXT files.

The Unicode text file has nine fields for each dialog box control, separated by commas, as shown in the following table.

Unicode Text File Fields for Address Entry Template

Field | Type | Description
1 | Integer | X position of control.
2 | Integer | X length of control.
3 | Integer | Y position of control.
4 | Integer | Y height of control.
5 Integer Type of control. Valid entries are:
DTCT_BUTTON – Creates a command button.
DTCT_CHECKBOX – Creates a check box.
DTCT_EDIT – Creates an edit field for user input.
DTCT_GROUPBOX – Creates a group box.
DTCT_LABEL – Creates a text label.
DTCT_LBX – Creates a list box.
DTCT_MVLISTBOX – Creates a multivalued list box.
DTCT_PAGE – Introduces a new page in the property sheet.
6 Integer Control flags. These are used only for DTCT_EDIT entries.

Valid entries can be a combination of the following:
0x00000001 – Creates a multiline edit control.
0x00000002 – Allows edit control to be edited.
0x00000004 – Requires edit from the user upon OK.
0x00000010 – Displays an asterisk (*) as user types in the edit control, such as for a password.

To combine these flags, bitwise OR them and enter the result in this field.
7 Integer Property tag that controls are mapped to. This value will be used by the address generation code to access field information entered by the user.

Valid entries are:
0x3001001E – PR_DISPLAY_NAME (display name of custom recipient).
0x6800001E – 0xFFFE001E – Custom string properties.

Note that the low-order bits for the custom string property are always 001E, which indicates that the property is a string.
8 | Integer | For DTCT_EDIT fields, the maximum length of input.
9 | Text | Label text for control. This can be text or an asterisk. NOTE: If you place a space between the last comma separator and this entry, the edit control will be created as read-only.

For example, the PROFS address type includes the Display Name, the Host Node Identifier, and the Host User Identifier. The following file illustrates a Unicode text file describing a PROFS address template.

0, 0, 0, 0, DTCT_PAGE, 0x00000000, 0x00000000, 0,PROFS Address
12, 50, 20, 8, DTCT_LABEL, 0x00000000, 0x00000000, 0,Display Name:
75, 141, 18, 12, DTCT_EDIT, 0x00000006, 0x3001001E, 256,*
12, 51, 43, 8, DTCT_LABEL, 0x00000000, 0x00000000, 0,Host Node ID:
75, 141, 41, 12, DTCT_EDIT, 0x00000006, 0x6800001E, 32,*
12, 51, 56, 8, DTCT_LABEL, 0x00000000, 0x00000000, 0,Host User ID:
75, 141, 54, 12, DTCT_EDIT, 0x00000006, 0x6801001E, 32,*

TEMPLATE.EXE takes the .WTX file as input and produces a binary file that is used as an attribute for the Address-Entry-Template object. Typically the output file has the same name as the input file, but has a .BLT extension. To convert the example PROFSADT.WTX to PROFSADT.BLT, enter the command

TEMPLATE PROFSADT.WTX PROFSADT.BLT


Address Syntax Programs

Address syntax programs work together with Address Entry Templates to convert data entered in an address entry template dialog box into a proxy address string. When the user clicks OK or Accept in an address template dialog box, the Microsoft Exchange Server address book reads the data from the dialog box and uses it to create the custom address in the correct syntax. You need to provide an address syntax program that the address book can use to translate the entered data into the complete address. This program is the Address-Syntax attribute on the Address-Entry-Template object.

This program is written in a special assembly-like address syntax language and is not compiled into executable code for each platform that your gateway is compiled for. It is byte-compiled into a special binary data file that is used by the Microsoft Exchange Server address book. This program does the work of converting data from the address entry template dialog box into an actual address string. Because the program is not compiled into platform-specific executable code, it is portable across all platforms supported by Microsoft Exchange Server.

To create the address syntax binary file
  1. Use the fields defined in the address template text file to determine how to generate the proxy addresses from the template input.
  2. Write the address syntax program in symbolic format.
  3. Convert the symbolic program into the binary data stored in a file.


Address Syntax Language

Programs in the address syntax language are a series of instructions and optional data. Each instruction is exactly 32 bits long and has from zero to three subsequent 32-bit operands; the number of operands is determined by the opcode stored in the lower 24 bits of the instruction. The two most significant bits, A1 and A2, specify whether the first two operands are addresses or MAPI property tags. If A1 is 1, then the first operand is an address. If A1 is 0, then the first operand is a MAPI property tag. Similarly, the value of A2 indicates the contents of the second operand. If the third operand exists, it is always an address. The remainder of the most significant byte of the instruction is reserved, and should be all zeroes. The following figure shows the structure of address syntax language instruction.

Address syntax language instruction format

The last instruction in the program must be HALT or ERROR. Any data for the program must be outside of the execution flow; you can place it after the last instruction or use the JUMP instruction to transfer execution over the data. An instruction has the format:

opcode [op1 [op2 [program-address]]]

where op1 and op2 are property tags associated with edit controls from the address template file or addresses of data strings within the address syntax program. The program-address operand is the address of an executable instruction in the address syntax program. Each instruction must have an operation code, but op1, op2, and program address are optional.

The following table describes all the instructions in the address syntax language.

Address Syntax Language Instructions

Symbolic name and operands | Binary Instruction Value | Number of operands | Description
HALT | 0x00000000 | 0 | End of program. Indicates successful completion.
ERROR | 0x00000001 | 0 | End of program. An error was detected in data supplied by the user.
EMIT property tag | 0x00000002 | 1 | Emits the data referenced by the property tag. Emitting data means copying what the user entered in the text field and appending it to the proxy address.
EMIT data address | 0x80000002 | 1 | Emits the data in a string referenced by the data address. There must be data included after the HALT command in the address syntax program; the address is a hexadecimal offset in bytes from the beginning of the program, but may also be specified with a label.
EMITUPPER data address | 0x00000006 | 1 | Same as the EMIT instruction, but converts the string to uppercase before appending it to the proxy address.
JUMP program address | 0x00000003 | 1 | Program execution transfers to the designated address. The operand is the address where the Microsoft Exchange Server address book will execute the next instruction.
JNX property tag, program address | 0x00000004 | 2 | Program execution transfers to the designated address if there is no data in the edit control associated with the property tag. This instruction allows the address syntax code to emit default data if the user fails to enter data in an optional field. The program may use this instruction to jump to an ERROR instruction that is handled by the Microsoft Exchange Server address book.
JE property tag1, property tag2, program address | 0x00000005 | 3 | Program execution transfers to the given program address if the data in edit controls associated with the two property tags are equal.
JE property tag, data address, program address | 0x40000005 | 3 | Program execution transfers to the given program address if data in the edit control associated with the property tag equals data referred to by the data address.
JE data1 address, data2 address, program address | 0xC0000005 | 3 | Program execution transfers to the given program address if data referred to by the two data addresses are equal.


Sample Address Syntax Program

This example demonstrates converting data entered in a PROFS address entry template into a proxy address string. The PR_NODE and PR_USER values are user-defined. Error1 and Slash represent addresses within the address syntax program. The PROFS proxy addresses are in the form PROFS:node/user, where node and user represent information entered in the address entry template dialog box. The prefix “PROFS:” is generated automatically by the Microsoft Exchange Server address book from the Address Type attribute. You must supply the slash (/) character within the address syntax program.

Using the sample PROFS address template described in Address Entry Template Binary Data, a symbolic address syntax program might look like:

EQU      PR_NODE         0x6800001E
              EQU      PR_USER         0x6801001E
              JNX      PR_NODE         Error1
              JNX      PR_USER         Error1
              EMIT     PR_NODE
              EMIT     Slash
              EMIT     PR_USER
              HALT
Error1:       ERROR
Slash:        "/"

Note that EQU in this example is a pseudo-operation that is not supported directly by the Microsoft Exchange Server address book. It has the same effect as a #define statement in C, which means that it allows numeric constants to be referred to by symbolic names that are only meaningful at compile time.

This program first checks if the Host Node ID and Host User ID fields of the template have been filled in. If not, program execution jumps to the label Error1 and executes the ERROR instruction. If the data is valid, execution continues and builds the PROFS proxy address by generating the data in the text fields and additional data.

The above example program must be converted to the following binary data so it can be used by the Microsoft Exchange Server address book. In the following table, the Address column is for reference only; the address numbers are not part of the program. You can do this conversion by hand (which is not unreasonably difficult because address syntax programs tend to be short), or you can write a program in some other language to create the binary file for you. There is presently no assembler utility provided to convert an address syntax program from a symbolic format to the required binary format.

Program Code for PROFS File

Address | Program code | Comment
00 | 0x00000004 | JNX
 | 0x6800001E | Property tag for PR_NODE
 | 0x00000034 | Program address of Error1
0C | 0x00000004 | JNX
 | 0x6801001E | Property tag for PR_USER
 | 0x00000034 | Program address of Error1
18 | 0x00000002 | EMIT edit control data
 | 0x6800001E | Property tag for PR_NODE
20 | 0x80000002 | EMIT data from program
 | 0x00000038 | Address of data string “/”
28 | 0x00000002 | EMIT edit control data
 | 0x6801001E | Property tag for PR_USER
30 | 0x00000000 | HALT
34 | 0x00000001 | ERROR
38 | 0x2F000000 | ASCII of “/”, null terminated

The hexadecimal numbers in the Program code column of this table are saved in a binary file. You can create an address template syntax program using a simple C program like the ones listed here.

CCMAIL.C | Generates a ccMail address template syntax program.
MACSCR.C | Generates a MacMail address template syntax program.
PCMSCR.C | Generates a PC-Mail address template syntax program.
X400SCR.C | Generates a X.400 address template syntax program.
SDUMP.C | “Disassembles” an existing binary address template syntax program into symbolic format.

These sample programs are located in the \BKOFFICE\SAMPLES\EXCHANGE\SYNTGEN directory. To compile one of these files, type CL <filename>.


Message and Recipient Options

Microsoft Exchange Server users can set special gateway options that apply for each message or for each recipient in the messages to or from a specified address type. The gateway provides for these options by supplying display tables in the Address-Template object. These message and recipient options then become properties in the MAPI message.

The message options property sheet in the Microsoft Exchange Client contains a property page for each message-options display table. These property sheets let the user specify message options for each resolved address in the recipient list of the message currently being composed or viewed.

Note You cannot implement default message options because Microsoft Exchange Server does not support the MAPI IMAPISession::QueryDefaultMessageOpt function.

The Recipient Options property sheet in the Microsoft Exchange Client contains a property page for each recipient-options display table. This property sheet lets the user set options for each individual message recipient that has an address of the gateway’s address type.

Note Recipient options do not work for custom recipients because recipient options are defined for a specific address type. The address type of a custom recipient in the Microsoft Exchange Server address book is EX rather than the recipient’s native address type (such as SMTP). Therefore, Microsoft Exchange Server has no reference for matching the address to a particular recipient options property sheet.

The Microsoft Exchange Server MS-DOS client does not expose message or recipient options, so the gateway must not depend on these options for correct operation.


Creating the Options Template

Similar to the address entry template, you need to provide templates into which the user can enter message and recipient options. The Microsoft Exchange Server SDK provides the TEMPLATE.EXE utility, which converts a text file describing dialog box controls into a binary file. You can use TEMPLATE.EXE to compile both your address entry templates and your options templates.

The TEMPLATE.EXE utility accepts a Unicode comma-separated-value (CSV) file of template control fields. The field descriptions are based on parameter definitions in the MAPI Programmer’s Reference. The actual field contents will vary depending on the syntax of the control, and a given field might not exist for a given control.

Options templates are created from .WTX files that you can create with the NOTEPAD.EXE utility. Each line in the file has 10 fields which describe one element in the options template. The following table lists the fields for describing these elements.

Control Fields for Options Templates

Field | Type | Description
1 | Integer | Horizontal position of control.
2 | Integer | Width of control.
3 | Integer | Vertical position of control.
4 | Integer | Height of control.
5 Integer Type of control. Valid entries are:
DTCT_BUTTON – Creates a command button.
DTCT_CHECKBOX – Creates a check box.
DTCT_EDIT – Creates an edit field for user input.
DTCT_GROUPBOX – Creates a group box.
DTCT_LABEL – Creates a text label.
DTCT_LBX – Creates a list box.
DTCT_MVLISTBOX – Creates a multivalued list box.
DTCT_PAGE – Introduces a new page in the property sheet.
6 Integer Control flags. This field corresponds to the ulFlags parameter in the MAPI structures.

Valid entries can be a combination of the following:
0x00000001 – Creates a multiline edit control.
0x00000002 – Allows edit control to be edited.
0x00000004 – Requires data from the user upon OK.
0x00000010 – Displays an asterisk (*) as user types in the edit control, such as for a password.

These flags are used only for DTCT_EDIT entries. To combine these flags, bitwise OR them and enter the result in this field.

DTCT_PAGE entries make special use of this field. Rather than storing flags, this field is used to store the context identifier of the topic in the help file for this property sheet.
7 | Integer | Control parameter 1. For DTCT_EDIT fields, this is the maximum length of input.
8 | Integer | Control parameter 2. This field is the property tag that controls are mapped to. It corresponds to the ulPropTag parameter in the MAPI structures.
9 | Integer | Control parameter 3. This is an extra field for the DTCT_LBX control.
10 | Text | Text label for DTCT_LABEL controls. For DTCT_EDIT controls this field holds the input mask. See the MAPI Programmer’s Reference for valid input masks.

Address Entry Template Binary Data shows an example of a Unicode text file for an address entry template. You can create a similar file to produce an options template. To compile an options template, call TEMPLATE.EXE with the “–M” flag, as shown in the following command.

TEMPLATE -M sourcefile destfile

where sourcefile is the Unicode file (usually with extension .WTX) and destfile is the file that will contain the compiled template.


Providing Online Help for Message and Recipient Options

The online Help file supplied with the Addr-Type object provides the user with instructions for using the gateway’s message and recipient options. It is a normal Microsoft Windows Help file. It should be made available on all Windows-based clients, but not on Microsoft Exchange Server MS-DOS clients. The MS-DOS client does not expose those options and cannot use Windows Help files.

There are no special requirements for context identifier or topic titles for this Help file. To link a property sheet to its help file, put the context identifier for the topic in the control flags field of the property sheet’s DTCT_PAGE control in its .WTX file. For example, an entry in a WTX file that looks like this:

0,  0,  0,  0,  DTCT_PAGE,  3300,  0,  0,General

specifies a property sheet called “General” that uses a help topic with the context identifier 3300.

Microsoft Exchange Server handles the details of allowing users to access the contents of this file; all you have to do is ensure that a topic with that context identifier is present in the help file specified when you install the property page. See Creating the Options Template for details.


Localizing Address Type Components

Addressing components should be translated into all languages needed by people who will be using your gateway. You should also translate the templates, message and recipient option property sheets, and online Help for your Addr-Type object because these items can be accessed by users. For address entry templates, message option templates, and recipient option templates, create one for each language. Create a separate Windows Help file for each language.

Translating template files is simply a matter of translating the fields containing text strings into the target language and recompiling those files with the TEMPLATE.EXE utility. Translating Windows Help files is a matter of translating the text in the source file and recompiling it with the Windows Help Compiler.

Each target language has a number associated with it that you will need to know when installing the translated components. For example, language 409 is English, 40C is French, 407 is German. These numbers are listed in the Win32 Software Development Kit.


Installing Addressing Objects

Installing the new address type for your gateway on Microsoft Exchange Server requires the creation of two objects on the server: the Address-Template object and the Addr-Type object. The Address-Template object includes the display table that describes the controls appearing on the dialog box for entering a new custom address. The display table is generated by the binary template file described in Address Entry Template Binary Data. The Addr-Type object has an attribute, Proxy-Generator-DLL, set to the file name of the proxy generation DLL. The Addr-Type object must be installed in order for the gateway to support its address type. The custom address template is optional for the gateway’s execution; however, it provides a friendly interface for the Administrator program user to create custom recipients for the foreign system.

To install a new address type
  1. Create the Address-Template object in the Addressing directory container.
  2. Create the Addr-Type object in the Addressing directory container.
  3. Copy the proxy generation DLL file to the Microsoft Exchange Server Address directory.

The addressing objects can be installed by using the TMPLINST.EXE and ADDRINST.EXE utilities supplied with the Microsoft Exchange Server SDK. These utilities create .CSV files necessary for batch imports to create the addressing objects.

The following example uses TMPLINST.EXE to create the Address-Template object using the PROFSADT.BLT and PROFSADT.OEL files, as described in Address Entry Template Binary Data.

TMPLINST /SITEDN=/o=microsoft/ou=apps-wga
/DISPLAY_NAME=proftmp /NAME=PROFS Address
/TYPE=PROFS /SYNTAX=c:\temp\profsadt.oel /SERVER=myserver
/MESSAGE_DT=c:\temp\profspmt.blt /RECIPIENT_DT=c:\temp\profsprt.blt
/ADDRESS_DT=c:\temp\profsadt.blt /LANGUAGE=409
/DATA16=profs16.hlp /DATA32=profs32.hlp /FILE=profs.hlp

This operation creates the directory object and uses the information in PROFSADT.OEL and PROFSADT.BLT to fill in the address syntax and address display table attributes for the Address-Template object. An installation program does not need to copy the .OEL and .BLT files into the Microsoft Exchange Server directory on the file system.

The following example uses ADDRINST to create the PROFS Addr-Type object:

ADDRINST /SITEDN=/o=microsoft/ou=apps-wga
/NAME=PROFS Proxy Generator /MACHINE=i386 /TYPE=PROFS
/PROXYDLL=\\myserver\address\PROFS\i386\proxygen.dll
/SERVER=myserver /GWPROXY=PROFS:

This utility does not copy the PROXYGEN.DLL file into the appropriate place in the Microsoft Exchange Server directory. A setup program must do that separately. For the preceding example, the directory for the DLL is

\MYSERVER\ADDRESS\PROFS\I386

The \PROFS\I386 directory will probably not exist yet on the server; the installation program creates the directory before copying the PROXYGEN.DLL file to it.

Keep in mind the following points when installing an Addr-Type object:

  • The Addr-Type object needs to be installed only once on each Microsoft Exchange Server site. The address type information is available to all servers on the site.
  • The gateway address routing table (GWART) must be rebuilt any time you add, change, or delete addressing information. This includes adding a new Addr-Type object and generating proxy addresses. Your setup program should rebuild the GWART if necessary, using the SAD_ScRunRID function.
  • It is possible to install an Addr-Type object without an associated gateway. The following diagram illustrates how this might occur.

In this scenario, both the gateway and its XXX Addr-Type object are installed at site A and are associated by the GWART at site A. Address templates and a proxy generation DLL are also associated with the XXX address type at site A. Clients at site A can see in their address books that addresses of type XXX are allowed, and they can use the address templates to create addresses of type XXX. New users on site A automatically receive proxy addresses of type XXX.

The XXX gateway is not installed at site B, so there are no address entry templates and no proxy generation DLL there. However, replication occurs between the sites, and users at site B can send mail to a type XXX address. In this case, the message will be replicated at site A and sent through the gateway to the intended recipient. A problem occurs when a new user is added at site B. This user will not receive an XXX proxy address and therefore cannot receive mail from XXX addresses. You need to install the Addr-Type object at site B so that new users there will receive type XXX proxy addresses.


Message Transfer

A gateway’s primary task is to transfer messages. Microsoft Exchange Server delivers outgoing messages to a gateway by attaching them to a special message called a message transfer envelope (MTE), and delivering them to the gateway’s MTS-OUT folder. The gateway must take the messages from the MTS-OUT folder and deliver them to the foreign system. For incoming messages, the gateway must use the information in an incoming message to create a MAPI message, which it must put in its MTS-IN folder.

The MTE provides a list of recipients to whom the gateway must deliver the message. The message is treated as an attached message object within the MTE. Your gateway must be able to process MTE information and deliver the attached messages, and also transfer several types of reports that inform message originators and recipients about message status.


Using MAPI Features

A Microsoft Exchange Server gateway is a MAPI client with access to MAPI folders, address books, message transports, and message stores. A gateway must therefore use MAPI interfaces and method to interact with Microsoft Exchange Server. Microsoft Exchange Server uses the MAPI interface to provide:

  • An information store where messaging information is kept.
  • A message transfer agent that controls how messages are sent from originators to recipients.
  • The folders that contain messages transferred to and from the gateway.


The Message Transfer Process

When Microsoft Exchange Server gives a message to a gateway, its first step is to transfer the message to the gateway for that foreign system. The gateway receives messages from its MTS-OUT folder on the server. The following procedure summarizes the basic message transfer steps for outgoing messages.

To transfer messages from the Microsoft Exchange Server information store to a gateway
  1. The information store receives a message which has an attached list of recipients.
  2. The message transfer agent (MTA) determines if any of the recipients are outside of Microsoft Exchange Server and must receive the message through a gateway.
  3. The MTA wraps the message in a message transfer envelope for delivery through the gateway.
  4. The message is delivered to the MTS-OUT folder for the gateway.

Your gateway must take messages from MTS-OUT, translate them into the foreign system format, and deliver them to their intended recipients in the foreign system.

If a recipient’s address type is not EX (the native Microsoft Exchange Server format), then the recipient is on a foreign system. In this case, Microsoft Exchange Server assigns the message to the gateway that handles the recipient’s address type.

Note The MTA continues to deliver messages to a gateway even if the gateway service is paused. This can cause messages to collect in the delivery queues and to overflow.

A message’s message transfer envelope (MTE) contains information about the recipients to whom the gateway must deliver the message. Microsoft Exchange Server puts all addresses that must be handled by the gateway into the recipient list of a message’s MTE. The properties that can be set on an MTE are described in Using Message Transfer Envelope Properties.

Because there is a separate recipient list for a message’s MTE, there are two recipient lists associated with the message — the original list that came with the message and the list on the MTE. The MTE’s recipient list is always a subset (although possibly a complete subset) of the original list. The MTE list contains only those recipients to whom the gateway must deliver the message. These recipients are called Responsibility-TRUE. The list on the message itself contains all the recipients to whom the message is addressed; some of these addresses may be for mail systems not associated with the gateway. See The Responsibility Attribute for details.


Detecting Outgoing Messages

A gateway can determine when an outgoing message arrives in its MTS-OUT folder by polling the information store periodically or by waiting for an Advise event from the information store. If your gateway uses the Advise event, it is important to note that the information store may not immediately send an Advise to the gateway when it sends a message. This is because MAPI does not immediately flush the request for the Advise. The Advise request does not become active until the cache is flushed. If your gateway uses the Advise event, you can cause the any pending Advise events to be flushed by:

  • Performing a IMAPITable::QueryRows operation on a the MTS-OUT folder’s contents table.
  • Requesting a noncached property of the MTS-OUT folder.


Message Transfer Envelopes and Attached Messages

A message transfer envelope (MTE) contains the outgoing message to be delivered as an attached object. This message object can be opened with the MAPI IMessage interface. This is the only attachment the MTE can have until the gateway calls the MAPI SetReadFlag function to indicate that it has accepted responsibility for the message. After the gateway accepts the message, it can add more attachments to the MTE if necessary.

Note For an MTE with a single attached message, the attachment number of the message is always zero. For a message with a single attachment, the number of the attachment is always zero.

Delivery reports and nondelivery reports carry the original message as an attachment if the MAPI property PR_CONTENT_RETURN_REQUESTED was set to TRUE on the original message. For more information about delivery report and nondelivery report structures, see Reports.


Handling Message Classes

A message’s message class tells a messaging application which properties a message contains, the type of information the message conveys, and how the message can be handled. Message classes are identified by the MAPI property PR_MESSAGE_CLASS on the message, and each message class has an associated set of properties. You can also create new message properties to meet your gateway’s requirements.

When Microsoft Exchange Server delivers a message to a gateway’s MTS-OUT folder, it encloses the message’s message class string in the message class string of the message transfer envelope (MTE). Gateways must always be able to handle the following message classes.

Message class | Description
ENVELOPE.{Message Class} | The MTE that contains the message. The standard message class enclosed in the MTE is IPM.NOTE.
REPORT.{Message Class}.NDR | Nondelivery report.
REPORT.{Message Class}.DR | Delivery report.
REPORT.{Message Class}.IPNRN | Interpersonal note receipt notification.
REPORT.{Message Class}.IPNNRN | Interpersonal note nonreceipt notification.

Handling a message class means being able to convert outgoing messages into an appropriate format when the foreign system has an analagous message class, and converting incoming messages to an appropriate MAPI message class. It also means being able to generate the various REPORT message classes when an incoming or outgoing message requires them.

The following figure shows an MTE and its embedded message. Note that the MTE recipient table contains the recipient address in Microsoft Exchange Server format, while the recipient table for the message contains it in SMTP format.

To deliver a report about an outgoing message
  1. The gateway creates the report message.
  2. The gateway places the report message in its MTS-IN folder.
  3. Microsoft Exchange Server delivers it to the recipient.

The details of delivering reports concerning inbound messages are clearly dependant on the foreign system’s requirements for reports.


Using Message Transfer Envelope Properties

A message transfer envelope (MTE) has all the common message properties in addition to specific MTE properties. For information about common message properties, see the MAPI Programmer’s Reference. Specific MTE properties are described in the following topics.


MTE Per-Message Properties

The following table shows the per-message properties of a message’s MTE. Many of these properties are native MAPI properties, but some are properties defined by Microsoft Exchange Server.

MTE Per-Message Properties

Property name | Type | Description
PR_ARRIVAL_TIME | Date/ Time | Date and time the message arrived at the gateway.
PR_CONTENT_SEARCH_KEY | Binary | Entry identifier of the message.
PR_FOREIGN_ID | Binary | Identifier of message within the foreign system. On outgoing messages from Microsoft Exchange Server, this property initially will not exist, but is added by the gateway.
PR_FOREIGN_REPORT_ID | Binary | Identifier assigned to the reports generated by the gateway in response to reports received from the foreign system.
PR_FOREIGN_SUBJECT_ID | Binary | Subject identifier assigned to reports generated by the gateway in response to reports received from the foreign system.
PR_MTS_ID | Binary | The Microsoft Exchange Server MTE identifier. If this property is not supplied by the gateway on incoming messages, it will be supplied by Microsoft Exchange Server.
PR_MTS_REPORT_ID | Binary | MTS identifier for reports.
PR_MTS_SUBJECT_ID | Binary | MTS identifier of the message for which a report was generated.
PR_ORIGINATOR_ADDR | String | E-mail address of message originator.
PR_ORIGINATOR_ADDRTYPE | String | Address type of message originator.
PR_ORIGINATOR_ENTRYID | Binary | Entry identifier of message originator.
PR_ORIGINATOR_NAME | String | Display name of message originator.
PR_RECIPIENT_NUMBER | Long | Index into the table of recipients.
PR_REPORT_DESTINATION_ENTRYID | Binary | Entry identifier of the immediate destination of the report.
PR_REPORT_DESTINATION_NAME | String | Display name of the immediate destination of the report.
PR_SUBJECT_TRACE_INFO | Binary | Trace information on the message report.
PR_TRACE_INFO | Binary | Trace information indicating how each messaging domain handled the message. See Gateway Trace Information for details.


MTE Per-Recipient Properties

The following table shows the per-recipient MAPI properties that are columns in an MTE’s recipient table. Depending on the direction of the transfer, either the gateway or Microsoft Exchange Server is responsible for delivering the message to every recipient in the recipient table. The MAPI methods IMessage::GetRecipientTable and IMessage::ModifyRecipients respectively read and manipulate information in the MTE’s recipient table.

In the following descriptions, ASN.1 refers to Abstract Syntax Notation, a standard for encoding symbols into binary form. See the Glossary for more information.

Per-Recipient MAPI Properties in MTE

Property name | Type | Description
PR_CONTENT_INTEGRITY_CHECK | Binary | ASN.1 content integrity check value that allows a message sender to protect message content from disclosure to unauthorized recipients.
PR_EXPLICIT_CONVERSION | Long | Indication that a message sender specifically requests a message content conversion for a recipient.
PR_IPM_RETURN_REQUESTED | Boolean | TRUE if this message should be returned with a report.
PR_MESSAGE_TOKEN | Binary | ASN.1 token for a message.
PR_NDR_DIAG_CODE | Long | Diagnostic code that forms part of a nondelivery report.
PR_NDR_REASON_CODE | Long | Reason code that forms part of a nondelivery report.
PR_NON_RECEIPT_NOTIFICATION_ REQUESTED | Boolean | TRUE if a message sender wants notification of nondelivery for a recipient.
PR_ORIGINATOR_NON_DELIVERY_ REPORT_REQUESTED | Boolean | TRUE if a message sender requests a nondelivery report for a recipient.
PR_ORIGINATOR_REQUESTED_ ALTERNATE_RECIPIENT | Binary | Entry identifier for an alternate recipient designated by the sender.
PR_PHYSICAL_DELIVERY_BUREAU_ FAX_DELIVERY | Boolean | TRUE if the messaging system should use a fax bureau for physical delivery of this message.
PR_PHYSICAL_DELIVERY_MODE | Long | Bitmask of flags defining the physical delivery mode (for example, special delivery) for a message designated for a recipient.
PR_PHYSICAL_DELIVERY_REPORT_ REQUEST | Long | Mode of a report to be delivered to a recipient upon completion of physical message delivery or delivery by the message handling system.
PR_PHYSICAL_FORWARDING_ADDRESS | Binary | Physical forwarding address of a recipient; used only with message reports.
PR_PHYSICAL_FORWARDING_ADDRESS_ REQUESTED | Boolean | TRUE if a message sender requests the message transfer agent to attach a physical forwarding address for a recipient.
PR_PHYSICAL_FORWARDING_PROHIBITED | Boolean | TRUE if a message sender prohibits physical message forwarding for a recipient.
PR_PHYSICAL_RENDITION_ATTRIBUTES | Binary | ASN.1 object identifier used for rendering message attachments.
PR_PROOF_OF_DELIVERY | Binary | ASN.1 proof of delivery value.
PR_PROOF_OF_DELIVERY_REQUESTED | Boolean | TRUE if a message sender requests proof of delivery for a recipient.
PR_RECIPIENT_CERTIFICATE | Binary | Recipient's ASN.1 certificate for use in a report.
PR_RECIPIENT_NUMBER_FOR_ADVICE | String | Recipient's telephone number to call to advise of the physical delivery of a message.
PR_RECIPIENT_TYPE | Long | MAPI_TO
PR_REGISTERED_MAIL_TYPE | Long | Type of registration used for physical delivery of a message.
PR_REPLY_REQUESTED | Boolean | TRUE if a message sender requests a reply from a recipient.
PR_REQUESTED_DELIVERY_METHOD | Long | Binary array of delivery methods (service providers), in order of a message sender's preference.
PR_SUPPLEMENTARY_INFO | String | Additional information for use in a report.
PR_TYPE_OF_MTS_USER | Long | Type of recipient, for use in a report.


Attachment Properties

The MAPI properties listed in the following table are found in an MTE attachment.

MTE Attachment Properties

Name | Type | Description
PR_OBJECT_TYPE | Long | Type of the object.
PR_ATTACH_METHOD | Long | The way the attachment contents can be accessed.


Gateway Trace Information

The PR_TRACE_INFO property stores a TRACEINFO structure containing gateway’s external trace information for a message. PR_TRACE_INFO helps a gateway or message transfer agent determine the path that a message has traveled. This information is critical for preventing message delivery loops. A TRACEINFO structure contains a set of TRACEENTRY structures in chronological order.

TRACEINFO Structure Members

Member | Type | Description
cEntries | Long | Number of TRACEENTRY structures.
rgtraceentry[ ] | TRACEENTRY | Array of TRACEENTRY structures

Each TRACEENTRY structure in the TRACEINFO structure contains the following members.

TRACEENTRY Structure Members

Member | Type | Description
lAction | Long | Routing action taken by the tracing domain. Possible actions are: expanded, redirected, relayed, and rerouted.
ftArrivalTime | Filetime | Time at which the message entered the tracing domain.
ftDeferredTime | Filetime | Time at which the tracing domain released the message.
rgchADMDName[17] | Char | ADMD name of tracing domain.
rgchCountryName[4] | Char | Country name of tracing domain.
rgchPRMDId[17] | Char | PRMD Identifier of tracing domain.
rgchAttADMDName[17] | Char | Attempted domain ADMD name. Contains information if attempt to send failed and message was rerouted.
rgchAttCountryName[4] | Char | Attempted domain country name. Contains information if attempt to send failed and message was rerouted.
rgchAttPRMDId[17] | Char | Attempted domain PRMD Identifier. Contains information if attempt to send failed and message was rerouted.

As a minimum requirement, each time a gateway submits an incoming message to Microsoft Exchange Server, it should create a TRACEENTRY containing an action, arrival time, and deferred time, as well as the country code, the Administration Management Domain (ADMD), and the Private Management Domain (PRMD) for the local domain.

If the foreign system supports similar trace information, the gateway can either translate the trace information or drop it when transferring outgoing messages to the foreign domain.

The Microsoft Exchange Server SDK provides the utility functions listed in the following table. You can use these functions to manipulate message tracing information.

TRACEINFO Utility Functions

Function | Action
HrTraceGetEntryListSize | Retrieves the size of TRACEINFO in memory, in bytes.
HrTraceGetEntryList | Retrieves the TRACEINFO for the given message.
HrTraceCreateEntryList | Creates a TRACEENTRY for the given message.
HrTraceAppendEntryList | Appends a TRACEENTRY to an existing TRACEINFO.
HrTraceSetEntryList | Sets the TRACEINFO for the given message.

The MAPI utility functions use the following structures.

Structure | Description
TRACEENTRY | Information for one trace.
TRACEINFO | Array of all TRACEENTRYs for one message.


Working with MAPI Messages and Folders

A message always has an associated recipient table, and can also have attachments and embedded messages. Embedded messages have their own PR_MESSAGE_CLASS and PR_SUBJECT properties as well as their own recipient tables. The recipient table has the MAPI properties shown in the following table for each recipient of the message.

Recipient Table Properties

Property Name | Description
PR_ADDRTYPE | Type of address, for example SMTP.
PR_DISPLAY_NAME | Recipient’s display name. For example, “John Doe.”
PR_EMAIL_ADDRESS | Recipients’s address in the format indicated by PR_ADDRTYPE. For example “johnd@microsoft.com.”
PR_ENTRYID | Entry Identifier with the Microsoft Exchange Server address book for a recipient.
PR_RECIPIENT_NUMBER | A recipient’s ordinal number in the recipient list.
PR_RECIPIENT_TYPE | Recipient type, MAPI_TO.
PR_SEND_RICH_INFO | Recipient is a MAPI recipient.

Note A gateway must always check the recipient table of the embedded MAPI message to find the correct value for the PR_SEND_RICH_INFO property. A message sent to a one-off address through a gateway does not carry this property on its MTE.

MAPI Folders use the IMAPIFolder interface. IMAPIFolder presents methods for accessing a table of messages contained in the folder, and manipulating the contents of that table and its messages.

The following topics discuss working with MAPI messages and folders. For more complete details, see the MAPI Programmers’ Guide. Keep in mind that gateways are a special kind of client application, and as such not all of the information on this subject in the MAPI documentation is directly applicable to gateways.


Accessing Messages in the MTS-IN and MTS-OUT Folders

To put incoming messages into the MTS-IN folder, you need to call the following MAPI methods:

  • IMAPIFolder::CreateMessage, to create a new MAPI message that will hold the data from the incoming message.
  • IMessage::CreateAttach, to hold any attachments on the incoming message.
  • IMAPIProp::OpenProperty, to open various message properties that your gateway will need to modify.
  • IMAPIProp::SetProps, to modify one or more property values.
  • IMessage::ModifyRecipients, to modify the recipient list on the new MAPI message.
  • IMAPIProp::SaveChanges, to make the above changes permanent in the new message.
  • IMessage::SubmitMessage, to save the message to the folder and mark it as ready to be delivered.

To read outgoing messages from the MTS-OUT folder, you need to call the IMAPIFolder::GetContentsTable, to access the table of messages (MTEs) present in the folder.

  • IMAPITable::QueryRows (or the Microsoft Exchange Server function HrQueryAllRows), to retrieve one or more rows from the table.
  • IMAPIContainer::OpenEntry, to access a particular MTE in the folder.
  • IMessage::GetRecipientTable, to find out what addresses the message attached to the MTE should be delivered to.
  • IMessage::GetAttachmentTable, to find the message attached to the MTE.
  • IMAPIProp::GetProps, to read the subject, message class, contents, etc., of the outgoing message.

For details about these functions, see the MAPI Programmer’s Reference. For examples of calling these functions, see the sample code for GWSAMPLE.C in the \BKOFFICE\SAMPLES\EXCHANGE\GWSAMPLE directory.


Using MAPI Folders

A Microsoft Exchange Server gateway uses the MAPI folders MTS-IN and MTS-OUT to submit messages to and receive messages from Microsoft Exchange Server. You can also design your gateway so it uses other MAPI folders to store messages while it processes them. Each MAPI folder has a contents table. The contents table for a folder created by a gateway will contain:

  • One row for each message contained within the folder.
  • Default content properties defined by MAPI in each row.


Message Properties to Show in Folders_

You can change the set of properties that are displayed in your gateway’s folder contents table by using the MAPI IMAPITable::SetColumns table function. Refer to the MAPI Programmer’s Reference for details on using this function. A suggested set of properties to display in a folder contents table is shown in the following table.

Suggested Folder Contents Table Properties

Property name | Type | Description
PR_ARRIVAL_TIME | Date/Time | Date and time that the message arrived at the gateway.
PR_ENTRYID | Binary | Entry identifier of the message within the folder.
PR_FOREIGN_REPORT_ID | Binary | Foreign message identifier of this report. Exists only for reports.
PR_FOREIGN_ID | Binary | Foreign message identifier of this message. Does not exist for reports.
PR_MESSAGE_CLASS | String | Message class.
PR_MESSAGE_FLAGS | Long | Contents of bits 16 – 31 for application use.
PR_MESSAGE_SIZE | Long | Message size.
PR_MTS_ID | Binary | MTS-ID of this message. Does not exist for reports.
PR_MTS_REPORT_ID | Binary | MTS-ID of this report. Exists only for reports.
PR_ORIGINATOR_ NAME | String | Display name of originator. Does not exist for reports.
PR_PRIORITY | Long | Message priority. Does not exist for reports.
PR_REPORT_DESTINATION_NAME | String | Display name of report destination. Exists only for reports.
PR_SEARCH_KEY | Binary | Message identifier.
PR_SUBJECT | String | Subject of the message or report.

You can use the MAPI IMAPITable::SortTable function to specify how entries in your gateway’s contents table are to be sorted. You can order the messages in a folder by any property in the folder contents table; for example, priority, arrival time, or size. This is useful if you want to allow Microsoft Exchange Server administrators to prioritize message processing based on particular properties.


Message Properties Indicating Transfer Status

PR_MESSAGE_FLAGS is one of the common message properties that indicate the current state of the message as set by the IMAPIProp::SetProps method (not the IMAPIProp::SaveChanges method). The following table defines the message states represented by the bits of PR_MESSAGE_FLAGS.

Interpretation of PR_MESSAGE_FLAGS Bits

Bit | Constant | Meaning
0 | MSGFLAG_READ | If set, indicates that the message has been transferred because the gateway has taken responsibility for the message. Applies only to outgoing messages. This flag is set by calling the IMessage::SetReadFlag method.
1 | MSGFLAG_UNMODIFIED | If set, indicates that the message has not been modified since being received.
2 | MSGFLAG_SUBMIT | If set, indicates that the message is marked for transfer to the Microsoft Exchange Server system because the IMessage::SubmitMessage function has been called for this message.
3 | MSGFLAG_UNSENT | If set, indicates that the message is being created.
4 | MSGFLAG_HASATTACH | If set, indicates that the message has at least one attachment.
5 – 31 |  | Reserved. Do not change.


Submitted Message Properties

Messages passing through your gateway may have properties in addition to the common message properties. The following table shows optional properties for a submitted message and indicates actions that your gateway should take when handling messages with these properties.

Optional Submitted Message Properties

Property name | Type | Description
PR_DELETE_AFTER_SUBMIT | Boolean | If present and set, indicates that the server should delete the message after submission.
PR_SENTMAIL_ENTRYID | Binary | Entry identifier of the folder where a copy of the message should be placed after it has been successfully submitted to an underlying messaging system. If zero-length, it indicates that no sent mail copy should be made. If this property does not exist, sent mail behavior is governed by the profile configuration.

A gateway uses the MAPI IMessage::SubmitMessage method to submit a message to Microsoft Exchange Server. When Microsoft Exchange Server takes responsibility, the following actions will occur:

  • If the PR_DELETE_AFTER_SUBMIT property is set, the information store deletes the message. Gateways typically set this property so that their MTS-IN folders do not accumulate large numbers of messages.
  • If the PR_SENTMAIL_ENTRYID property is set, the information store copies the message to the indicated folder. Gateways can use this property to implement archiving features.

A gateway uses the MAPI IMessage::SetReadFlag method when it accepts responsibility for delivering a message to the foreign system. After the gateway has called this function, Microsoft Exchange Server cannot time-out the message.


Using Incoming and Outgoing Message Folders

When a gateway is installed, the MTS-OUT and MTS-IN folders are automatically and permanently created. MTS-OUT holds messages coming into the gateway from Microsoft Exchange Server, while MTS-IN holds messages going out to Microsoft Exchange Server. Both folders store messages in Microsoft Exchange Server format.

Note For best performance, use the MTS-IN folder to create messages going into Microsoft Exchange Server, rather than creating the messages in another folder and transferring them to MTS-IN.

MTS-OUT and MTS-IN are automatically created. You can create additional folders for your gateway to use in managing the message transfer. The following figure shows an example of a message transfer design.

Sample message transfer design

This sample design includes the MTS-OUT and MTS-IN folders, both storing messages in Microsoft Exchange Server format, and the following additional folders storing messages in the foreign system format:

  • An incoming message folder that receives messages from the foreign system and receives translated messages from the MTS-OUT folder.
  • An outgoing message folder that receive messages from the gateway to be delivered to the foreign system.

An incoming message folder is useful because it provides a place for the gateway to hold incoming messages if it cannot process them right away. Without an incoming message folder the gateway must process all incoming messages immediately, which can create performance or memory subsystem problems.

Incoming and outgoing message folders are also particularly useful if the gateway cannot remain connected to the foreign system all the time. For example, a UUCP-based (UNIX-to-UNIX Copy Protocol) gateway could cache outgoing messages that it has already translated in an outgoing message folder and then send them all in one batch when it can next connect to its UUCP host. Similarly, it would at that time receive a batch of incoming messages from the UUCP host that it could store in an incoming message folder for later sequential processing.

Additionally, gateways with flexible or dynamic routing to various remote addressing domains can use multiple outgoing message folders to hold outgoing messages bound for different domains. A gateway could also use multiple inbound message folders in this situation, although there is no particular benefit to doing so over storing all incoming messages in a single incoming message folder.


Limiting Unread Messages in the Gateway

Messages entering the gateway are transferred from the Microsoft Exchange Server to the gateway’s MTS-OUT folder in the server’s information store. The server limits the maximum number of unread messages in all the gateway’s MTS-OUT folders in the following way:

  • It tracks the total number of unread messages (messages that have not had the IMessage::SetReadFlag function invoked) in all gateway folders.
  • If the unread message total reaches the value in the MDB-Unread-Limit field of the gateway object, the server does not transfer additional messages to the gateway.
  • After the limit has been reached, the server waits an amount of time specified in the MDB-Backoff-Interval field of the gateway object, before checking the number of unread messages in the receive folders, and continues waiting if the limit is still exceeded.

The information store transfers messages from an message transfer queue in the MTA to the information store for a gateway only when that gateway is logged on. To prevent messages from being stranded in the receive folder of an unresponsive gateway, a timer event is associated with each message that is transferred from the MTA to the information store. If this timer event is triggered, the information store returns a nondelivery report to the originator with the reason-code set to MAPI_REASON_TRANSFER_IMPOSSIBLE and the diagnostic-code set to MAPI_DIAG_MAXIMUM_TIME_EXPIRED. It then removes the message from the folder.

A gateway cancels the timer event on a message by invoking the IMessage::SetReadFlag function on the message object. It does this by moving the message out of the receive folder or by copying the message. Before the timer is canceled, the message can be deleted by the information store at any time to invalidate the message object.

The information store uses the Time-Out-Period field in the gateway object to set the timer on each message transferred from the message transfer queue to the information store. When a nondelivery report is generated by a time-out, these properties are not returned:

  • Properties added to a message and not saved with the IMAPIProp::SaveChanges function.
  • Gateway-specific properties added to an MTE for internal use by the gateway.

A gateway may not add additional attachments to an MTE until after the timer has been canceled. This enables the information store to identify the original message content if a nondelivery report needs to be generated because of message time-out.


Preserving Foreign System Message Information

In some cases the information provided by the foreign system must be preserved in a MAPI message when messages are transferred through a gateway. Examples of information that may need to be preserved are trace information, message headers, and correlation identifiers.

The MAPI PR_TRANSPORT_MESSAGE_HEADERS property holds the message headers of the foreign message. If the foreign message is in the process of being automatically forwarded and is sent back to the gateway, these headers need to be added back into the message. Dropping the header information can result in a message loop.


Mapping Message Identifiers

It is important to keep track of the various identifiers that are assigned to a message as it is transferred between Microsoft Exchange Server and a foreign system. These identifiers are used to monitor the message’s progress and to construct delivery and nondelivery reports that must be able to reference the original message identifier at any point along the message path. Message identifiers created in one system may not be usable in another because of incompatible formats.

A message can have up to four different identifiers during the transfer process. These are:

  • A MAPI message identifier for the message content.
  • A MAPI message identifier for the MTE.
  • A Microsoft Exchange Server message identifier (PR_MTS_ID).
  • A foreign system message identifier (PR_FOREIGN_ID).

The PR_MTS_ID and PR_FOREIGN_ID properties of all transferred messages are recorded by the Microsoft Exchange Server Administrator program in the accounting and audit log. The gateway stores all transferred messages for a specific length of time that is defined by the Administrator program. This allows the gateway to construct complete delivery and nondelivery reports.


Message Identifier Tracking for Outbound Messages

The following topics discuss message identifier tracking when a message is transferred from Microsoft Exchange Server to a foreign system and when a delivery or nondelivery report is returned from the foreign system to Microsoft Exchange Server. It is important to track message identifiers so that useful debugging information ends up in the Microsoft Exchange Server Administrator error logs, so message loops can be avoided, and so users can receive proper reports about a message.

There are several steps in this process:

  1. The client application creates a new message and submits it to the server.
  2. The server transferrs the message to a gateway.
  3. The gateway translates the message to the foreign system’s message format and submits it to the foreign system.
  4. The foreign system sends a report back to the gateway. Note that this may happen a long time after the gateway sends the message which triggered the report.
  5. The gateway translates the report into a MAPI message and submits it to the server.
  6. The server delivers the report to the user who sent the original message.


Client to Microsoft Exchange Server Message Transfer

The following steps are performed when a message is transferred from a client to Microsoft Exchange Server:

  1. When a client creates a message, MAPI assigns the PR_SEARCH_KEY message identifier.
  2. When the message is submitted to Microsoft Exchange Server, the PR_SEARCH_KEY property’s value is also maintained in the message’s PR_CONTENT_ID and PR_CONTENT_CORRELATOR properties.
  3. Microsoft Exchange Server creates a new message identifier and stores it in the message’s PR_MESSAGE_SUBMISSION_ID property.


Microsoft Exchange Server to Gateway Message Transfer

When a message is transferred from Microsoft Exchange Server to the gateway, the following steps are performed:

  1. A new MAPI message, the MTE, is created.
  2. Microsoft Exchange Server copies the value of the PR_MESSAGE_SUBMISSION_ID property from the outgoing message to the MTE’s PR_MTS_ID property.
  3. Microsoft Exchange Server stores the outgoing message’s PR_SEARCH_KEY identifier in the MTE’s PR_CONTENT_SEARCH_KEY property.


Gateway to Foreign System Message Transfer

The following steps are performed when the gateway transfers a message to the foreign system:

  1. The gateway assigns a foreign message ID and stores it in the MTE’s PR_FOREIGN_ID property.
  2. The gateway stores the MTE in a folder so it can be retrieved later for report correlation purposes.
  3. The gateway creates an entry in the tracking log containing the PR_MTS_ID and PR_FOREIGN_ID properties from the MTE.

    Typically, a tracking event entry is made each time the message is transferred to the foreign system so that transfer time can be logged (a single message may be transferred multiple times if it has multiple recipients).

If the foreign system generates a report, it typically returns the foreign message ID for the original message. The gateway should store the foreign message ID in the PR_SUBJECT_TRACE_INFO property of the report. If the foreign system does not provide this level of report correlation, the gateway should attempt to identify the original message.


Foreign System to Gateway Report Transfer

The following steps are performed when the foreign system transfers a delivery or nondelivery report to the gateway:

  1. When the gateway receives a report from the foreign system, it creates a MAPI report which is assigned a PR_SEARCH_KEY.
  2. The gateway looks up the original message by matching the foreign report’s message ID with the PR_FOREIGN_ID property values of the gateway’s archived messages. The foreign report’s message ID should be the same as the message ID originally generated by the gateway for the outgoing message.
  3. The gateway assigns the gateway report PR_PARENT_KEY, PR_FOREIGN_SUBJECT_ID, and PR_MTS_SUBJECT_ID properties from identifiers in the original message. (PR_FOREIGN_SUBJECT_ID could also be assigned from the foreign report if the report carries such information.)
  4. The gateway report’s PR_FOREIGN_REPORT_ID is assigned from the foreign report’s report ID.


Gateway to Microsoft Exchange Server Report Transfer

The following steps are performed when the gateway transfers a report to Microsoft Exchange Server:

  1. Microsoft Exchange Server creates a new MTS report with and assigns it a report ID.
  2. Microsoft Exchange Server copies the report ID to the gateway report’s PR_MTS_REPORT_ID property for auditing purposes.
  3. Microsoft Exchange Server copies the gateway report’s PR_MTS_SUBJECT_ID to the MTS report’s subject ID, and the gateway report’s PR_PARENT_KEY to the MTS report’s PR_CONTENT_CORRELATOR property.


Microsoft Exchange Server to Client Report Transfer

The following steps are performed when Microsoft Exchange Server transfers a report to the client:

  1. A new PR_SEARCH_KEY is created for that report.
  2. The PR_PARENT_KEY of the MAPI report is assigned the PR_CONTENT_CORRELATOR property from the MTS report.


Message Identifier Tracking for Inbound Messages

The following topics discuss message identifier tracking when a message is transferred from a foreign system to Microsoft Exchange Server and when a delivery or nondelivery report is returned from Microsoft Exchange Server to the foreign system.

There are several steps in this process:

  1. The gateway receives a message from the foreign system.
  2. The gateway translates the message into a MAPI message and delivers it to the server.
  3. The server delivers the message to the recipient.
  4. The server generates a report and delivers it to the gateway
  5. The gateway translates the report to the foreign system’s format and delivers it to the foreign system.


Foreign System to Gateway Message Transfer

The following steps are performed when the foreign system transfers a message to the gateway:

  1. The foreign system assigns a message ID to the message being transferred.
  2. The gateway creates:
    • A MAPI message (the content message) to contain the content of the incoming message.
    • An MTE message to contain the content message.
  3. The MAPI message identifier of the content message is assigned to the MTE’s PR_CONTENT_IDENTIFIER property.
  4. The message ID from the incoming message is assigned the MTE’s PR_FOREIGN_ID property.
  5. If the gateway builds a delivery or nondelivery report, the PR_FOREIGN_SUBJECT_ID property from the MTE is assigned to the subject ID of the report.


Gateway to Microsoft Exchange Server Message Transfer

The following steps are performed when the gateway transfers a message to Microsoft Exchange Server:

  1. Microsoft Exchange Server creates a new MTS message and assigns it a message ID. It also assigns the same message ID back to the PR_MTS_ID of the message the gateway delivered to its MTS-IN folder.
  2. The PR_CONTENT_CORRELATOR and PR_CONTENT_IDENTIFIER properties in the MTS envelope are assigned from the gateway transfer envelope’s PR_CONTENT_IDENTIFIER.


Microsoft Exchange Server to Client Message Transfer

The following steps are performed when Microsoft Exchange Server transfers the message to a client:

  1. A MAPI message is created.
  2. The PR_SEARCH_KEY property is assigned the value of the PR_CONTENT_IDENTIFIER property contained within the MTS transfer envelope.


Microsoft Exchange Server to Gateway Report Transfer

The following steps are performed when Microsoft Exchange Server transfers a delivery or nondelivery report to the gateway:

  1. The value of the PR_CONTENT_CORRELATION property of the original message is returned with the report.
  2. A new MAPI message is created in the gateway’s MTS-OUT folder for the report, and a PR_SEARCH_KEY is created for it.
  3. The report’s PR_MTS_REPORT_ID, PR_PARENT_KEY, and PR_MTS_SUBJECT_ID properties are assigned the values of the PR_MTS_REPORT_ID, PR_CONTENT_CORRELATION, and PR_MTS_SUBJECT_ID from the Microsoft Exchange Server report, respectively.
  4. The gateway finds the original message by matching the report’s PR_MTS_SUBJECT_ID property with the PR_MTS_ID properties of its archived messages.
  5. The gateway assigns the PR_FOREIGN_SUBJECT_ID property’s value from the PR_FOREIGN_ID property in the original message.


Gateway to Foreign System Report Transfer

The following steps are performed when the gateway transfers a report to the foreign system:

  1. When a report is created in the foreign system, a foreign Report-ID is assigned.
  2. The gateway stores the foreign Report-ID in the gateway report’s PR_FOREIGN_REPORT_ID.
  3. The Subject-ID of the foreign report is assigned from the gateway report’s PR_FOREIGN_SUBJECT_ID.
  4. When the report has been transferred to the foreign system, the gateway creates an entry in the accounting and audit log containing the PR_MTS_REPORT_ID, PR_FOREIGN_REPORT_ID, PR_MTS_SUBJECT_ID, and PR_FOREIGN_SUBJECT_ID.

The gateway does not need to save a copy of the report; no further correlation will be required because reports must never generate further reports.


Transport Neutral Encoding Format

Transport Neutral Encoding Format (TNEF) provides a standard method for passing both textual and binary message data. In this method, TNEF encapsulates MAPI properties not supported by an underlying messaging system into a binary stream that can accompany a message through transports and gateways. The target transport can then decode the encapsulation to retrieve all the properties of the original message.

Because a message consists of MAPI properties, your gateway can use TNEF to encapsulate the message properties into a binary stream. This stream can then be attached to an outbound message for transfer by the gateway. A gateway must be able to determine whether an attachment is a TNEF attachment.

You can use TNEF when you want to create extra MAPI properties (for example, in a custom message class) and put these extra properties into an attachment. You can also attach multiple messages to each other in a form that the foreign system understands. Using TNEF lets you transmit messages with more complex formats, such as rich text.

When mapping addresses, first determine whether any of the Responsibility-TRUE recipients are TNEF. The Boolean MAPI property PR_SEND_RICH_INFO indicates whether the recipients can use TNEF. Send all TNEF recipients a separate message containing the TNEF attachment.

Note Do not include reports in TNEF attachments.

TNEF attachments can be included in or excluded from the TNEF stream. Excluded attachments must have unique names. TNEF generates a tagged form of the message text that is used on inbound processing to recover attachment positions.

For detailed information about TNEF, see the MAPI Programmer’s Reference.


Message Translation

Message translation is the process by which a gateway converts between MAPI’s message format and the message format of the foreign system that the gateway serves, for both incoming and outgoing messages. This translation is done on the basis of the message class of incoming and outgoing messages.

Translation has to be done on the basis of message class because different MAPI message classes support different sets of properties. This means there cannot be one algorithm for converting a MAPI message into the foreign system’s message format. Similarly, if the foreign system’s message format supports its own concept of message classes, then separate translation algorithms are necessary to handle the message classes defined in the foreign system. If the foreign system does not have a concept of message classes, you can choose a a constant string for the gateway to use as the message class of incoming messages.

The Microsoft Exchange Server SDK provides a framework for message translation that gateways use. Gateways enter as many translation DLLs as they need into the Windows NT Registry so that the appropriate translation program is called when the gateway needs to translate each incoming or outgoing message. When developing your gateway, you must also provide these translation DLLs. A translation DLL is considered appropriate for a message if the message class string supported by the DLL is a proper prefix of the message class string of the message to be translated. If more than one DLL is applicable to a particular message, the one with the closest matching message class string is used.

There are two primary advantages of this approach over embedding translation code directly in your gateway. One is that you may change the translation code or add new translations without recompiling the gateway. The other is that translation DLLs may be added or changed while a gateway is running.


Translating Messages Using a Translation DLL

At some point during processing of incoming or outgoing messages, the gateway must call the message translation framework to translate the message to the appropriate format. Typically this happens after the gateway determines that it can in fact process the message. Most gateways do some minimal verification of the input message, such as determining that it can parse the destination addresses, before calling the translation framework. If it determines that it cannot process a message, a gateway can reject the message and return an error report without ever calling the translation framework.

The gateway program calls the translation framework using the functions shown in the following table.

Function | Action | When called
HrConvInitGlobals | Initializes common data areas. | When the gateway starts.
HrConvInitInstance | Creates a new instance of the translation framework. Each instance is single-threaded. Multiple instances can be used in separate threads. | When new thread is created to perform translations.
HrConvConvert | Performs a conversion. | When each message is translated.
HrConvUninitInstance | Disposes of a previously allocated translation framework instance. | When a translation thread exits.

If HrConvConvert returns an error, or the gateway cannot otherwise convert the message, it should return a non-delivery report to the sender.


Translating Attachments

Gateways call the HrConvConvert function to translate messages. However, they can also use it to convert attachments. Because translation DLLs are not restricted to operating on message objects, you can define separate translation phases for attachments in the same way that you can use multiple translation phases for messages. The translation environment for an attachment should include the gateway name, the message type, and the attachment type. See HrCnvQueryCapability for details on translation phases and translation environments.


Required Translation DLL Functions

Every translation DLL must have the following functions.

Entry Point | Purpose
HrCnvConvert | Performs the translation
HrCnvQueryCapability | Determines whether the translation DLL can translate a particular message class
HrGetExportVector | Returns a vector of pointers to the HrCnvConvert and HrCnvQueryCapability entry points.

These functions are called at appropriate times by the message translation framework, usually in response to a gateway’s call to the framework’s HrConvConvert function.

Function parameters and return values for these entry points, as well as function prototypes, are in the EDK.H header file. All translation DLLs should include this file.


HrGetExportVector

The HrGetExportVector function simply returns a list of the other entry points in the DLL. The HrGetExportVector function can simply return the address of a static CONVDLLVECT structure, such as:

static CONVDLLVECT sExportedFuncs =
{
    1,                       // version number 1
    HrCnvQueryCapability,    // address of query capability function
    HrCnvConvert             // address of translation function
};

HrGetExportVector is the only function in the DLL that must be an entry point. The other functions must exist in the DLL, but do not have to be entry points because pointers to them are returned by HrGetExportVector.

Note that the entry point names in the .DEF file for a translation DLL are not required to have any particular value. Because the translation framework uses Windows NT Registry keys to locate the entry point names for translations, you can put multiple translations in a single translation DLL. Each translation in a DLL consists of an entry point which is the HrGetExportVector function for that translation, plus the corresponding HrCnvQueryCapability and HrCnvConvert functions, although clearly there is no requirement that your implementations of those functions use those function names. See Installing a Translation DLL for details about how Windows NT Registry keys are used to specify the entry point names for the HrGetExportVector functions within a translation DLL.

The IPM_IN and IPM_OUT sample translation DLLs, located in the \BKOFFICE\SAMPLES\EXCHANGE directory, contain examples of HrGetExportVector functions, as well as their definitions in the .DEF files for the DLLs.


HrCnvConvert

The HrCnvConvert function performs the actual translation between message formats. When called, this function will be passed pointers to the object to be translated and to a stream object which HrCnvConvert should write the results of the translation to.

Translating outgoing messages means using MAPI calls to retrieve the relevant properties of the outgoing message and writing their values to the output stream in whatever format is appropriate for the foreign system. Translating incoming messages means interpreting the incoming message’s data (often just a stream of bytes) and writing the data to properties on the output message.

The IPM_IN and IPM_OUT sample translation DLLs, located in the \BKOFFICE\SAMPLES\EXCHANGE directory, contain examples of HrCnvConvert functions for converting RFC-822 messages (Internet style SMTP messages) to and from MAPI messages.


HrCnvQueryCapability

The HrCnvQueryCapability function returns an HResult indicating whether the translation DLL’s HrCnvConvert function can handle a particular message. The function receives a pointer to the message to be translated, a pointer to the message class of the message, and a pointer to the environment of the translation. The function returns a BOOL indicating whether it can or cannot translate the message.

For outgoing messages, the important factor is usually the message class of the outgoing message. For incoming messages, this function may need to analyze some or all of the input message’s header or other delivery information to determine whether the message can be translated by the DLL’s HrCnvConvert function.

The environment of the translation is a string of the form GatewayName.PhaseName, such as “fax.phase2”. This allows for gateways whose requirements demand that translation take place in more than one phase. Most gateways will only need one phase and will thus have a constant string for their environment. If your gateway requires multiple phases to translate some particular message class, you must provide separate translation DLLs for each combination of message class and translation phase; consequently, HrCnvQueryCapability should return FALSE if the DLL’s environment or the message class does not match the input message or environment.

The IPM_IN and IPM_OUT sample translation DLLs, located in the \BKOFFICE\SAMPLES\EXCHANGE directory, contain examples of HrCnvQueryCapability functions both for incoming RFC-822 messages, and for outgoing MAPI messages.


Installing a Translation DLL

All translations are registered through the Windows NT Registry, in subkeys stored under the key HKEY_LOCAL_MACHINE\Software\Classes\MAPI Conversions.

The MAPI Conversions key has a subkey for each translation DLL. The DLL subkey name must be a relative name, so these DLLs must be installed in the SYSTEM32 directory of the machine running the gateway.

Each DLL key name contains a subkey for each conversion within the DLL. These subkeys represent the various HrGetExportVector entry points in a translation DLL that the conversion engine can use to load the conversion.

Each subkey has the following set of values.

Subkey | Required | Type | Description
Classes | Yes | REG_MULTI_SZ | Message Class strings supported by this entry point.
Point | Yes | REG_SZ | Translation phase for this entry point.
Options | No | REG_SZ | Options that will be passed to the entry point.

The sample gateway creates the following registry entries for the IPM_IN and IPM_OUT sample translation DLLs:

HKEY_LOCAL_MACHINE\Software\Classes\MAPI
    Conversions\ipm_in.dll\GetTrivialVector
        Classes = ENVELOPE.IPM REPORT.IPM
        Point = SAMPLEGW.INBOUND
        Options =
HKEY_LOCAL_MACHINE\Software\Classes\MAPI     Conversions\ipm_out.dll\GetTrivialVector
        Classes = ENVELOPE.IPM REPORT.IPM
        Point = SAMPLEGW.OUTBOUND
        Options =

The Point key is used if a translation DLL needs to be called at different phases of the messages transit through the gateway. For example, the conversion DLL might be called once with Point = STARTING, then again with Point = ENDING. See HrCnvQueryCapability for details.


Samples Translation DLLs

Sample Translation DLLs

Several sample translation DLLs are available in the Microsoft Exchange SDK, in the SAMPLES\EXCHANGE\ directory.

Source File | Function | Subdirectory
IPM_IN.CPP | Translates RFC-822 messages into MAPI messages | IPM_IN
IPM_OUT.CPP | Translates MAPI messages into RFC-822 messages | IPM_OUT
TNEFDEC.C | Decodes a TNEF copy of the message from an embedded message | XLATCONV
TNEFENC.C | Adds a TNEF copy of the message as an attachment | XLATCONV
TOUPPER.C | Places message text in an attachment | XLATCONV
TRIVIAL.C | Simplest possible message converter | XLATCONV

You can use these conversions as examples for designing conversions for your gateway. You must design the input and output formats of the conversions for your gateway. The Microsoft Exchange Server conversion framework passes two void pointers through the conversion. These pointers can point at anything; typically you use them to point at the files from which your gateway creates input messages and to which it writes output messages. You need to document the use of these pointers so that third parties can develop conversions for your gateway.


Reports

Microsoft Exchange Server gateways generate reports to inform message originators of the success or failure of message delivery and receipt. Four classes of reports are supported:

  • Delivery Reports
  • Nondelivery Reports
  • Read Receipts
  • Nonread Receipts

A gateway should always generate non-delivery reports when messages cannot be delivered. Successful delivery reports are optional.

Users can request reports and receipts by users on a per-message basis. Gateways should inspect outgoing messages for the following MAPI properties to determine whether reports and receipts have been requested for the message:

PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED

PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED

PR_READ_RECEIPT_REQUESTED

PR_NON_RECEIPT_NOTIFICATION_REQUESTED

Note The PR_NON_RECEIPT_NOTIFICATION_REQUESTED property corresponds to a request for a non-read receipt.

All reports should conform to the minimum required content and semantics of the X.400 specification. Content and functionality beyond that required by X.400 is optional. For example, nondelivery reports often include the original message content even though it is not required by the X.400 specification; if the original message content is present in a nondelivery report, the user can fix addressing problems and resend the message. Places where reports and receipts for Microsoft Exchange Server are different from the X.400 standard are discussed in Deviations from the X.400 Standard.


Delivery Reports

A delivery report is a MAPI message whose message class string is REPORT.X.DR, where X is the message class string of the original message, such as REPORT.IPM.Note.DR. A delivery report should give as much information as possible about the delivery of the original message. What is possible depends on the foreign system and what sort of delivery reports it supports. Delivery reports can be generated by calling the MAPI method IMAPISupport::StatusRecips.

If the foreign system does not support delivery reports, then your gateway can generate a delivery report when it successfully transfers responsibility for a message to the foreign system. Such a report can do no better than to indicate to the sender that the foreign system accepted the message.

If the foreign system supports some explicit form of delivery reports, then the gateway should wait for a delivery report from the foreign system before generating a delivery report to deliver to the original message’s sender. Such a report should pass on as much information as possible from the foreign system’s delivery report.

For details about delivery reports, see Required Report Message Properties and IMAPISupport::StatusRecips in the MAPI Programmer’s Reference.


Nondelivery Reports

A gateway should generate nondelivery reports whenever message delivery fails. The nondelivery report is returned to the original sender. There are several reasons why message delivery can fail:

  • Address mapping can fail. This means the gateway is unable to find or generate an address for a responsibility-true recipient to which it can deliver the message.
  • The gateway is unable to connect to the foreign system. Typically a gateway will make several attempts at regular intervals before deciding that a message cannot be delivered.
  • The gateway delivers the message to the foreign system, but the foreign system returns it as undeliverable. This can happen if the recipient’s address does not exist in the foreign system, or if local problems in the foreign system prevent delivery.

Like delivery reports, nondelivery reports can be generated by calling the MAPI method IMAPISupport::StatusRecips. Since nondelivery reports are so important, however, you may want your gateway to generate its own nondelivery reports (messages with the message class REPORT.IPM.Note.NDR). A Microsoft Exchange Server nondelivery report should contain at least the following elements:

  • Nondelivery report envelope--the report message itself.
  • Nondelivery report failed recipient list
  • Original message
  • Original message recipient list

The original message and its recipient list are included in the nondelivery report as an embedded message attachment. The properties for the envelope and failed recipient list are described in Nondelivery Report Envelope Properties and Nondelivery Report Failed Recipient List Properties.

The remaining topics in this section present information necessary to generate well-formed nondelivery reports.


Nondelivery Report Properties

The following table shows the MAPI properties of nondelivery reports, and how these properties relate to the properties of the original message.

Nondelivery Report Property | Original Message Property
PR_REPORT_DESTINATION_NAME | PR_SENDER_NAME, PR_REPORT_NAME
PR_REPORT_DESTINATION_ENTRYID | PR_SENDER_ENTRYID, PR_REPORT_ENTRYID
PR_MTS_SUBJECT_ID | PR_MTS_ID
PR_DISPLAY_NAME | PR_DISPLAY_NAME
PR_ADDRTYPE | PR_ADDRTYPE
PR_EMAIL_ADDRESS | PR_EMAIL_ADDRESS
PR_SEARCH_KEY | PR_SEARCH_KEY
PR_ENTRYID | PR_ENTRYID
PR_DISCRETE_VALUES | Used for distribution lists with nondelivered members.
PR_ORIGINAL_DISPLAY_NAME | Used for a nondelivered member of a distribution list.
PR_ORIGINAL_ENTRYID | Used for a nondelivered member of a distribution list.

For details about the properties on reports, see the topic Required Report Message Properties in the MAPI Programmer’s Guide.


Nondelivery Report Envelope Properties

The envelope is a MAPI message that contains the following properties.

PR_MESSAGE_CLASS

PR_MESSAGE_CLASS is used for the message class. This property should be in the form REPORT.X.NDR, where X is the message class of the original message. If the original message is unavailable, this property should be set to REPORT.IPM.Note.NDR.

PR_REPORT_DESTINATION NAME and PR_DESTINATION_ENTRY_ID

PR_REPORT_DESTINATION NAME and PR_DESTINATION_ENTRY_ID are address properties for the recipient of the nondelivery report. These properties should always be available on the original message. If the original message is unavailable, they can be determined through the same mechanism that the gateway uses to map recipient addresses on incoming mail, such as proxy address lookup.

Microsoft Exchange Server reports can only be sent to a single recipient. If a gateway receives a nondelivery report that must go to multiple recipients, the gateway must create and submit several messages.

PR_MTS_SUBJECT_ID

PR_MTS_SUBJECT_ID is used for the Message Transfer System (MTS) identifier from the original message. In the X.400 model, a message is given an MTS identifier when it enters the MTS for delivery. When a Microsoft Exchange Server message is submitted to a gateway, the MTS identifier is written into the message’s PR_MTS_ID property.

If the original message and its envelope are available when a nondelivery report is created, the PR_MTS_SUBJECT_ID property on the report should be copied from the PR_MTS_ID property of the original message.

If the original message and its envelope are unavailable, there are two alternatives:

  • The PR_MTS_ID value from the original message can be saved through some other mechanism such as a database local to the gateway.
  • A value for PR_MTS_SUBJECT_ID on the report can be invented. To successfully send a Microsoft Exchange Server nondelivery report, PR_MTS_SERVER_ID must have the correct format, but the actual content is not validated.

PR_MTS_SUBJECT_ID is a binary MAPI property that it must contain a null-terminated string. The data pointer of a PR_MTS_SUBJECT_ID SPropValue structure must point to a null-terminated string and the byte count must include the terminating null.

The correct format for PR_MTS_SUBJECT_ID is:

c=country name;a=ADMD name;p=PRMD ID;l=local ID\0

where the parameters can be anything that meets the requirements for X.400 MTS identifiers.

An invented value for PR_MTS_SUBJECT_ID should contain a reasonable approximation of true MTS ID values. The gateway can obtain correct values for country name, ADMD name, and PRMD ID in several ways:

  • Read them from the gateway’s Mail-Gateway directory object.
  • Extract them from the gateway’s X.400 Gateway-Proxy attribute.
  • Extract them from the PR_MTS_ID property of a message sent to the gateway.
  • Extract them from the first trace entry of a message sent to the gateway.

The value for Local ID in an MTS ID should be chosen so that it encapsulates whatever identifying information was available from the foreign system. This could be a correlation identifier, a foreign message identifier, or other information.

For example, the following value is a syntactically correct PR_MTS_SUBJECT_ID string:

c=US;a= ;p=Microsoft;l=<"Hui-z2.0.v54.7xA4o"@xyz-corp.com>\0


Nondelivery Report Failed Recipient List Properties

The failed recipient list is a MAPI address list containing information about recipients to whom the gateway could not deliver the message. It contains the following properties:

PR_RECIPIENT_TYPE

This property should be copied from the PR_RECIPIENT_PROPERTY of the appropriate recipient on the original message, if available. Allowed values are MAPI_TO, MAPI_CC, and MAPI_BCC.

PR_RECIPIENT_NUMBER

This property contains the offset of the recipient in the original message. For example, the first recipient has a PR_RECIPIENT_NUMBER value of 1. If this recipient is a member of a distribution list, then the offset of the distribution list in the original message is used.

PR_DISPLAY_NAME

This property contains values from the original message.

PR_ADDRTYPE

This property contains values from the original message.

PR_EMAIL_ADDRESS

This property contains values from the original message.

PR_ENTRYID

This property contains values from the original message.

PR_NDR_REASON_CODE

These codes are enumerated in the MAPITAGS.H file.

PR_NDR_DIAG_CODE

These codes are enumerated in the MAPITAGS.H file. For a list of allowed values, see the documentation for the PR_NDR_DIAG_CODE property in the MAPI Programmer’s Reference.

PR_REPORT_TIME

PR_REPORT_TIME is the time at which a per-recipient report was generated. Ideally this should be the time at which the message was found to be undeliverable. The X.400 standard requires the Arrival Time attribute on reports. However, the Microsoft Exchange Server information store requires PR_REPORT_TIME as a mandatory element on delivery reports and nondelivery reports.

PR_ARRIVAL_TIME

PR_ARRIVAL_TIME is the MAPI equivalent of the X.400 per-recipient report attribute Arrival Time. This is defined as “The date and time at which the communique entered the Management Domain (MD) that produced the per-recipient report.” The MAPI property PR_ARRIVAL_TIME is used in two different contexts; it is a message envelope property associated with the original message, and it is also a per-recipient property on the nondelivery report.

The appropriate values to set for PR_ARRIVAL_TIME and PR_REPORT_TIME depend on where the nondelivery report was generated and on the amount of information known to the gateway and the foreign system.

PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED

This code must be set to TRUE for a nondelivery report.

PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED

This code must be set to FALSE for a nondelivery report.


X.400 Nondelivery Report Attributes

The following table shows the attributes of X.400 nondelivery reports and how they relate to the MAPI properties of MAPI nondelivery reports. Attributes which do not have corresponding MAPI properties are not listed.

Attribute | MAPI Properties
Origin and Expansion History | PR_ORIGINATOR_AND_DL_ EXPANSION_HISTORY
Subject MTS Identifier | PR_MTS_SUBJECT_ID
Content | Embedded message or attachment
Content Correlator | PR_CONTENT_CORRELATOR
Content Identifier | PR_CONTENT_IDENTIFIER
Content Type | PR_X.400_CONTENT_TYPE
Origin Check | PR_ORIGIN_CHECK
Original EITs | PR_ORIGINAL_EITS
Reporting Distribution List Name | PR_REPORTING_DL_NAME
Reporting Message Transfer Agent Certificate | PR_REPORTING_MTA_CERTIFICATE
Security Label | PR_MESSAGE_SECURITY_LEVEL
MTS identifier | PR_MTS_ID
Report Destination | PR_REPORT_DESTINATION_NAME and PR_REPORT_DESTINATION_ ENTRYID
External Trace Information | PR_TRACE_INFO
Internal Trace Information | PR_INTERNAL_TRACE_INFO
Subject External Trace Information | PR_SUBJECT_TRACE_INFO

The following table shows Per-Recipient Report attributes and their corresponding MAPI properties.

Attributes | MAPI Properties
Actual Recipient Name | PR_DISPLAY_NAME, PR_ADDRTYPE, PR_EMAIL_ADDRESS, PR_ENTRYID
Arrival Time | PR_REPORT_TIME See Deviations from the X.400 Standard.
Intended Recipient Number | PR_RECIPIENT_NUMBER
Originator Report Request | PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED, PR_ORIGINATOR_DELIVERY_ REPORT_REQUESTED
Converted EITs | PR_CONVERTED_EITS
Forwarding Address | PR_PHYSICAL_FORWARDING_ ADDRESS
Originally Intended Recipient | PR_ORIGINALLY_INTENDED_ RECIP_ ENTRYID
Redirection History | PR_REDIRECTION_HISTORY
Supplementary Information | PR_SUPPLEMENTARY_INFO
Nondelivery Diagnostic | PR_NDR_DIAG_CODE
Nondelivery Request | PR_NDR_REASON_CODE


Read Receipts

Read receipts are report messages similar to delivery and non-delivery reports. They have message class strings of the form REPORT.X.RN, where X is the message class of the message the receipt corresponds to (usually IPM.Note). Read receipts inform a sender that a recipient has read a message. Read receipts are generated by the recipient’s email client software; no other component of a messaging system can be guaranteed to know when a user opens a message.

Whether a gateway can support read receipts depends on the foreign system’s capabilities. If the foreign system does support read receipts, gateways should do the following:

  • For outgoing messages, convert the value stored in the messages’ PR_READ_RECEIPT_REQUESTED property into whatever format the foreign system requires for read receipt requests.
  • For incoming read receipts, convert the content of the receipt—whatever form it takes—into a message whose message class is REPORT.IPM.Note.RN and deliver it to the sender of the original message.

For details about what properties are required on read receipts, see the topic About Message Properties in MAPI Programmer’s Guide.


Nonread Receipts

Nonread receipts are similar to read receipts, delivery reports, and nondelivery reports. They have message class strings of the form REPORT.X.NRN, where X is the message class of the message the receipt corresponds to (usually IPM.Note). Nonread receipts inform a sender that a recipient has deleted a message without opening it. Read receipts are generated by the recipient’s email client software; no other component of a messaging system can be guaranteed to know when a user deletes a message.

Whether a gateway can support nonread receipts depends on the foreign system’s capabilities. If the foreign system does support nonread receipts, gateways should do the following:

  • For outgoing an messages, convert the value stored in the message’s PR_NON_RECEIPT_NOTIFICATION_REQUESTED property into whatever format the foreign system requires for nonread receipt requests.
  • For an incoming nonread receipt, convert the content of the receipt—whatever form it takes—into a message whose message class is REPORT.IPM.Note.NRN and deliver it to the sender of the original message.

For details about what properties are required on nonread receipts, see About Message Properties in MAPI Programmer’s Guide.


Deviations from the X.400 Standard

This section discusses areas in which Microsoft Exchange Server reports differ from standard X.400 nondelivery reports.


Mixed Delivery and Nondelivery Reports

Standard X.400 reports can mix per-recipient entries for successful and failed delivery in a single report. Exchange Server requires separate message classes, using REPORT.X.DR for delivery reports and REPORT.X.NDR for nondelivery reports. Delivery and nondelivery per-recipient reports cannot be mixed in the same Microsoft Exchange Server report message.


Arrival Time

The X.400 standard requires the Arrival Time attribute on reports. However, the Microsoft Exchange Server information store requires PR_REPORT_TIME as a mandatory element on delivery reports and nondelivery reports.


Diagnostic and Reason Codes

The X.400 standard specifies that the properties PR_NDR_DIAG_CODE and PR_NDR_REASON_CODE should always occur together, but MAPI can generate nondelivery reports which contain only PR_NDR_DIAG_CODE. Therefore, these two properties are not always paired in Microsoft Exchange Server reports.

The values for PR_NDR_DIAG_CODE are listed in MAPITAGS.H, which is part of the MAPI SDK. Its default value is MAPI_DIAG_NO_DIAGNOSTIC.

The values for PR_NDR_REASON_CODE are also listed in MAPITAGS.H. Its default value is MAPI_REASON_TRANSFER_FAILED.


Backboning

Backboning is the process of transmitting messages between two similar messaging systems using an intermediate system of a different type. It is an important feature that should be offered by all Microsoft Exchange Server gateways. The goal of backboning is to send messages between Microsoft Exchange Server sites in different organizations as easily as you do between two users on the same site. A typical example is that of Microsoft Exchange Server sites at widely separated locations throughout the country. Mail users can send messages to others in distant cities by using the Internet as a backbone.

This section discusses using a foreign system as a backbone between two Microsoft Exchange Server systems. You can also use a Microsoft Exchange Server backbone between two foreign systems.


Backboning Scenarios

Backboning can be done between Microsoft Exchange Server sites in different organizations or between a Microsoft Exchange Server site and a foreign system that uses a MAPI client and can therefore process messages containing MAPI properties.

Site-to-site replication is not supported for Microsoft Exchange Server gateways. The sample gateway provided with this SDK cannot be used as a site connector. Replication between Microsoft Exchange Server sites must be handled by a site connector and not a gateway.


Organization-to-Organization Backboning

When a foreign system is used as a backbone between sites in different organizations, these sites must appear to be directly connected. The following figure shows two Microsoft Exchange Server organizations backboning over the Internet.

Organization-to-organization backboning

In this scenario, recipients in a different organization are represented as custom recipient objects in the directory.


Backboning To Foreign MAPI Providers

Backboning To Foreign MAPI Clients

The following figure shows backboning between a Microsoft Exchange Server organization and a foreign recipient using a MAPI-aware client application. MAPI providers should be able to handle Microsoft Exchange Server rich text format.

Backboning to a foreign MAPI-based recipient

In this scenario, recipients using MAPI client applications are represented as custom recipient objects in the Microsoft Exchange Server directory. MAPI-based recipients are distinguished from native foreign system recipients by a Boolean attribute on the directory object. This attribute (PR_SEND_RICH_INFO) can be set by the Microsoft Exchange Server Administrator program.


Gateways and Backboning

All Microsoft Exchange Server gateways should support backboning. A gateway must transfer both message content and addressing information in the appropriate format for the receiving system.

Transferring Message Content

Some foreign systems do not support the special properties that Microsoft Exchange Server allows, such as Microsoft Schedule+ menu formats and rich text in messages. A gateway must be able to distinguish between three types of recipients and handle message content accordingly. A message recipient can be on:

  • A foreign system that does not support special properties. For example, the message may be addressed to an Internet user.
  • Another Microsoft Exchange Server site that is connected by a foreign system as a backbone.
  • A foreign system that uses a MAPI client and therefore supports special properties.

For destination systems that support special properties, the gateway must encapsulate the message content so that it can pass through the foreign system backbone and then be re-created with all its properties at the destination system.

Transferring Addressing Information

Addressing formats must be translated between different systems. When a message is sent from a Microsoft Exchange Server system, the addresses of both the sender and the recipient are in Microsoft Exchange Server native format, which is called EX and is the X.500 distinguished name (DN). The gateway must translate both these addresses to the format of the backboning system.

When the message is transferred from the foreign system backbone to the Microsoft Exchange Server recipient, the gateway that makes that transfer must translate the recipient’s address back to the original Microsoft Exchange Server format. To convert the sender’s address back to the original format, the gateway must open the original message that is attached to the message transfer envelope (MTE). The gateway must also be able to handle address translation for CC and BCC recipients. See Addressing for details about address translation.


Deciding to Backbone a Message

When a backboning gateway receives an outbound message, it has to determine the final recipient of that message. If the message is being backboned across the foreign system to another Microsoft Exchange Server or other MAPI-based system, the gateway must encapsulate the message before handing it on to the foreign system, so that all Microsoft Exchange Server special properties are preserved. If the message recipient is a native user of the foreign system, the message is sent directly to that recipient. This decision can be made for each individual message or for groups of messages. The gateway developer can implement this decision using one of the following options:

  • For individual messages Use the MAPI-Recipient property (PR_SEND_RICH_INFO) that is set on the recipient in the message recipient table. This property is derived from the MAPI recipient attribute on the recipient object in the directory or, for a one-off address, from a per-recipient option defined by the address type. The per-recipient flag will be supported by the personal address book (PAB) if a one-off address is stored in the PAB.
  • For groups of messages Compare the recipient address with an address space table defined in the gateway’s configuration. To implement this option, you must provide a property page with your gateway that allows an administrator to enter an address space in the foreign domain and specify that everyone in that address space needs to be backboned. Then the gateway can compare recipient addresses with the specified address spaces.

For best performance, design the gateway to determine as soon as possible which recipients should be backboned. For example, if all recipients need to be backboned, no other conversions are necessary and message delivery will be faster.


Message Recipient Table

Each MAPI message sent from Microsoft Exchange Server has a recipient table. The recipient table contains the following properties for each intended recipient of the message.

Property Name | Description
PR_ADDRTYPE | Identifies the type of mail system. For example: SMTP.
PR_DISPLAY_NAME | Specifies the recipient’s display name, for example “John Doe.”
PR_EMAIL_ADDRESS | Specifies the recipient’s address: In foreign system format for a one-off address; otherwise in Microsoft Exchange Server format.
PR_ENTRYID | Points to the directory entry for a Microsoft Exchange Server recipient.
PR_RECIPIENT_NUMBER | Specifies this recipient’s ordinal number in the recipient list.
PR_RECIPIENT_TYPE | Specifies the recipient type, MAPI_TO.
PR_SEARCH_KEY | Message identifier.
PR_SEND_RICH_INFO | If TRUE, recipient is a MAPI recipient.


MAPI Recipient Property

A gateway uses the MAPI-Recipient property (PR_SEND_RICH_INFO) to determine whether to backbone an individual message to a given recipient. The PR_SEND_RICH_INFO property is exposed in the recipient table of a message and denotes whether a recipient has a MAPI-capable system. If this property is TRUE for a recipient, the gateway should encapsulate Microsoft Exchange Server special properties in messages being backboned to that recipient.

Setting the Property

The originator of a message can set whether a recipient is MAPI-capable on individual messages. This feature must be designed into the Addr-Type object and associated address entry template that you provide with your gateway. If the property is present on a recipient in a message, it will be stored in the personal address book (PAB) with an address. This MAPI-Recipient property is set in different ways for different object types, as described in the following sections.

Microsoft Exchange Server Directory Object

The MAPI-Recipient attribute on the recipient object in the Microsoft Exchange Server directory is set by default to TRUE for mailbox objects and FALSE for custom recipient objects. The administrator can change the setting in the advanced property page for a particular user. This enables the administrator to specify that a particular recipient in a foreign system uses a MAPI-based client and that messages to that recipient should be encapsulated.

If directory replication is performed within an organization, you can also use this property to identify users who are in another site in the same organization. They are represented as mailbox objects in the directory and will have the property set to TRUE by default.

Custom Recipient Object

The directory of another Microsoft Exchange Server organization can be imported to the organization on which the gateway is configured. In this case, the mailbox objects in the original organization become custom recipient objects in the gateway’s organization. The MAPI-Recipient property of each original mailbox object retains its value of TRUE as a custom recipient object. The gateway can thus use the MAPI-Recipient property to determine whether messages to a recipient need to be backboned.

Originator

The MAPI-Recipient property may also be present on the originator of a message. A gateway should check for this and transfer the property to the Microsoft Exchange Server if it is present because the property will be needed if a recipient replies to a message and the gateway needs to return the reply to the originator.


One-Off Addresses

A one-off address template should contain a check box with which the user can set the MAPI-Recipient property for one-off addresses. When a user creates a one-off address for backboning a message to a MAPI-based recipient, the user can set the MAPI-Recipient property to TRUE. (The default value for this property is FALSE.) If the property is set on a one-off address, it is maintained in the personal address book (PAB) and will be automatically set in the future when the user addresses a message using the PAB.

The gateway should check incoming messages with one-off addresses to see if they contain TNEF attachments. If a one-off message contains TNEF, it is a backboned message and its MAPI-Recipient property should be set to TRUE. The gateway should also set the MAPI-Recipient property on the originator of the message so replies can be encapsulated for return.


Address Space Table

Your gateway can determine whether to backbone a message to a particular recipient based on the recipient’s address. To implement this feature, you must provide a Microsoft Exchange Server Administrator program property page on the gateway object. The gateway administrator can use this property page to implement an address space table. This table defines a particular range of addresses as belonging to another Microsoft Exchange Server site or to a set of users who all use MAPI-compatible clients. For each Responsibility-TRUE recipient address, the gateway compares the address to its backbone address space table and decides whether that recipient requires backboning.


Encapsulation

A gateway can handle the transfer of Microsoft Exchange Server special properties across a backbone by encapsulating the message so that these properties pass through the foreign system and remain intact at its destination. Microsoft Exchange Server encapsulates message parts by encoding them in TNEF. For more information, see Transport Neutral Encoding Format.

The gateway should determine which recipients of the message are MAPI-Recipients, and then encapsulate MAPI message parts for transfer to those recipients. The gateway maps the message to the foreign system’s format and stores the message’s content in a TNEF encapsulated attachment in the foreign system’s attachment format.

The following figure shows how addresses and message content are backboned using encapsulation.

Encapsulating a message for backboning

The message transfer envelope (MTE) contains information that is necessary for a message to pass through the foreign system. Envelope information must be preserved during the backboning process so a backboned message can be delivered intact to the destination Microsoft Exchange Server system by the receiving gateway.

Your gateway can encapsulate message attachments in two ways:

  • The message text and its attachments can be encapsulated as a single TNEF attachment in the backboned message. The sample gateway provided with this SDK performs this type of encapsulation. It is illustrated in the preceding diagram.
  • The message text and its attachments can be encapsulated separately and tags can be placed inside the message text to indicate where the attachments need to be inserted when they are reconstructed. TNEF provides a mechanism for creating tagged message bodies that your gateway can use to encapsulate attachments separately from the message text.

See Message Transfer for more information about message transfer envelopes and transferring message properties.


Recipient Handling

The backboning process must handle several types of message recipients. These recipient addresses may need to be translated to the foreign system format before they are encapsulated.

Individual Recipients

Only Responsibility-TRUE recipients appear in the message transfer envelope (MTE) recipient table. These are recipients to whom the gateway must deliver the message. These addresses can be either native Microsoft Exchange Server addresses or one-off addresses. If they are native addresses, the gateway must resolve them to proxy addresses for the foreign system. If they are one-off addresses, they must be of the type that the gateway requires.

Originator

The message originator address appears both on the MTE and on the message content. The gateway should insert the originator’s proxy address into both the MTE and the message content so that replies can be delivered to the originator.

Distribution List Recipients

If the message is addressed to a distribution list (DL), the message’s recipient table contains the distinguished name (DN) of the DL. When Microsoft Exchange Server wraps the message in an MTE to send to the gateway, it breaks down the DL and places a Responsibility-TRUE recipient in the MTE’s recipient table for each DL member. The DL itself remains as a single entry in the recipient table.

When the DL members are listed as individual recipients in the MTE recipient table, each one has a PR_RECIPIENT_NUMBER property. This property is the number of the DL entry that contains the recipient in the message content recipient table.

Each individual Responsibility-TRUE recipient must be resolved to its proxy address representation. The DL in the message content recipient table must be resolved to its proxy representation before the message content is encapsulated in TNEF.


TNEF Conversion Candidates

Items that need to be converted to TNEF in a backboned message are those items that cannot be easily mapped into foreign system attributes. If the foreign system supports the same functionality as Microsoft Exchange Server, the gateway should include message attributes in the native foreign message rather than encapsulate them. Items that may need to be encapsulated include the following:

  • Per-recipient attributes Put any per-recipient attributes the foreign system does not support into a TNEF-encoded recipient table.
  • Attachments If the foreign system supports attachments, it is best to convert these to native foreign system attachments and then rebuild the message. Then the attachments can be read directly if the message goes to a native client. If the foreign system does not support attachments, your gateway will need to encode them at the end of the message body. This is often necessary when backboning over a SMTP-based system, in which case attachments should be encoded using the standard Unix uuencode format.
  • OLE objects Encapsulate these because most foreign systems do not support OLE.
  • Rich text This should be encapsulated.


TNEF Modes

MAPI supplies the ITnef interface that provides several methods for TNEF encoding and message handling. The OpenTnefStreamEx function provided by MAPI offers three modes of operation:

  • Compatibility mode This mode supports Microsoft Mail 3.2 and encapsulates only those properties that are supported by Microsoft Mail 3.2.
  • Best data mode This is the default TNEF mode. It uses Microsoft Mail 3.2 format and also includes message attributes that would need to be downgraded for Microsoft Mail 3.2. It includes these latter attributes as MAPI encapsulation. If they arrive on a MAPI client, they can be read. The cost of this mode is that it increases the message size.
  • Pure mode This mode encapsulates only MAPI properties. If another type of client receives the message, it cannot read the message. This mode provides the maximum message fidelity for MAPI clients.

A gateway should carry out its encapsulation using the appropriate mode. If no configuration option is provided, the gateway should encode using best data mode at the expense of the message size overhead.

For more information about implementing TNEF, see the MAPI Programmer’s Reference.


Code Page Issues

In international environments, gateways must perform code page conversions (converting between different character sets). The gateway must convert between foreign system and Microsoft Exchange Server code pages, and between code pages of originating and destination Microsoft Exchange Server systems.

The Microsoft Exchange Client creates strings using the code page specified by the client locale. The strings are stored in Unicode in the Microsoft Exchange Server information store. A gateway can retrieve the message properties from the information store either in Unicode format or in the code page specified by the gateway’s locale.

The following three parts of a backboned message need to be treated separately for code page conversion:

  • Message text Foreign system’s native code page.
  • Message envelope Foreign system’s native code page.
  • TNEF attachment Either Unicode or the code page of the gateway.

When a gateway transfers strings that are encapsulated using TNEF, the strings should be in the Microsoft Exchange Server code page when they are encapsulated. The gateway should also tag the TNEF code page property so the receiving system can perform any required conversion.

Code page support is relevant only in TNEF best data and pure modes.


Interoperating with the Microsoft Exchange Server Internet Mail Service

Gateways that need to interoperate properly with the Microsoft Exchange Server Internet Mail Service need to take some precautions with their use of TNEF encoding. Any gateway that delivers messages to the Internet at large should do this because it is not possible to know whether a recipient on the Internet will receive the message via Microsoft Exchange Server. This section describes how the Microsoft Exchange Server Internet Mail Service uses TNEF so that you can make your gateway properly interoperate with it.


MIME and Uuencode Encodings

The Exchange Internet Mail Client and Internet Mail Service generate TNEF encodings when sending a MAPI message to another SMTP host. The TNEF binary stream is stored in a file attached to the message called WINMAIL.DAT. If the receiving system is TNEF-aware, it can detect the WINMAIL.DAT attachment and retrieve the MAPI properties from the TNEF stream contained in the attachment.

The Internet Mail Service supports both uuencode and MIME encoding for TNEF attachments in SMTP messages. MIME is the preferred encoding, although which encoding is used depends on the capabilities of the receiving system. The Microsoft Mail for PC Networks SMTP Gateway only supports uuencode.

MIME

If sending a TNEF message to a system which supports MIME, the “multipart/mixed” content type should be used for the message. The TNEF stream must be base64 encoded and placed in a MIME body part of Content-Type application/ms-tnef. All file attachments sent with the message must be encapsulated in the TNEF stream. No other content types or encodings are supported for transmitting the TNEF stream. MIME encoding is described in detail in the documents RFC-1521 and RFC-1522, which are available from a number of sources on the Internet.

Uuencode

If sending to a system which does not support MIME, the WINMAIL.DAT attachment should be uuencoded and placed directly in the body of the message. All file attachments sent with the message should be uuencoded and placed into the message body separately. A gateway or client that receives a non-MIME message should look for a uuencoded file called WINMAIL.DAT in the body of the message. The order of attachments in the message does not matter. Uuencode encoding is described in the online manual pages for most UNIX systems; there is no RFC document describing this encoding method.

TNEF Correlator

It is not always safe to assume that a TNEF stream found in a message belongs with that message and should be decoded. Many foreign messaging systems return the contents of a message along with nondelivery reports. Also, if a recipient is on a system that does not support TNEF replies to a message, the original TNEF stream will no longer be valid. To avoid this problem, some piece of information found in both the TNEF stream and the message header must be used to correlate them.

The Internet Mail Service adds a MAPI property, PR_TNEF_CORRELATION_KEY, to each outgoing message before converting it to TNEF format. The value stored in PR_TNEF_CORRELATION_KEY is also placed in a header in the SMTP message, called X-MS-TNEF-Correlator.

When the Internet Mail Service receives a message with a TNEF attachment, it looks for PR_TNEF_CORRELATION_KEY in the TNEF attachment. If it exists and matches the value of X-MS-TNEF-Correlator, then the TNEF is decoded. If they do not match or if X-MS-TNEF-Correlator is missing, then the TNEF stream is ignored.

If the PR_TNEF_CORRELATION_KEY property is not present, then the TNEF is decoded. This is necessary to retain compatibility with the Microsoft Mail SMTP Gateway and the Exchange Internet Mail Client, which do not use PR_TNEF_CORRELATION_KEY.

Support for the X-MS-TNEF-Correlator header field is not mandatory, but SMTP gateways that generate TNEF format can use PR_TNEF_CORRELATION_KEY and X-MS-TNEF-Correlator to detect cases where message contents are returned in reports. Your software should never require PR_TNEF_CORRELATION_KEY on messages it receives.

MIME and Uuencode Examples

This section contains examples of messages containing MIME encoded and uuencode encoded TNEF streams.

MIME

The example below shows the headers and body of a MIME message containing a TNEF stream. Note that the value of the X-MS-TNEF-Correlator field is the same as the Message-ID field, and that the Internet Mail Service has placed the message body and the TNEF stream in different MIME parts of the message.

Received: by doug10.wspu.microsoft.com with Microsoft Exchange (IMS 4.5.1336)
    id <01BAE995.CB639550@doug10.wspu.microsoft.com>; Tue, 23 Jan 1996 13:22:07 -0800
Message-ID: <c=US%a=_%p=MICROSOFT%l=DOUG10960123132206AF005100@doug10.wspu.microsoft.com>
X-MS-TNEF-Correlator: <c=US%a=_%p=MICROSOFT%l=DOUG10960123132206AF005100@doug10.wspu.microsoft.com>
From: "Doug" <doug2@10.wspu.MICROSOFT.com>
To: "Douglas" <doug@osu-beavers.wspu.microsoft.com>
Subject: What is the status of my order?
Date: Tue, 23 Sep 1996 13:22:06 -0800
X-Mailer:  Microsoft Exchange Server Internet Mail Connector Version 4.5.1336
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="---- =_NextPart_000_01BAE995.CB66A290"

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.  Contact your
mail administrator for information about upgrading your reader to a version
that supports MIME.

------ =_NextPart_000_01BAE995.CB66A290
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit

Hey Doug,

Just checking on the status of the Coffee I ordered from you on Monday.

Doug

------ =_NextPart_000_01BAE995.CB66A290
Content-Type: application/ms-tnef
Content-Transfer-Encoding: base64

eJ8+IggVAQaQCAAEAAAAAAABAAEAAQeQBgAIAAAA5AQAAAAAAADoAAEIgAcAGAAAAElQTS5NaWNy
b3NvZnQgTWFpbC5Ob3RlADEIAQWAAwAOAAAAzAcBABcADQAWAAYAAgAWAQEggAMADgAAAMwHAQAX
AA0AFgAHAAIAFwEBCYABACEAAAAxRDIxMkU3N0VGNTRDRjExOEY2RTAwQUEwMDUxRUM4MQAuBwEN
gAQAAgAAAAIAAgABBIABACAAAABXaGF0IGlzIHRoZSBzdGF0dXMgb2YgbXkgb3JkZXI/ACsLAQOQ
BgDEAwAAGgAAAAMAJgAAAAAAAwA2AAAAAAADAAYQNArBVwMABxBFAAAAHgAIEAEAAABGAAAASEVZ
RE9VRyxKVVNUQ0hFQ0tJTkdPTlRIRVNUQVRVU09GVEhFQ09GRkVFSU9SREVSRURGUk9NWU9VT05N
T05EQVlET1VHAAAAAwAQEAAAAAADABEQAAAAAAIBCRABAAAAyQAAAMUAAABIAQAATFpGdSMzE/H/
AAoBDwIVAqQD5AXrAoMAUBMDVAIAY2gKwHNldO4yBgAGwwKDMgPGBxMCgyIzD3poZWwDIERs+mcC
gH0KgAjPCdkCgAqBgw2xC2BuZzEwMxQghwsKEvIB0CBIZXkVMBkIYGcsCoUKhUp1c5cFQBGwBZBr
C4BnIAIglCB0FPAgG1BhdBtAPRwAZhwzCFAN0AngIEkvHAALIASQCYAgA1IgeQsIYBwCTQIgZGF5
Li8aXBoCCoUVkQAhcAAAAAMAAlkBAAAAHgBwAAEAAAAgAAAAV2hhdCBpcyB0aGUgc3RhdHVzIG9m
IG15IG9yZGVyPwACAXEAAQAAABYAAAABuunY2Mk79t3yVRgRz49uAKoAUeyBAABAADkAwG7M2Njp
ugEDAPE/CQQAAAIBRwABAAAAMAAAAGM9VVM7YT0gO3A9TUlDUk9TT0ZUO2w9RE9VR1NUMTAtOTYw
MTIzMjEyMjA2Wi02AAIB+T8BAAAAUgAAAAAAAADcp0DIwEIQGrS5CAArL+GCAQAAAAAAAAAvTz1N
SUNST1NPRlQvT1U9MTAvQ049UkVDSVBJRU5UUy9DTj1ET1VHU1QgKERPVUdTVDEwKQAAAB4A+D8B
AAAAEQAAAGRvdWdzdChkb3Vnc3QxMCkAAAAAAgH7PwEAAABSAAAAAAAAANynQMjAQhAatLkIACsv
4YIBAAAAAAAAAC9PPU1JQ1JPU09GVC9PVT0xMC9DTj1SRUNJUElFTlRTL0NOPURPVUdTVCAoRE9V
R1NUMTApAAAAHgD6PwEAAAARAAAAZG91Z3N0KGRvdWdzdDEwKQAAAABAAAcwkHky0NjpugFAAAgw
gFc02djpugEDAA00/T8AAAIBFDQBAAAAEAAAAFSUocApfxAbpYcIACsqJRceAD0AAQAAAAEAAAAA
AAAACwApAAAAAAALACMAAAAAAAIBfwABAAAAUgAAADxjPVVTJWE9XyVwPU1JQ1JPU09GVCVsPURP
VUdTVDEwOTYwMTIzMTMyMjA2QUYwMDUxMDBAZG91Z3N0MTAud3NwdS5taWNyb3NvZnQuY29tPgAA
ANrg

------ =_NextPart_000_01BAE995.CB66A290--

Uuencode

The example below shows the headers and body of a RFC-822 message containing a uuencoded TNEF stream. Note that the value of the X-MS-TNEF-Correlator field is the same as the Message-ID field, and that the encoded TNEF stream is part of the message body.

Received: by doug10.wspu.microsoft.com with Microsoft Exchange (IMS 4.5.1336)
    id <01BAE996.1A250570@doug10.wspu.microsoft.com>; Tue, 23 Jan 1996 13:24:19 -0800
Message-ID: <c=US%a=_%p=MICROSOFT%l=DOUG10960123132418AG005100@doug10.wspu.microsoft.com>
X-MS-TNEF-Correlator: <c=US%a=_%p=MICROSOFT%l=DOUG10960123132418AG005100@doug10.wspu.microsoft.com>
From: "Doug" <doug2@10.wspu.MICROSOFT.com>
To: "Douglas" <doug@wspu.microsoft.com>
Subject: What is the status of my order?
Date: Tue, 23 Sep 1996 13:24:18 -0800
X-Mailer:  Microsoft Exchange Server Internet Mail Sonnector Version 4.5.1336
Encoding: 8 TEXT, 32 UUENCODE
X-MS-Attachment: WINMAIL.DAT 0 00-00-1980 00:00

Hey Doug,

Just checking on the status of the Coffee I ordered from you on Monday.

Doug

begin 600 WINMAIL.DAT
M>)\^(A05`0:0" `$```````!``$``0>0!@`(````Y 0```````#H``$(@ <`
M& ```$E032Y-:6-R;W-O9G0@36%I;"Y.;W1E`#$(`06 `P`.````S <!`!<`
M#0`8`!(``@`D`0$@@ ,`#@```,P'`0`7``T`& `3``(`)0$!"8 !`"$````R
M,C(Q,D4W-T5&-31#1C$Q.$8V13 P04$P,#4Q14,X,0`=!P$-@ 0``@````(`
M`@`!!( !`" ```!7:&%T(&ES('1H92!S=&%T=7,@;V8@;7D@;W)D97(_`"L+
M`0.0!@`,! ``&@````,`)@```````P`V```````#``80J'8Q+0,`!Q!8````
M'@`($ $```!9````4T5.1$E.1U=)5$A5545.0T]$14A%641/54<L2E535$-(
M14-+24Y'3TY42$535$%455-/1E1(14-/1D9%14E/4D1%4D5$1E)/35E/54].
M34].1$%91$]51P`````#`! 0``````,`$1 ``````@$)$ $```#_````^P``
M`+X!``!,6D9UK)IM4O\`"@$/`A4"I /D!>L"@P!0$P-4`@!C: K <V5T[C(&
M``;#`H,R`\8'$P*#(C,/>FAE; ,@1&P:9P*#- /%`@!P<G&A$B)S=&5M`H,U
M$PW^?0J ",\)V0* "H$-L0M@X&YG,3 S%" +"A+RDP'0!E%N9 N 9R #\ !T
M:"!5545.0_!/1$4N'> *A0J/"Y%C%V(<84AE>14P"&!GTBP>'$IU%M @$; %
MD)9K'-("(" =,&4@%M#L870AL")P9B*C"% -T'D)X"!)(G +( 20"8 @60-2
M('D(8")R30(@9'QA>1X-('(;K1Z%&&$``2C0``,``ED"````'@!P``$````@
M````5VAA="!I<R!T:&4@<W1A='5S(&]F(&UY(&]R9&5R/P`"`7$``0```!8`
M```!NNG9)S\[]MX%51@1SX]N`*H`4>R!``! `#D`</Y")]GIN@$#`/$_"00`
M``(!1P`!````, ```&,]55,[83T@.W ]34E#4D]33T94.VP]1$]51U-4,3 M
M.38P,3(S,C$R-#$X6BTW``(!^3\!````4@````````#<IT#(P$(0&K2Y" `K
M+^&"`0`````````O3SU-24-23U-/1E0O3U4],3 O0TX]4D5#25!)14Y44R]#
M3CU$3U5'4U0@*$1/54=35#$P*0```!X`^#\!````$0```&1O=6=S="AD;W5G
M<W0Q,"D``````@'[/P$```!2`````````-RG0,C 0A :M+D(`"LOX8(!````
M`````"]//4U)0U)/4T]&5"]/53TQ,"]#3CU214-)4$E%3E13+T-./41/54=3
M5" H1$]51U-4,3 I````'@#Z/P$````1````9&]U9W-T*&1O=6=S=#$P*0``
M``! ``<P$"K'%]GIN@% ``@P,%K#)]GIN@$#``TT_3\```(!%#0!````$ ``
M`%24H< I?Q ;I8<(`"LJ)1<>`#T``0````$`````````"P`I```````+`",`
M``````(!?P`!````4@```#QC/553)6$]7R5P/4U)0U)/4T]&5"5L/41/54=3
M5#$P.38P,3(S,3,R-#$X04<P,#4Q,#! 9&]U9W-T,3 N=W-P=2YM:6-R;W-O
,9G0N8V]M/@```,WY
`
end


Administrative Functions

Gateways can supply administrative functionality in a Microsoft Exchange Server system. This functionality includes:

  • Error handling
  • Tracking messages
  • Performance monitoring


Error Handling

It is important that a gateway provide or store as much information as possible if an error occurs. You can implement four levels of error handling:

  • Retry the failed operation in case the problem is temporary, as in a communication failure.
  • Send a nondelivery report for the message. (Note that a gateway should not send a nondelivery report for a report.)
  • If the gateway cannot send the message and also cannot send a nondelivery report (for example, if the network is down), save the message, write an entry in the error log, and alert the administrator. Retry the operation later.
  • If you can continue processing only by deleting the message, then delete the message, write an entry to the error log, and alert the administrator. An example of this is when the gateway receives a message that is too large to store or send.


Tracking Messages

You can incorporate message tracking functions in your gateway. Message tracking traces the progress of messages traveling through the gateway to Microsoft Exchange Server or to the foreign system. Typically, Microsoft Exchange Server message identifiers are incompatible with those in foreign systems. Translation tables between the systems are required to track all messages.


Using Tracking Functions

Microsoft Exchange Server provides tracking functions that your gateway can use to record auditing and accounting information. The gateway is responsible for providing the tracking functions with data about each message that passes it. Microsoft Exchange Server specifies the information to be passed.

Gateways use the functions listed in the following table to handle message tracking.

Function | Action | When Called
HrTrackInitLog | Initializes the gateway event tracking session. | As gateway starts.
HrTrackWriteLog | Logs a tracking event. | For each message.
HrTrackUninitLog | Uninitializes the gateway tracking session. | As gateway stops.


Performance Monitoring

The Windows NT Performance Monitor is a utility that displays statistics for analyzing system performance. The Microsoft Exchange Server performance monitoring system enables a gateway to send statistics to the Windows NT Performance Monitor.

Using this mechanism to set up your gateway’s performance reporting requires a lot less effort than creating a performance monitoring system yourself. In addition, displaying performance information in the Windows NT Performance Monitor allows the gateway’s performance statistics to be directly compared and graphed against other system performance statistics such as memory footprints and CPU usage.


The Windows NT Performance Monitor

The Windows NT Server operating system provides a utility called the Performance Monitor, which can display statistics for system resources such as processors, memory, file handles, threads, and processes. The Performance Monitor allows user-written applications to publish their own statistics.

Your gateway can send its own performance statistics to the Windows NT Performance Monitor by using the Microsoft Exchange SDK performance monitor functions. These functions provide access to a library for performing statistical calculations, and a library for managing a memory-mapped file that is used as an asynchronous communication mechanism between your gateway and the Performance Monitor.

The Windows NT Performance Monitor keeps track of a set of objects, each of which represents a system resource. Each object has a set of counters that can provide device usage, queue length, delay, throughput, and internal congestion measurements. Your gateway can be registered as an object for performance monitoring. Multiple instances of an object are allowed, such as when multiple instances of your gateway are running.

The Performance Monitor allows you to do the following:

  • View data from any number of computers simultaneously.
  • View and dynamically change charts that reflect current activity and show counter values that are updated at a user-defined frequency.
  • Export data from charts, logs, alert logs, and reports to spreadsheet or database programs for further manipulation.
  • Add system alerts that list an event in the alert log and optionally notify the system administrator by displaying the alert view or issuing a network alert.
  • Run a predefined program when a counter value goes over or under a user-defined value. This is useful for starting or stopping additional threads or processes to respond to varying workloads.
  • Create log files containing data about various objects from different computers.
  • Create one long-term archive by jointing pieces of other existing log files.
  • View current activity reports or create reports from existing log files.
  • Save individual chart, alert, log, or report settings, or the entire workspace setup, and reuse when needed.

You can use the Performance Monitor to send alerts from your gateway. To do this, set up an alert in the Performance Monitor and specify a computer name to which the alert will be sent. If the receiving computer is running a program that monitors alerts, it will receive the alert.

For an overview of performance monitoring, see the Win32 Programmer’s Reference.


Performance Monitor Functions

The Win32 SDK includes functions that let you set counters used by the Windows NT Performance Monitor. The Microsoft Exchange Server SDK includes functions for performance monitoring:

Function | Action | When Called
HrMonInit | Begins monitoring | When the gateway starts
HrMonUninit | Ends monitoring | When the gateway exits
HrMonCollectNDRStats | Updates statistics for NDR messages | After processing an NDR message
HrMonCollectMessageXferStats | Updates statistics for message transfers | After transferring a message
HrMonCollectAssociationStats | Updates statistics for associations | After creating, deleting, or changing associations
HrMonLockCounters | Locks a set of counters against access by other threads | Before accessing a user-defined counter
HrMonUnlockCounters | Unlocks a set of counters | After accessing a user-defined counter

These and other functions used for performance monitoring are supplied in the libraries EXCHINST.LIB, MONITOR.LIB, and STATS.LIB. See also HrInstallServicePerfMon, HrRemoveServicePerfMon, COUNTERDEF.


Monitoring Gateway Performance

The Microsoft Exchange Server SDK provides a performance monitoring interface layer between the gateway and the Windows NT Performance Monitor functions. This interface provides an easy way to publish statistics that are commonly needed for a gateway. Gateways can use the MONITOR.LIB library to:

  • Collect gateway data
  • Calculate statistics using the STATS.LIB library
  • Write statistics to memory-mapped files

A performance monitor DLL is responsible for taking data from the memory mapped files and presenting it to the Windows NT Performance Monitor. The Performance Monitor uses the DLL to poll the memory-mapped files at periodic intervals to retrieve performance data.

Note A gateway must be run at least once before its object becomes visible in the Performance Monitor.

The following figure shows the complete performance monitoring process. The shaded areas are the components you need to build.

Performance monitoring process


Setting Up Counters

The Windows NT Performance Monitor uses a set of counters to monitor gateway performance. The Microsoft Exchange Server SDK performance monitoring functions provide several counter types and counter periods. You can select the appropriate counters and periods for your gateway.

For more information on the performance monitor functions supplied in the Microsoft Exchange Server SDK, see HrInstallServicePerfMon, HrMonInit, HrRemoveServicePerfMon, HrMonLockCounters and COUNTERDEF.

Gateway Counters

Gateway counters are used for statistics that apply to the entire gateway. They are:

  • The number of messages entering Microsoft Exchange Server through the gateway.
  • The number of bytes entering Microsoft Exchange Server through the gateway.
  • The number of messages leaving Microsoft Exchange Server through the gateway.
  • The number of bytes leaving Microsoft Exchange Server through the gateway.
  • The number of nondeliverable receipts on messages entering Microsoft Exchange Server through the gateway.
  • The number of nondeliverable receipts on messages leaving Microsoft Exchange Server through the gateway.
  • The number of connections the gateway has made to the foreign mail system.

Folder Counters

Folder counters are used for statistics that apply to a single MAPI folder. MAPI folders are frequently used as queues, such as MTS_OUT. You can set up counters for several different folders. The folder counters are:

  • The number of messages in the folder.
  • The number of bytes in the folder.
  • The number of messages entering the folder.
  • The number of bytes entering the folder.
  • The number of messages leaving the folder.
  • The number of bytes leaving the folder.

User-Defined Counters

The Microsoft Exchange Server performance monitor functions let you set up and directly manipulate counters used by the Windows NT Performance Monitor. The following table shows counters that are typically required for a gateway and which are not provided through STATS.LIB. You can also define additional counters.

Counter | Counter definition
Foreign Logical Connections | The number of logical connections this gateway currently has to foreign systems.
Messages/Unit Time | The number of messages processed per unit time.
Message Bytes/Unit Time | The number of message bytes processed per unit time.
Nondelivery Reports/Unit Time | The number of nondelivery reports processed per unit time.
Threads in Use | The number of threads in use by the gateway.
Work Queue Size | The number of items in the gateway work queue, which is the total number of messages in the gateway’s MTS-IN and MTS-OUT folders.

Counter Period Types

For many of the counters, you can use the period type to specify how data is displayed. The period types are show in the following table.

Period type | Data displayed
None | A current value (snapshot statistic) such as the number of associations or the number of messages in a folder. Also used for user-defined counters.
Continuous | Total number of events during the past Performance Monitor sampling period.
Last N Minutes | Total number of events during the last N one-minute intervals.
Total | Total number of events since the gateway started running.


Calculating Statistics

The monitor phase is responsible for collecting gateway data and calculating statistics. There are two types of counter statistics:

  • Snapshot statistics Each snapshot statistic is derived from one measurement recorded at one particular moment in time, such as the number of messages in the out-queue or the number of threads in use. Folder snapshot statistics are generated using the folder snapshot functions provided by STATS.LIB.
  • Period statistics Each period statistic is based on measurements recorded over a period of time, such as messages received per hour or the maximum number of messages in the in-queue during a four-hour period. They are generated from snapshot statistic derivations, using the jump window functions provided by STATS.LIB.

For more information, see Folder Snapshot Functions and Jump Window Functions.


Monitor Sampling Functions

The monitor sampling functions are high-level functions called by the gateway. These functions internally record simple snapshot statistics and call the Folder Snapshot Functions and the Jump Window Functions to calculate the additional statistics. The monitor maintains a separate thread function, SharedMemoryUpdate, to periodically update the memory-mapped file with the calculated statistics.

The sample gateway uses monitor sample functions to make calls to MONITOR.LIB, which in turn uses the folder snapshot functions and the jump window functions in STATS.LIB. At regular intervals the SharedMemoryUpdate function copies the calculated statistics to the memory-mapped file.

The monitor sampling functions are listed in the following table.

Function | Action | When called
HrMonInit | Initializes the data collection for all statistics of a folder. | As gateway starts.
HrMonCollectNDRStats | Builds statistics on the number of nondelivery reports produced in a folder. | For each nondelivery report sent or received.
HrMonCollectMessage XferStats | Builds statistics on the number of messages traveling in each direction through the gateway. | For each message transferred through the gateway.
HrMonCollect AssociationStats | Updates the statistic on the current number of gateway associations. | Each time the number of associations changes.
HrMonLockCounters | Locks the counters against access by other threads or processes. | Before accessing a user-defined counter.
HrMonUnlock Counters | Unlocks the counters to allow access by other threads or processes. | After accessing a user-defined counter.
HrMonUninit | Closes down the data collection for all statistics. | As gateway stops.


Folder Snapshot Functions

The folder snapshot functions generate folder measurements taken at a specific moment in time. These functions are found in STATS.LIB.

The following measurements can be produced in any number:

  • The number of messages in the folder.
  • The length of time the oldest message has been in the folder.
  • For all messages in the folder, the total of all their wait times.

The folder snapshot functions are typically called in the order shown in the following table.

Function | Action | When called
HrOpenFolderMetrics | Opens the folder for folder snapshot statistics. | For each folder where snapshot statistics are to be collected, once when monitoring starts.
HrGetFolderMetrics | Retrieves specified folder snapshot statistics. | For each folder where snapshot statistics are collected, periodically during monitoring.
CloseFolderMetrics | Closes the folder and releases resources allocated in HrOpenFolderMetrics. | For each folder where snapshot statistics have been collected, once when monitoring stops.


Jump Window Functions

The jump window functions convert snapshot statistics into statistics that cover some interval of time. Monitoring programs can call these functions in STATS.LIB to produce folder statistics based on several sets of folder measurements taken over an interval of time.

The interval of time is called a jump window. It is a fixed-size window of time that keeps up with the current clock time by making small, equal-sized forward jumps. The width of the jump window is its duration; the time interval between jumps is its resolution.

Each jump window can produce one of the following statistics for the data it has collected:

  • Maximum
  • Minimum
  • Mean
  • Total

The jump window functions are listed in the following table.

Function | Action | When called
HrJSOpen | Defines a jump window’s calculations and dimensions. | For each period statistic to calculate.
HrJSCollectDataPoint | Adds a new data point to the window. | When snapshot data is available.
HrJSGetValue | Calculates the jump window’s current value. | For each jump window calculation.
JSClose | Closes and destroys the jump window. | For each jump window.
HrFileTimeToSeconds | Converts time durations from FILETIME type to seconds. | When a time duration must be displayed to the owner.


Performance Monitor DLLs

You must supply a DLL with your gateway that reads performace data from the memory-mapped files created by each gateway instance and places it in the Windows NT Registry so that the Windows NT Performance Monitor can access it. This DLL services the memory-mapped files for all instances of the gateway.

A performance monitor DLL must open the memory mapped files when the Performance Monitor starts, collect performance data each time the Performance Monitor requests a sample, and close the memory-mapped files when the Performance Monitor stops. Performance monitor DLLs use a counter structure for transferring data into the Windows NT Registry.

Performance monitor DLLs must implement the following functions.

Function | Purpose
OpenGatewayPerformanceData | Opens the memory mapped files, creates a connection to the Windows NT application event log, and passes a copy of the counter structure to the registry.
CollectGatewayPerformanceData | Updates the performance data in the registry with data from the memory mapped files. There are multiple memory-mapped files if there are multiple instances of a gateway. In that case, The DLL can merge them into one structure before passing it to the Performance Monitor.
CloseGatewayPerformanceData | Closes the memory mapped files, frees memory used by the counter structure, and disconnects from the application event log.

For more information about Performance Monitor DLLs and creating these routines, see the Windows NT Server Device Driver Kit (DDK) and the code for the GWPERF sample performance monitor DLL.


Example: Performance Monitoring

The following topics show techniques used by the sample gateway and the sample performance monitor DLL for performance monitoring, such as installing counters in the Windows NT Registry so the Windows NT Performance Monitor will recognize them.

Installing the counters requires creating counter definition files, some initial setup of the registry, and loading the counter definition file information into the registry. It also requires that the performance monitor DLL be set up in a directory specific to your gateway.

For more information about installing counters, see Optimizing Windows NT in the Windows NT Server Resource Kit.


Choosing Gateway and Gateway Type Names

The first step in adding performance monitoring to your gateway is choosing a name that represents your gateway type. This name should be specific to your gateway and not a generic type name. For example, use ACME-Fax rather than Fax. This name is used as a key under the SYSTEM\CurrentControlSet\Services key in the Windows NT Registry, and it will hold information describing the counters in your gateway. For this reason it cannot be shared by another gateway that uses a different set of counters. The type for the sample gateway is MyGate.

In addition to choosing the gateway type name, you should also choose a name for your specific gateway. This will be the name of the gateway as it is installed in Microsoft Exchange Server. You can install multiple instances of the gateway, in which case there will be more than one gateway name. Each gateway name is also used as a key under the SYSTEM\CurrentControlSet\Services key in the registry, so a gateway name should not be the same as a gateway type name. This example uses two instances of the gateway named MyGate1 and MyGate2.


Choosing Counters

The next step in adding performance monitoring to your gateway is deciding which counters you want to publish. While the exact choices depend on the type of gateway you are writing, certain counters are useful for most gateways. These include the number of messages and bytes waiting to be processed in MTS_OUT, the number of messages and bytes transferred in or out, and the number of nondeliverable receipts. This example uses the following counters:

  • Messages waiting in outbound queue (MTS_OUT).
  • Bytes waiting in outbound queue (MTS_OUT).
  • Messages transferred out.
  • Bytes transferred out.


Creating the Counter Definition Files

When you have chosen your counters, you need to create two files to define them: one is an .INI file and one is an .H file. This example uses the names MYGATE.INI and MYGATE.H. These files contain a numeric constant representing each counter, the name of each counter, and a help message describing what it does. The Windows NT Performance Monitor uses this information to display the counters and let the user select them.

MYGATE.H

MYGATE.H contains the defined numeric constants used to represent the counters. The names and help text for each counter are given in MYGATE.INI. These defined constants will be used to reference the counters inside your gateway as well as inside the Windows NT Performance Monitor.

MYGATE.H is a C/C++ include file that is intended to be included in your gateway program. It contains the symbol for the gateway object and each counter defined in the .INI file. Each symbol is assigned a constant numeric value. Note that each constant is a consecutive even number starting at 0. By convention, an even number represents the object or counter name and the odd number immediately following it represents the help text.

// begin MYGATE.H

#define MYGATE 0
#define MESSAGES_IN_OUT_QUEUE 2
#define BYTES_IN_OUT_QUEUE 4
#define MESSAGES_OUT 6
#define BYTES_OUT 8

// end MYGATE.H

MYGATE.INI

The .INI file contains three sections, [info], [languages], and [text]. The [info] section contains the name of the registry key used by the gateway, and the name of the .H file containing the numeric constants for each counter. The [languages] section contains numeric constants for each language used in the [text] section. The constants defined in this section, along with the “_HELP” and “_NAME” strings, are used to identify which strings in the [text] section correspond to which counters defined in the .H file. The [text] section contains the display names and help text for each counter. If multiple languages are defined in the [languages] section, display names and Help text for all such languages will be included in the [text] section.

// begin MYGATE.INI

[info]
drivername=MyGate
symbolfile=MYGATE.H

[languages]
009=English

[text]
MYGATE_009_NAME=My Gateway
MYGATE_009_HELP=This is my performance monitoring example
MESSAGES_IN_OUT_QUEUE_009_NAME=Messages In Outbound Queue
MESSAGES_IN_OUT_QUEUE_009_HELP=The number of messages in the outbound queue, waiting to be processed by the gateway
BYTES_IN_OUT_QUEUE_009_NAME=Bytes In Outbound Queue
BYTES_IN_OUT_QUEUE_009_HELP=The total bytes in the outbound queue, waiting to be processed by the gateway
MESSAGES_OUT_009_NAME=Outbound Messages
MESSAGES_OUT_009_HELP=The number of messages sent out of the gateway
BYTES_OUT_009_NAME=Outbound Bytes
BYTES_OUT_009_HELP=The total bytes sent out of the gateway

// end MYGATE.INI


Installing the Performance Monitor DLL

The performance monitor DLL file must be placed in a directory that is specific to your gateway. It can be placed wherever you like and can be renamed. When you set up the registry, you will insert a path to this DLL.

Even though this DLL is the same for all gateway instances, it is important that there is only one gateway type referring to the same physical DLL. Otherwise, the Windows NT Performance Monitor will attempt to load the same DLL twice for two different gateway types. This should be avoided because different gateway types probably store different information in their memory mapped performance data files, and a performance monitor DLL for one type of gateway is unlikely to properly use a file for another type.


Setting Up The Registry

Before the counters can be installed in the Windows NT Registry, you must do some initial setup of the registry. Under the SYSTEM\CurrentControlSet\Services key, create a key with the same name as your gateway type (in our example, MyGate). Under that key create subkeys called Linkage and Performance.

Under the Linkage subkey, create a value called Export of type REG_MULTI_SZ with its value being the gateway name(s) that you chose above (in our example, MyGate1 and MyGate2).

Under the Performance subkey, create a value called Library of type REG_SZ with its value being the full pathname of the performance monitor DLL for your gateway. Create three other values called Open, Close, and Collect, and give them the exact types and values shown in the following registry tree. Here is how the tree should look:

SYSTEM\CurrentControlSet\Services\
        MyGate
               Linkage
                     Export:REG_MULTI_SZ:MyGate1 MyGate2
               Performance
                     Close:REG_SZ:CloseGatewayPerformanceData
                     Collect:REG_SZ:CollectGatewayPerformanceData
                     Library:REG_SZ:c:\...\GWPERF.DLL
                     Open:REG_SZ:OpenGatewayPerformanceData


Installing The Counters

After the preceding setup steps have been performed, installing the counters is simple. Go to a command prompt, switch to the directory where MYGATE.INI and MYGATE.H are located, and type the following:

LODCTR MYGATE.INI

To uninstall the counters, type:

UNLODCTR MyGate

Note that UNLODCTR takes the name of the gateway type, not the .INI file.

The Windows NT Performance Monitor should now recognize the counters. The performance monitor DLL will not return any actual counter values to the monitor until your gateway is running and sending it data. For that to happen, you need to add Microsoft Exchange Server performance monitoring calls to your gateway code.


Gateway Setup Programs

You should provide a setup program for your gateway so users can install, configure, and remove the gateway within the Microsoft Exchange Server environment. This section describes how to write a setup program and identifies the most important installation tasks the program will need to perform.

For general information on writing setup programs, see the Setup API documentation in the Win32 SDK.

Note The installation and configuration of a gateway are closely related tasks because gateways are usually configured during installation. Moreover, setup and administration operations interact with many of the same components within Microsoft Exchange Server and Microsoft Windows NT Server.


About Gateway Setup Programs

A primary function of the setup program is to copy all necessary files from floppy disks or CD to the server’s hard disk. The setup program must also ensure that the gateway is recognized by Microsoft Exchange Server system components and can communicate with them. Your setup program can use the utility functions provided with the Microsoft Exchange Server SDK to manage the gateway’s configuration information.

Your setup program can include some or all of the following steps:

  • Collect and verify system installation requirements from the administrator. See Collecting System Requirements.
  • Install the gateway as a service of Windows NT Server using the Windows NT service control manager. See Installing the Gateway as a Service.
  • If you use an Administrator extension DLL to add property pages to the gateway’s directory object, the setup program can install its associated Admin-Extension object in the Microsoft Exchange Server directory. See Installing an Admin-Extension Object.
  • Certain files are required for gateways that use Administrator extensions or address types. The setup program can copy these directory-related files onto the server’s hard disk. See Copying Files Onto Disk.
  • Copy the required files for the gateway itself onto the computer on which the gateway will run (not necessarily a Microsoft Exchange Server computer). See Copying Files Onto Disk.
  • Set the Gateway bit in the Heuristics attribute on the Server object. See Setting the Server Heuristics Attribute.
  • Create the Mail-Gateway object in the Microsoft Exchange Server directory. See Creating the Directory Object.
  • Set the attribute values of the gateway object. See Initializing the Extension-Data Attribute.
  • Install address type and proxy address information, and rebuild the gateway address routing table. See Installing Addressing, Updating the Gateway-Proxy Field of the Site Object, and Rebuilding the Gateway Address Routing Table.
  • Generate proxy addresses for current recipients. See Generating Recipient Proxy Addresses.
  • Set up performance monitoring for your gateway. See Installing Performance Monitoring.
  • Reconfigure other system elements as required. See Reconfiguring the System.


Writing the Setup Program

The recommended guide for writing a setup program is the Setup API documentation in the Win32 SDK.

The Setup API documentation includes a sample setup program template and online Help that explains how to use the template. It also provides many functions you will need, including those that control basic user dialog boxes. You may need to create additional custom dialog boxes.

The Microsoft Exchange Server SDK provides a sample gateway setup program called GWSETUP. It is located in the directory \BKOFFICE\SAMPLES\EXCHANGE\GWSETUP.


Performing Preliminary System Configuration

Before you install a Microsoft Exchange Server gateway:

  • Microsoft Exchange Server must be installed and running.
  • The Microsoft Exchange Server Administrator program must be installed on the computer on which the gateway will run.

The computer from which you install the gateway does not have to be the Microsoft Exchange Server computer. This means that you can install a gateway remotely.

If your gateway is designed to operate as a service of Windows NT Server, an administrator needs to set up a Windows NT Server account with the “Log on as a service” right for the gateway before running its setup program. The documentation for your gateway’s setup procedure should make these prerequisites clear.


Collecting System Requirements

Gateways are usually installed and configured according to the user’s specified needs. It is good practice to collect and verify this data from the user at the beginning of the setup procedure through a series of interactive dialog boxes. This information tells the setup program which components to install and how to configure the user’s system.

Typical information to be gathered at this point includes:

  • The name of the Microsoft Exchange Server computer on which to install the gateway.
  • The site on which to install the gateway.
  • A display name for the gateway directory object.
  • A display name for the gateway service.
  • A path to the directory in which to install the gateway.
  • The Windows NT Server account name for the gateway service.
  • The Windows NT Server account password for the gateway service.

For example, the setup program for the sample gateway distributed with this SDK uses the following files to collect information at installation time:

  • DIALOGS.RC This file contains the dialog boxes that are displayed.
  • GWUISTF.C This program contains dialog box control routines and validates some of the entered data.
  • GWSETUP.C This program performs high-level dialog box control operations and performs some additional data validation.


Installing the Gateway as a Service

If your gateway runs as a service of Windows NT Server, you must install it in the Windows NT service control manager (SCM). Making your gateway a service of Windows NT Server enables it to start up automatically when the computer is turned on and to run in its own security context. Users also gain the ability to control the gateway through the operating system, instead of requiring a custom user interface.

To register a gateway as a service of Windows NT Server
  1. Connect to the SCM by calling the Win32 OpenSCManager function.
  2. Create the service by calling the Win32 CreateService function and passing information such as the service name and type, and the ways the service should be switched to and started.
  3. In the local Windows NT Registry, open the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services key. Do this by calling the Win32 RegOpenKeyEx function.
  4. Under this key, create other necessary keys for the service, such as the Object key, the Parameters key, and the Diagnostics key. Registry keys are created by calling the Win32 RegCreateKeyEx function.
  5. Write the configuration information that your application needs into these Registry keys.

For an example of this procedure, see the HrInstallService function in \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\EXCHINST.C. See Installing Event Logging for specifics on creating the Diagnostics key.


Installing Event Logging

To enable diagnostic event logging for your gateway to be controlled from the Microsoft Exchange Server Administrator progam, your installation program must create a Diagnostics key for the gateway service in the Windows NT Registry. This key must appear as a subkey of the gateway service’s registry entry. The following figure shows the registry entry for the MSExchangeDS service.

The path to the Diagnostics registry entry is

HKEY_LOCAL_MACHINE\ SYSTEM\CurrentControlSet\Services\Service Name\Diagnostics

where Service Name is the name of your gateway’s Windows NT Server service. To activate the Administrator program’s Diagnostics Logging property page for your gateway, the Diagnostic-reg-key attribute of your gateway’s Mail-Gateway object must be set to Service Name.

Subkeys of the Diagnostics key represent loggable events. The preceding figure shows 15 such events defined. Each event description consists of a resource identifier number followed by a string. The value associated with each subkey represents the significance level for logged events of that type.

Significance levels range from from 0 to 5, with 0 being the most significant (such as critical errors) and 5 the least significant (such as debugging output). The Microsoft Exchange Server administrator uses the Diagnostics Logging property page to set a diagnostic logging level that determines which events are written to the Windows NT Application event log. This level is typically set to 0 (critical errors), 1 (minimal), 3 (medium), or 5 (maximum). Events with a value less than or equal to the logging level are written to the event log. For more information about how the diagnostic logging level is used, see the Microsoft Exchange Server Administrator’s Guide.

To localize the registry key names to other languages, you must provide a resource DLL that contains the localized version of the event description strings for each language. An event description’s resource identifier number is the same in all languages. The resource DLL is placed in the server’s RES directory, which is shared as \\ServerName\RESOURCES. You must also create a DiagnosticsMessageFile registry key under the gateway service, containing the name of the DLL. The resource DLL is built from an .MC file so that it is in the correct format for the Windows NT Application event Log.


Installing an Admin-Extension Object

If your gateway uses custom property sheets to present data to administrators, its setup program must install them. This means that it must install the Admin-Extension object in the directory and copy the Administrator extension DLL and any other necessary files to specific locations on the server. For information about copying files, see Copying Files Onto Disk.

To install an Admin-Extension object
  1. Verify whether the Admin-Extension object already exists in the directory, using MAPI functions or the BatchExport function. See Finding an Object in the Directory.
  2. If the Admin-Extension object does not exist, skip to step 4. If the object does exist, check its version. This is a multistep procedure that uses calls to the HrGetFileVersionInfo, HrAdminExtensionExists, and HrGetAdminExtensionVersion functions and to the Win32 VerQueryValue function.
  3. If the installed Admin-Extension object is newer than the one to be installed, use a dialog box to ask the user whether to overwrite the installed object with the older one on the distribution medium. If the user answers Yes, proceed with step 4. If the user answers No, end the installation of this Admin-Extension object. If other Admin-Extension objects need to be installed, begin again at step 1.
  4. Call GUIDGEN.EXE to generate an extension name, or make up a unique extension name for the Admin-Extension object.
  5. If there is already an Admin-Extension object with the same name as the one you are installing, remove the installed one by calling the HrRemoveAdminExtension function and passing the extension name of the Admin-Extension object.
  6. Copy the files associated with the Admin-Extension object to the Microsoft Exchange Server computer. See Files Used with Directory Objects.
  7. Create the new Admin-Extension object with the BatchImport function or DAPIWrite function. Use the GUID created in step 4 for the extension name of the object. If other Admin-Extension objects need to be installed, begin again at step 1.

For sample code that performs these steps, see the GWSETUP.C file in the \BKOFFICE\SAMPLES\EXCHANGE\GWSETUP directory.

For general information about working with Administrator extensions, see Administrator Program Extensions. For information about setting the attribute values of the Extension-Data attribute, see Initializing the Extension-Data Attribute.


Copying Files Onto Disk

If you make installed files such as Administrator extension DLLs centrally accessible, administrators can control the gateway through its associated directory object from any computer on the site. A setup program can facilitate this by copying certain files into specified directories.


Files Used with Directory Objects

When Microsoft Exchange Server is installed, it creates the following publicly exported directory shares:

\\Server-name\ADD-INS

\\Server-name\ADDRESS

\\Server-name\CONNECT$

Under these directories, subdirectories called Extension-Name\Platform designate the name of the Administrator extension object or Addr-Type object being installed and the platform on which it runs. (For information about platform designations, see Installing the Administrator Extension DLL.) The gateway setup program must create the Extension-Name\Platform subdirectories, along with the directory for the gateway’s executable file.

Use these directories as follows:

  • Files for Administrator extension DLLs Gateways that use a DLL to insert extension data into the directory should install their public files in \\Server-Name\ADD-INS\Extension-Name\Platform.
  • Files for address types If the gateway creates a new address type, files used by the Addr-Type object should be installed in \\Server-Name\ADDRESS\Address-Type\Platform. Note that the address type appears in the PR_ADDRTYPE property in the recipient table of a message, as well as in other message properties.
  • Other files Other public files, such as those that provide server-specific configuration information, should be installed in \\Server-Name\CONNECT$\Extension-Name\Platform.


Installing the Executable File

Your gateway’s executable file is copied into a directory specified by the administrator installing the gateway. You must install a gateway onto the computer on which you run the setup program, although this computer need not be the Microsoft Exchange Server computer. For example, if you want to run a gateway on Computer A, run the setup program and install the gateway’s files on Computer A — even though Computer B may be the actual Microsoft Exchange Server computer to which you will connect the gateway.


Example: Administrator Extension Installation

An SMTP gateway called PRO-SMTP is written by the fictitious company Pro-Electron, Inc. This SMTP gateway is installed to a server called PROTON running Microsoft Exchange Server, the gateway name PRO-SMTP is used as the Extension-Name, and the files are for the i386 (Intel) platform.

In this installation, the setup program copies both PROADMIN.DLL (the Administrator extension DLL) and PROADMIN.HLP (the Help file for the gateway’s extension property sheets) to \\PROTON\ADD-INS\PRO-SMTP\I386. The proxy generation DLL for this gateway is copied to the \\PROTON\ADDRESS\PRO-SMTP\I386 directory.

The gateway setup program displays a dialog box that lets the administrator choose the destination of the gateway’s executable file. This destination directory is saved in the Windows NT Registry on the gateway’s computer.

Note The Common-Name attribute of a directory object is a concatenation of the values used for Extension-Name and Platform. For example, the gateway in the preceding example would have a common name of PRO-SMTP:i386, and the Administrator program would recognize it only by this name. Therefore, your setup program must use the Extension-Name and Platform values consistently when it copies files and when it imports the gateway’s directory object.

The sample setup file GWSETUP.C first builds a list of files to be copied, then calls the CopyFilesInCopyList function of the Setup API in the Win32 SDK.


Setting the Server Heuristics Attribute

The Server object in the Microsoft Exchange Server directory has a Heuristics attribute. Bits on this attribute can be set to specify that gateways and connectors are installed or that replication is enabled. The Microsoft Exchange Server Administrator program uses the Heuristics attribute to determine which containers, property pages, and menu options to make available for clients.

Your gateway setup program must set the Gateway bit on the Heuristics attribute so that the Administrator program will display menu options and containers that relate to gateways and custom recipients.

To set the Gateway bit on the Heuristics attribute
  1. Retrieve the current Heuristics attribute on the Server object.
  2. Perform a bitwise OR operation with this attribute and the value 0x02.
  3. Set the result of the bitwise OR operation into the Server object’s Heuristics attribute.

To set the Gateway bit, call the HrSetGatewayBit function. The sample code from the GWSETUP program contains an example of calling this function.

Note When removing a gateway, do not clear the Gateway bit from the Heuristics attribute.


Creating the Directory Object

Your gateway must be recognized by other programs such as the Microsoft Exchange Server Administrator program. Therefore, the setup program must create a new object for your gateway in the Microsoft Exchange Server directory and provide initial object attribute values. The setup program can set most of these values as defaults, while others (such as the server name) can be specified by the user through a setup dialog box. When you add a new Mail-Gateway object to the directory, an associated mailbox and folder hierarchy is created in the server’s information store.

A gateway setup program calls the Microsoft Exchange Server directory access functions to create the object that represents the gateway in the directory and to write the object’s attributes to the directory. It presents dialog boxes to the administrator for entering attribute values, such as the address space serviced by the gateway. The directory access functions are described in Directory Operations. Setup programs can use the BatchImport or DAPIWrite directory access functions to create the directory object. The sample gateway installation program GWINST.C in the \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU directory prepares for and calls BatchImport.

To import a directory object, a gateway setup program first obtains all necessary configuration information from several sources. It reads default data from the gateway’s header files and uses some of the default values that correspond to gateway applications. It also copies extension data from the extension data file on the distribution medium. For more information, see Initializing the Extension-Data Attribute.

Note Your gateway setup program should always set the gateway object’s Computer-Name attribute with the name of the Microsoft Exchange Server computer. This attribute is required for the Administrator extension interface to work correctly. The GWSETUP program provides an example of setting Computer-Name, using the GetComputerName function.


Initializing the Extension-Data Attribute

Gateways can use the Extension-Data attribute to store custom data in the directory. This data can be manipulated through custom property pages implemented in an Administrator extension DLL.

During the setup procedure, the Extension-Data attribute must be initialized. You can use the CFGCODE utility to create a file holding default Extension-Data values. After this extension data file is created, it can be used during application setup. When the customer runs the setup program, the file can be copied directly into the directory object’s Extension-Data attribute. Its binary contents are formatted correctly for storage in the Microsoft Exchange Server directory as an attribute on the application object. For more information, see CFGCODE: Generating a Packed Property Structure.

You may need to create the Extension-Data values based on values entered by the customer while running the setup program. In this case, you can create the extension data file by calling HrCfgPackData and writing the resulting output to a file. GWSETUP.C provides an example of how to do this.

The setup program also performs this write operation using directory access function calls.


Installing Addressing

A customer may want to install the gateway’s addressing separate from installing the gateway. For example, suppose the customer has installed a gateway on site A, but not on site B. The two sites are connected by a site connector. Messages from site B that are addressed to recipients served by the gateway are routed to site A and pass through the gateway. Therefore, the customer will install the gateway addressing on site B, even though the gateway itself is not installed there. To allow this kind of routing, the customer would need to install the Addr-Type object, proxy generation DLL, and optionally the Administrator extension DLL on every site that uses the site A gateway. Your setup program should allow for this.


Updating the Gateway-Proxy Field of the Site Object

When you install the Addr-Type object, you must add information to the site proxy address field (the Gateway-Proxy attribute) of the site object. This means that you are adding another value to the multivalued Gateway-Proxy field (for proxy addresses) of the site object. The Gateway-Proxy field for each site contains information that proxy generation DLLs use to create addresses for the users at that site. This site object should have one proxy address for each Addr-Type object installed; this also means that it has one proxy address for each address template installed.


Rebuilding the Gateway Address Routing Table

Any time you add, delete, or change address type information, you need to rebuild the gateway address routing table (GWART). The sample gateway setup program, GWSETUP, provides an example of rebuilding the GWART by calling the SAD_ScRunRID function.


Generating Recipient Proxy Addresses

Your setup program should let the user start a bulk Create Proxy operation. This generates a proxy address of the new type you are installing for all existing recipients on the site. (The proxy generation DLL, called by the Microsoft Exchange Server Administrator program, will automatically generate proxy addresses for recipients added later.)

The sample gateway setup program, GWSETUP, illustrates function calls for the proxy generation process. It calls SAD_ScBulkCreateProxy to create the new proxy addresses. This function starts the process on the server running Microsoft Exchange Server and then returns control to the setup program while the proxy addresses are being created. If you want to keep the user informed of the progress of proxy generation, you can periodically call SAD_ScGetBulkProxyStatus and use its information to display progress.

The proxy address generator needs to log errors. If you use event logging, you need to register the proxy generation DLL with the Windows NT Application event log. The DLL registers on the server running Microsoft Exchange Server to which it is connected.


Installing Performance Monitoring

A setup program can install performance monitoring, a process that includes defining the gateway data that will be used by the Windows NT Performance Monitor. Performance data is represented as a set of individual data items called counters.

As shown in the sample gateway setup program GWSETUP.C, you can install performance monitoring in two steps.

To install performance monitoring
  1. Call the HrInstallServicePerfMon function of EXCHINST.C, in the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\EXCHINST directory. This function creates a performance monitor object (or class) in the Windows NT Registry, and creates keys for that object. It also creates a single Registry instance of this class.
  2. Call the FLoadCounters function to load performance counters into the newly created Windows NT Registry entry. Later, when you run the Windows NT Performance Monitor, the object and instance (with default counters) will be available. Your setup program should call FLoadCounters only for the first instance of the gateway being monitored. The FLoadCounters function is defined in EDKSETUP.H.


Removing a Gateway

The DoRemove function in GWSETUP.C shows how to remove a gateway service’s entire installation. The following procedure lists the steps for removing a gateway in the order in which DoRemove performs them. You can use the steps that are relevant for removing your gateway.

To remove a gateway
  1. Present a dialog box in which the administrator can select an application to remove. The ShowChooseServiceDlg function displays such a dialog box.
  2. Determine whether the gateway service is running by calling the FServiceRunning function. If it is running, attempt to stop the service.
  3. Remove the directory object. Call the HrRemoveGateway function to remove a gateway object from a given site. This function is defined in EXCHINST.C.
  4. Remove performance monitoring for the service by calling the HrRemoveServicePerfMon function. If the lpfUnloadCounters parameter returned from this function call is TRUE, continue with step 5. If it is FALSE, multiple instances of the gateway are installed. In this case, perform steps 7 and 8, and then begin again at step 1.

    Note The performance counters are unloaded and the registry entries are deleted only after all instances of the gateway have been removed.

  5. Call the FUnloadCounters function to unload the counters used in performance monitoring.
  6. Remove the gateway’s keys from the Windows NT Registry by calling the HrRemoveRegistry function.
  7. Remove the gateway service from the Windows NT service control manager by calling the HrRemoveService function.
  8. Delete the files belonging to the gateway using the EDKDeleteNode function.

The DoRemove function removes gateway components from the local computer. Server components in the Microsoft Exchange Server directory must be removed in a separate step using directory access functions. For example, address types and Administrator extensions are not removed because they may be needed by other applications.

When removing a gateway, your program should not remove address templates and extension DLLs and their associated objects. This is because these components may still be in the process of being used by other applications.


Sample Gateway and Applications

The Microsoft Exchange Server SDK includes a sample gateway that illustrates common gateway features. The sample code for each feature is isolated in its own module so that you can use it directly or as a starting point for developing your own gateway code.

This section describes:

  • Sample gateway features.
  • Installing and running the sample gateway.
  • Building and running sample gateway applications.
  • Installing gateway components.


Sample Gateway Features

You can use the sample gateway to send messages back and forth between two servers using a shared filesystem as the underlying transport mechanism. The gateway receives inbound messages as files. The gateway creates messages from the information in the files and submits them. The gateway receives outbound messages in its MTS-OUT folder, and converts them into files for output. The sample gateway performs message translation and transfer functions, and generates notification messages as requested.


Configuring the Sample Gateway

How the gateway is configured controls where the gateway looks for incoming message files and where it places outgoing message files. It also controls other details about message processing, including the address type and the location of conversion DLLs. The configuration dialog box is supplied by the gateway's extension DLL and is discussed in Using SGWADMIN.DLL.

The gateway only responds to configuration changes when it is started.


Operation as a Windows NT Service

The sample gateway is a single executable file (GWSAMPLE.EXE) that uses two message conversion DLLs (IPM_IN.DLL and IPM_OUT.DLL). It is started and stopped as a service running on Windows NT Server. If it shuts down because of a nonrecoverable error, the status is reflected in the Windows NT service control manager (SCM).

The sample gateway supports the pause/resume feature. When the SCM requests that the gateway pause, the gateway will not pick up any new messages for processing. When the gateway pauses, it will signal that it is paused and will not perform any more actions until it is resumed. Pausing the gateway will not cause it to declare any messages as nondeliverable.


Message Transport Features

Transport features of the sample gateway include:

  • Native transport
  • TNEF
  • Message classes
  • Delivery reports
  • Address mapping
  • Message identifiers
  • Message trace
  • Message content translation.

Native Transport

The sample gateway provides native transport, which means it uses its own format for transporting the content of a message. Messages are encoded in a format based on RFC 822. This message format is shown in Sample Gateway Message Format.

If a syntax error occurs in the message envelope, the gateway places an event in the Windows NT Application event log indicating the message identifier and that it was rejected because of a syntax error. If there is a syntax error in the message content, the message is declared as nondeliverable.

The sample gateway does not support nested messages. It will not stop if it detects a nested message, but it will not attempt to preserve the content of nested messages.

TNEF

The sample gateway always looks for a TNEF attachment when it receives a message and, if there is one, extracts any MAPI properties from it. If at least one recipient of a message is a MAPI recipient, the gateway generates a TNEF attachment in addition to the regular content of the message. The gateway ensures that each attachment has a unique file name relative to the message, and automatically creates unique attachment names if the message has multiple attachments with the same name. The gateway uses TNEF mechanisms to preserve attachment locations. Applying TNEF to a message preserves embedded messages while using native transport does not.

If a message is addressed to both MAPI and non-MAPI recipients, the gateway creates two files: one with a TNEF attachment for MAPI recipients and one without a TNEF attachment for non-MAPI recipients.

Message Classes

The message class determines how the gateway transports a message. IPM and REPORT messages are detected and transported differently. Other classes of messages are simply nondelivered, which means that a nondelivery report (NDR) is sent to the originator of the message. A useful enhancement to the sample gateway would be the ability to delivery any message class by packaging all the message's properties in a TNEF attachment and sending that attachment as the sole content of the outgoing message. The gateway could still generate NDRs if there are no MAPI recipients of such a message.

Delivery Reports

The sample gateway transports delivery reports, nondelivery reports, receipt notifications, and nonreceipt notifications as distinct message classes. It does this by defining a native format for the encoding of REPORT messages.

Address Mapping

The sample gateway uses the MAPI IAddressBook::PrepareRecips method to map recipients to an address type that is configurable, which is initially set to EDK. Messages are nondelivered for Responsibility-TRUE recipients that cannot be mapped. Responsibility-FALSE recipients that cannot be mapped are dropped from the message.

Message Identifiers

The sample gateway passes Microsoft Exchange Server message identifiers through the transport without converting the identifiers into special attributes. It passes these identifiers in the X-Message-ID and X-Message-Subject-ID header fields.

Message Trace

The sample gateway writes information for the PR_TRACE_INFO property whenever a message passes through it. The PR_TRACE_INFO property is discussed in Message Transfer.

The external trace information is saved in the External-Received-By, External-Received-At, External-Attempted-By, and External-Deferred-At header fields as shown in the message example in XLATDRIV: Translating Messages. The internal trace information found in the PR_INTERNAL_TRACE_INFO property is saved in the Internal-Received-By, Internal-Received-At, Internal-Attempted-By, and Internal-Deferred-At header fields. The external trace information is used to prevent loops in message delivery between different sites, while the internal trace information is used to prevent loops in message delivery within a site.

Message Content Translation

The sample gateway translates both inbound and outbound messages. For outbound messages, the input is an LPMESSAGE pointer to the envelope and the output is a stream on a file. This is reversed for inbound messages. Translations are supported for ENVELOPE.IPM and REPORT.IPM message classes.


Sample Gateway Installation and Operation

The GWSETUP.MAK file in the \BKOFFICE\SAMPLES\EXCHANGE\GWSETUP directory creates a new GWSETUP directory, as well as the GWSETUP.INF file that is used for setting up the sample gateway.

Note Before you can install the sample gateway, you must build all the sample applications. See Building the Sample Applications for general information about the build process. If the sample applications do not exist in the corresponding \BKOFFICE\SAMPLES\EXCHANGE directories (not in the \BIN directory), INFLINE.EXE will fail when you attempt to install the gateway.


Installing the Sample Gateway

If you are installing the sample gateway for the first time, or if you have changed any of the files listed here since your previous installation, you need to create a new GWSETUP.INF file before proceeding. Files referenced in GWSETUP.INF are:

  • EDKADT.HLP
  • GWPERF.DLL
  • GWSAMPLE.EXE
  • IPM_IN.DLL
  • IPM_OUT.DLL
  • PROXYGEN.DLL
  • SGWADMIN.DLL
  • SGWADMIN.HLP

To create the GWSETUP.INF file
  1. Change to the \BKOFFICE\SAMPLES\EXCHANGE\GWSETUP directory.
  2. Type the following command:

    NMAKE - F GWSETUP.MAK

    This process uses the default settings for the BLDTYPE and TARGETDIR environment variables unless you manually change them. You can view the environment variables by typing SET at the command prompt.

You can install the sample gateway either by using the GWSETUP.EXE program to automatically install all the gateway components, or by installing individual gateway components. See Installation Programs for information on how to install components.

The gateway setup program GWSETUP.EXE performs the following actions:

  • Obtains information about the gateway environment and the Mail-Gateway object.
  • Installs the Admin-Extension object for the gateway.
  • Installs the Addr-Type object associated with the gateway.
  • Copies the necessary files to the server.
  • Creates the gateway site proxy address for the address type.
  • Creates proxy addresses of the new address type for existing recipients in the Microsoft Exchange Server directory.
  • Installs the Mail-Gateway object in the directory.
  • Rebuilds the gateway address routing table (GWART).
  • Installs the message conversion DLLs used by the gateway.
  • Installs performance monitoring counters for the gateway service. (Note that GWSETUP.EXE only loads the counters; it doesn't actually install the performance monitor.)

These functions are discussed in Writing the Setup Program.

To install the sample gateway using GWSETUP
  1. Select Sample Gateway Setup in the Microsoft Exchange Server SDK program group

– Or –

Change to the command prompt and run SETUP.EXE from the \BKOFFICE\BIN\GWSETUP directory.

  2. Click Continue.
  3. Click Install.
  4. In the Choose Server dialog box, enter the name of the computer running Microsoft Exchange Server on which you want to install the gateway, and click Continue.
  5. In the Choose Site dialog box, select the site name for the gateway (for example, /o=Microsoft/ou=site) and click Continue.
  6. In the Directory Display Name field of the Install dialog box, type the name of the gateway to be used by the Microsoft Exchange Server Administrator program (for example, samplegw).
  7. In the Service Display Name field, enter the name to be displayed for the gateway when it is listed as a service. This name can be the same as the Directory Display Name.
  8. For Service Account, enter the Windows NT Server account that has been created for the gateway. The account must have "Log On as Service" rights. This should be specified as domain\account (for example, operations\gwuser).
  9. For Service Password, enter the password for the Windows NT Server account.
  10. For Service Directory, enter the directory for the gateway executable file, including the drive name. (C:\GW is the default directory.)
  11. Click Continue.

The setup program performs the following tasks:

  • Creates a directory with the path and name specified as Service Directory in step 10 above.
  • Copies the gateway's executable file, GWSAMPLE.EXE, to the service directory.
  • Creates two subdirectories, IN and OUT, under the service directory. The sample gateway uses these subdirectories for message processing.
  • Displays a message when the gateway object is installed.

You can verify that the gateway object is installed by looking in the Connections container inside the Microsoft Exchange Administrator program for the gateway name. This is the Directory Display Name entered in step 6 above. If the gateway name is not there, click Refresh on the Window menu in the Administrator program. The name should then appear.

The sample gateway uses the account and password information entered in steps 8 and 9 above. After the gateway service is installed, its associated account information can be changed through the Windows NT service control manager.


Running the Sample Gateway

To prepare for running the sample gateway
  1. Install instances of the gateway on two servers.
  2. Create the required gateway directories on each server.
  3. Share the gateway directories between the servers.
  4. Create a mailbox for each gateway.
  5. For each gateway, create a custom recipient entry for the other gateway.

After the sample gateway is installed, you can run it from the command prompt or as a service running on Windows NT Server.

To run the sample gateway as a service of Windows NT Server
  1. Double-click Control Panel.
  2. Double-click Services.
  3. Select the sample gateway.
  4. Click Start.

To run the sample gateway from the command prompt
  1. Change to the directory in which you installed the gateway. (C:\GW is the default directory.)
  2. At the command prompt, type:

    START GWSAMPLE NOTSERV gwguid

    where gwguid is the identifier that was automatically created by the Win32 function CoCreateGUID when you installed the gateway. You can find the value for gwguid in the Windows NT Registry.


Using SGWADMIN.DLL

The SGWADMIN DLL creates the Administrator extension for the sample gateway. Use the Options tab to display a dialog box in which you can specify the gateway's configuration.

Sample gateway Administrator extension dialog box

The fields in the dialog box are:

  • Address Type Address type of messages passing through the gateway. The default is EDK.
  • System Administrator Display name and e-mail address of the system administrator.
  • Messages to Process Indicates whether the gateway will process inbound and outbound messages. A checked box indicates that the gateway will process that type of message. The remaining fields in the dialog box have two columns of values, one for inbound messages and one for outbound messages.
  • Threads Number of threads used to process messages.
  • Messages Per Thread Number of messages processed in each thread.
  • Sleep Per Message The length of time it takes to process one message. If the gateway finishes processing a message before this interval has elapsed, it waits until the end of the interval before starting to process the next message.
  • Polling Interval If this is set to NOTIFICATION, the gateway uses notifications to determine when to process the next message. For incoming messages, it uses the first change notification; Windows NT Server tells the gateway when there is a change in the incoming message directory. For output messages, it uses the MAPI notification mechanism to determine when messages arrive in the MTS-OUT folder.

    If this is set to a value greater than –1, the gateway waits that many milliseconds before trying to process another message.

  • Directory Name of the directory from which the gateway reads incoming messages or to which it writes outgoing messages. The directory name must be preceded by a backslash (\).
  • Converter Pointers to the locations of conversion DLLs for the inbound and outbound messages.

Note The preceding information is available as online Help for this dialog box.


Gateway Sample Applications

Several sample applications illustrate gateway-related programming tasks. Each sample application is located in its own directory under \BKOFFICE\SAMPLES\EXCHANGE. They are:

Sample | Purpose
LOOKUP | Looks up proxy addresses.
PERFTEST | Performance monitoring.
PROXYGEN | Generates proxy addresses.
QUEVIEW | Displays the contents of the gateway's incoming and outgoing folders.
RPTDRIV | Driver for report generation.
XLATDRIV | Driver for message translation.

See Installation Programs for more information about installing each of these sample applications. For information about setting up your development environment, see Development Environment.


Installing Gateway Components

The following sample applications relate to installing gateway components. They are located in the \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU directory.

Note In practice, gateway developers usually combine this functionality into a single setup program. They are kept separate here to make the sample code simpler to understand.

ADDRINST: Installing an Addr-Type Object

EXTNINST: Installing an Administrator Extension

GWINST: Installing a Mail-Gateway Object

PERFINST: Installing Performance Monitoring

PROFINST: Installing a MAPI Profile

SERVINST: Installing a Service

TMPLINST: Installing an Address Entry Template

XLATINST: Installing a Message Conversion


Building the Gateway Sample Applications

To compile a gateway sample application
  1. Change to the directory containing the application's source files.
  2. Type NMAKE.

    For example, to compile the LOOKUP sample application, type the following:

    CD \BKOFFICE\SAMPLES\EXCHANGE\LOOKUP\NMAKE

To build all sample applications and libraries at once

Type the following at the command prompt:

CD \BKOFFICE\SAMPLES\EXCHANGE\NMAKE

This builds the sample applications in their own component directories as if you had built each one separately.

To build only the Microsoft Exchange Server SDK libraries

Type the following command:

CD \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\NMAKE

General NMAKE options are described in Development Environment.


LOOKUP: Finding a Proxy Address

The LOOKUP sample application enables you to enter a user's address and the address type to which you want it converted. The program does an exact match on the proxy address and is able to look up hidden recipients. The LOOKUP program does the following:

  • Calls the function HrGWResolveAddress to locate the recipient entry identifier of the address you input.
  • Calls HrGWResolveProxy to find the corresponding address of the type you specify.
  • Indicates whether it is a MAPI recipient and prints its EX address if the address is resolved.
  • Returns an error code and asks you to enter another address if the address cannot be found.

Note Some address types are case-sensitive and others are not. When comparing addresses, applications should compare byte-for-byte, and should always use uppercase for case-insensitive address types.

To build LOOKUP
  1. Change to the directory containing the LOOKUP source files:

    \BKOFFICE\SAMPLES\EXCHANGE\LOOKUP

  2. Type NMAKE.

To run LOOKUP
  1. At the command prompt, change to the \BKOFFICE\BIN directory.
  2. Type LOOKUP [ProfileName]. You will be prompted to enter the address you want resolved.
  3. To end the run, type EXIT at this prompt. Otherwise, enter an address to be resolved, in the format <address type>:<address>. For example:

    SMTP:John@Microsoft.com

    You will be prompted to enter the address type that you want returned.

  4. Enter the new address type; for example, MS for an address in Microsoft Mail format. If the resolved address is available, LOOKUP returns it and indicates whether it is a MAPI recipient. If the address is unavailable, LOOKUP returns an error message.
  5. Repeat, beginning with step 3.


PERFTEST: Monitoring Performance

The PERFTEST sample application demonstrates how to monitor the performance of gateways using the Windows NT Performance Monitor. The PERFTEST application also demonstrates MONITOR.LIB functions. For more information about the performance monitor, see Using the Performance Monitor and Installing Performance Monitoring.

The PERFTEST sample application performs some gateway functions in that it receives and sends messages. But as a testing application, PERFTEST cannot receive messages from foreign systems. When a user sends a message, PERFTEST adds its own header to the subject line of the message and then returns it to the sender. This behavior lets you control the test closely by sending messages to PERFTEST. The performance monitor process is described in Performance Monitoring.

Note When GWSETUP installs the sample gateway, it automatically creates a class key for the gateway in the Windows NT Registry. PERFTEST looks for a specific class key named PerfTestType in the registry, so it won't run on the sample gateway as installed by GWSETUP. If you create a new PerfTestType key for the sample gateway, you will have two keys pointing at the same object, and you will see two identical objects when you view the performance data in the Windows NT Performance Monitor.

If the sample gateway was installed using GWSETUP, you must completely remove it and reinstall it using the installation programs GWINST.EXE, SERVINST.EXE, and PERFINST.EXE. This procedure installs a new service, gateway object, and performance monitoring information (using the PerfTestType class key) for PERFTEST to use.

To build PERFTEST
  1. Change to the directory containing the PERFTEST source files:

    \BKOFFICE\SAMPLES\EXCHANGE\PERFTEST

  2. Type NMAKE.

PERFTEST is usually run as a nonservice application, but it can also be run as a service.


Monitoring Performance with PERFTEST

PERFTEST is used to monitor the performance of a gateway. Standard counters are available, or you can add your own counters by modifying the sample code.

If you want to add additional counters, you may want to modify the COUNTERDEF array in the source code. Refer to COUNTERDEF for more information about this structure because the counters must be added in the correct sequence.

The following procedures describe how to run PERFTEST as either a standalone application or as a service of Windows NT Server.

To run PERFTEST as a standalone application
  1. At a command prompt, change to the \BKOFFICE\BIN directory.
  2. Verify that a gateway has been installed. See Installing the Sample Gateway. For a simple procedure for setting up and verifying a gateway, see Importing and Exporting with DIRSYNC.
  3. Set up the Windows NT Registry information for PERFTEST by typing the following command:

    PERFINST /SERVICE=<gateway-name> /CLASS=PerfTestType /DLL=C:\BKOFFICE\BIN\GWPERF.DLL /OPEN=OpenGatewayPerformanceData /COLLECT= CollectGatewayPerformanceData /CLOSE=CloseGatewayPerformanceData

    The following new registry key is created for PERFTEST: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PerfTestType\Performance and Linkage.

    The Library value in this new registry key is configured to search for GWPERF.DLL in the \BKOFFICE\BIN directory.

  4. Change to the BKOFFICE\SAMPLES\EXCHANGE\PERFTEST directory.
  5. Type LODCTR PRFCOUNT.INI. This step loads the counter information into the PERFTEST registry entry.
  6. Run PERFTEST by typing PERFTEST NOTSERV <gateway-name>

    An icon labeled Performance Monitoring Sample is displayed at this point. It indicates that PERFTEST is running as an application.

  7. Start the Windows NT Performance Monitor and add the counters to be monitored.
To run PERFTEST as a service of Windows NT Server
  1. At a command prompt, change to the \BKOFFICE\BIN directory.
  2. Install a gateway if one is not installed. See Sample Gateway and Applications for more information. Do not use GWSETUP to install the gateway when you are using PERFTEST to monitor the gateway because GWSETUP creates objects and pointers that conflict with PERFTEST. If GWSETUP has been used to install the gateway, you should completely remove and reinstall the gateway prior to using PERFTEST. See Removing a Gateway and Installing the Sample Gateway.
  3. Set up the Windows NT Registry information for PERFTEST by typing the following command:

    PERFINST /SERVICE=<gateway-name> /CLASS=PerfTestType
    /DLL=c:\BKOFFICE\BIN\GWPERF.DLL
    /OPEN=OpenGatewayPerformanceData /COLLECT=CollectGatewayPerformanceData /CLOSE=CloseGatewayPerformanceData

    A new registry key is created for PERFTEST: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
    PerfTestType\Performance and Linkage.

  4. Change directory to \BKOFFICE\SAMPLES\EXCHANGE\PERFTEST
  5. Type LODCTR PRFCOUNT.INI.
  6. Now you can run PERFTEST by typing PERFTEST <gateway-name>.
  7. Start the Windows NT Performance Monitor and add the counters that you want to monitor.
    • Select NT PERFMON from the Administrative Tools menu.
    • Click Add Counters.
  8. Select PERFTEST from the Object drop-down combo box.
  9. Select the counter you want to monitor for the gateway.
  10. Log on to a mailbox with the Microsoft Exchange Client.
  11. Submit a message to a custom recipient associated with the gateway that you are monitoring. The message will be returned to you and the counter on Windows NT Performance Monitor will reflect the message's effect on the gateway.


PROXYGEN: Generating a Proxy Address

PROXYGEN is a DLL that generates a proxy address of type EDK for the sample gateway. It creates the address from a combination of site and recipient attributes as determined by the site level proxy.

PROXYGEN demonstrates the use of the following functions:

RcInitProxies_edk_RcInitProxies

RcGenerateProxy_edk_RcGenerateProxy

RcValidateProxy_edk_RcValidateProxy

FreeProxy_edk_FreeProxy

To use it, you must first install the EDK address type by running the sample gateway setup program.

To build PROXYGEN
  1. Change to the \BKOFFICE\SAMPLES\EXCHANGE\PROXYGEN directory.
  2. Type NMAKE.

When you modify an existing proxy address, Microsoft Exchange Server automatically calls the proxy generation DLL to validate the changes. If the modified address contains invalid characters or other errors, Microsoft Exchange Server displays an error message and the DLL writes an error message to the Windows NT Application event log. The RcValidateProxy routine in PROXYGEN verifies that a manually entered proxy is valid.

The PROXYGEN DLL demonstrates several features for creating and modifying proxy addresses. You can use these features or similar ones in your gateway. For complete information, see the PROXYGEN sample code. The following is a summary of PROXYGEN features:

  • When the gateway is installed, the setup program installs a site address. You can insert special characters in the site address to tell PROXYGEN how to create individual proxy addresses. This feature appears in the RcGenerateProxy function. The RcGenerateProxy function creates proxy addresses based on the site proxy address string, which has the following format:

    EDK: format@domain

    Domain is uninterpreted and is written exactly as is.

    Format is optional; if specified it must contain only valid EDK address characters plus the following special symbols:

%s | Substitute the user's surname.
%g | Substitute the user's given name.
%d | Substitute the user's display name.
%m | Substitute the user's mailbox (alias) name.
%% | Substitute a single %.
%r | Substitute characters within a format string. See the following paragraph for details.

In all the substitutions listed in the table, spaces and illegal characters will be removed from the field before the substitution is made. If there is no format field, the site proxy address format is equivalent to:

EDK: %m@domain

Use the %r symbol to specify replacing one character with another in subsequent substitutions in the format string. For example, the format

%g%r ch1 ch2 %s

means that all instances of the character ch1 will be replaced by ch2 in all surnames as the proxy addresses are generated. In this case, since the %r symbol follows %g, given names are inserted in the proxy address with no character replacements.

  • PROXYGEN performs automatic character translation if a name contains extended characters. In the EDK type, you can use only 7-bit ASCII characters. See the table in the RcGenerateProxy code that performs the translation.

You can use the path that is set up for PROXYGEN to test your own proxy generation DLL. The Address Types property page in the Microsoft Exchange Server Administrator program shows the display name and path of the proxy generation DLL. For testing, you can edit the proxy address path to point to your own proxy generation DLL. This way you can check if the DLL is generating the correct proxy address without having to install a new address type.

If you use this method, however, your DLL must produce addresses that begin with "EDK."


QUEVIEW: Listing Gateway Folders

QUEVIEW is an Administrator extension application that adds a new property page to the Microsoft Exchange Server Administrator program. From this property page, administrators can view messages in gateway queue folders. They can also perform actions on the messages in the queue folders if they have the appropriate rights.

Use this application to view gateway folders, specifically MTS-IN and MTS-OUT, and to view messages in transit while they are in these folders (also known as the queue).

Although QUEVIEW is an Administrator extension application, it uses no extension data. The information it displays on its property sheets is a snapshot of folders and their contents that are obtained when QUEVIEW is started. QUEVIEW does not update its display in real time, but it does provide a Refresh button that updates the display.

To build QUEVIEW
  1. Change to the directory containing the QUEVIEW source files:

    \BKOFFICE\SAMPLES\EXCHANGE\QUEVIEW directory.

  2. Type NMAKE.

To run QUEVIEW, connect it to a gateway running on your computer.

To run QUEVIEW
  1. Under the directory \EXCHSRVR\ADD-INS, create the directory \QUEVIEW\I386. For DEC-Alpha computers, see the Note that follows the last step.
  2. Copy QUEVIEW.DLL from \BKOFFICE\BIN to
    \EXCHSRVR\ADD-INS\QUEVIEW\I386.
  3. Install QUEVIEW.DLL using EXTNINST.EXE.

    For example:

    EXTNINST /SITEDN=/o=Microsoft/ou=Redmond
    /DISPLAY_NAME="EDK Queue Viewer Extension for I386" /MACHINE=i386 /NAME=QUEVIEW
    /EXTDLL=\\myserver\add-ins\queview\i386\queview.dll
    /SERVER=myserver

  4. In the Microsoft Exchange Server Administrator program, edit the gateway's raw attributes. (Start ADMIN.EXE with the /RAW parameter. On the File menu, click the Raw Properties option.)
  5. List attributes of type All.
  6. Edit the attribute Extension-Name; enter QUEVIEW as the new extension name.
  7. Click Add, then click OK. This automatically closes the gateway's property sheet.
  9. Reopen the gateway's property sheet.
  10. Click the Queue Viewer tab.

Note To run QUEVIEW on the DEC-Alpha platform, follow the preceding steps, substituting "Alpha" for "I386" in all cases. For example, Step 1 becomes: "Under the directory \EXCHSRVR\ADD-INS, create the directory \QUEVIEW\Alpha".

Now when you select a folder, messages currently in that folder will be displayed.


RPTDRIV: Generating Reports

The RPTDRIV sample application uses REPORT.LIB functions, which generate delivery, nondelivery, receipt, and nonreceipt reports. RPTDRIV logs on to the messaging system as a gateway so you can send mail messages to it. RPTDRIV reads each message and generates a report, sending the report to the originator of the message.

To build RPTDRIV
  1. Change to the directory containing the RPTDRIV source files:

    \BKOFFICE\SAMPLES\EXCHANGE\RPTDRIV directory.

  2. Type NMAKE.

To run RPTDRIV
  1. Install the sample gateway. See Installing the Sample Gateway.
  2. Create a custom recipient with an address type similar to the gateway.
  3. Type START RPTDRIV NOTSERV <gateway-name>.
  4. Log on to a mailbox profile using the Microsoft Exchange Client.
  5. Submit a message to the custom recipient with one of the subject lines in the following table. RPTDRIV reads the subject line of the message and returns the corresponding report to the originator. The subject must exactly match one of the choices for the report to be generated.
Subject line | Corresponding report type
NDR | Nondelivery report
DR | Delivery report
NRN | Nonreceipt notification
RN | Receipt notification


XLATDRIV: Translating Messages

The XLATDRIV sample application enables you to:

  • Set up a conversion in the gateway to translate messages.
  • Send messages to the gateway.
  • Open a text file to check that the messages you sent were translated correctly.

Before you run XLATDRIV, you must install the sample gateway as described in Installing the Sample_Gateway.

Source code for IPM_IN and IPM_OUT is in the corresponding directories under \BKOFFICE\SAMPLES\EXCHANGE. Source code for the remaining conversions is in the \BKOFFICE\SAMPLES\EXCHANGE\XLATCONV directory. You can choose a conversion from those described in the following table:

Conversion DLL | Description
IPM_IN.DLL | Translates a message from RFC 822 format to MAPI format.
IPM_OUT.DLL | Translates a message from MAPI format to RFC 822 format.
TNEFDEC.DLL | Decodes a TNEF copy of the message as an embedded message.
TNEFENC.DLL | Adds an attachment containing an encoding of the entire content of the original message in TNEF format.
TOUPPER.DLL | Adds an attachment containing the message text converted to uppercase.
TRIVIAL.DLL | Adds an attachment with no changes.

Note Do not run multiple instances of XLATDRIV against the same gateway profile.

To run XLATDRIV, you must have a conversion point of SAMPLEGW.OUTBOUND for outbound conversion DLLs, and a conversion point of SAMPLEGW.INBOUND for inbound conversion DLLs.

To build XLATDRIV
  1. Change to the directory containing the RPTDRIV source files:

    \BKOFFICE\SAMPLES\EXCHANGE\XLATDRIV directory.

  2. Type NMAKE.
To run XLATDRIV
  1. From the \BKOFFICE\BIN directory, copy the following into a directory that is on your path:

    IPM_IN.DLL

    IPM_OUT.DLL

    TNEFDEC.DLL

    TNEFENC.DLL

    TOUPPER.DLL

    TRIVIAL.DLL

    Windows NT Server searches the directories listed in the path environment variable when attempting to locate a DLL, and searches directories in the path before it searches the current directory.

  2. Run XLATINST to install the conversion DLLs you need. The parameter values for XLATINST are shown in the following table.
Conversion DLL | Values
IPM_IN.DLL | Classes : REG_MULTI_SZ : ENVELOPE.IPM REPORT.IPM
 | Options : REG_SZ
 | Conversion Point : REG_SZ : SAMPLEGW.INBOUND
IPM_OUT.DLL | Classes : REG_MULTI_SZ : ENVELOPE.IPM REPORT.IPM
 | Options : REG_SZ:
 | Conversion Point : REG_SZ : SAMPLEGW.OUTBOUND
TNEFDEC.DLL | Classes : REG_MULTI_SZ : ENVELOPE.IPM
 | Options : REG_SZ :
 | Conversion Point : REG_SZ : SAMPLEGW.INBOUND
TNEFENC.DLL | Classes : REG_MULTI_SZ : ENVELOPE.IPM
 | Options : REG_SZ :
 | Conversion Point : REG_SZ : SAMPLEGW.OUTBOUND
TOUPPER.DLL | Classes : REG_MULTI_SZ : ENVELOPE.IPM
 | Options : REG_SZ :
 | Conversion Point : REG_SZ : SAMPLEGW.OUTBOUND
TRIVIAL.DLL | Classes : REG_MULTI_SZ : ENVELOPE.IPM
 | Options : REG_SZ :
 | Conversion Point : REG_SZ : SAMPLEGW.OUTBOUND

  3. Start the Microsoft Exchange Client. Sign on as a user and compose and send mail messages to one or two recipients on the gateway. These are the messages that XLATDRIV will translate.
  4. To start XLATDRIV, change to the \BKOFFICE\BIN directory. At the command prompt, type XLATDRIV NOTSERV <gateway> where gateway is the name of the gateway's MAPI profile. To see all the options supported by XLATDRIV, type XLATDRIV NOTSERV <gateway> /?".

    XLATDRIV supports the following three options:

    /DIRECTION
    For /DIRECTION = INBOUND, XLATDRIV reads text files that were created with the Outbound conversion from the current directory and translates them into MAPI messages in the gateway's MTS-IN directory.

    For /DIRECTION = OUTBOUND, XLATDRIV reads messages from the gateway's MTS-OUT folder and converts them into XLT*.TMP text files in either the current directory or the directory specified by the /LOCATION option.

    The default for /DIRECTION is OUTBOUND.

    TNEFDEC.DLL only works with the /DIRECTION = INBOUND option. All other conversion DLLs in XLATCONV only work with the /DIRECTION = OUTBOUND option.

    /LOCATION
    Specifies the directory into which to write or read the text files. If it is not provided, the current directory is used.
    /ENCODE
    Enables TNEF encoding and decoding of messages. This option only works on outbound processing. The default is no TNEF encoding and decoding.
  5. Start the Microsoft Exchange Client again. Sign on as gateway. Access the directory where XLATDRIV placed the translated messages. Open the messages and check the translation. The message translation program uses the first conversion it encounters in the Windows NT Registry.
  6. To disable or enable a conversion you have loaded, run the Regedt32 program in the WINNT35\SYSTEM32 directory. In the HKEY_LOCAL_MACHINE\Software\Classes key, in the conversion subkeys:
    • To enable a conversion, in its conversion subkey, for the Point value, type SAMPLEGW.OUTBOUND for outbound conversion DLLs or SAMPLEGW.INBOUND for inbound conversion DLLs.
    • To disable a conversion, in its conversion subkey, for its Point value, type zSAMPLEGW.OUTBOUND for outbound conversion DLLs or zSAMPLEGW.INBOUND for inbound conversion DLLs.
  7. To use a new conversion, start the Microsoft Exchange Client as a user, send more mail to the gateway, and type:

    XLATDRIV NOTSERV <gateway> /DIRECTION=OUTBOUND

    You can also add more XLT*.TMP files to your current directory and type:

    XLATDRIV NOTSERV <gateway> /DIRECTION=INBOUND

    See Sample Gateway Message Format for the format of the XLT*.TMP text files.

IPM_OUT.DLL writes the first line of a textized message as X-Tnef-Attach:<TNEF data filename, if any>. Therefore, files with TNEF attachments have the first line "X-Tnef-Attach:MAPIMAIL.DAT", and files without TNEF attachments have the first line "X-Tnef-Attach:".

This way, IPM_IN.DLL can easily determine if an input file has TNEF data by examining the first line of the file.


Installation Programs

The programs described in the following topics install individual gateway components. All these programs are located in the \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU directory.

To build the installation programs
  1. Change to the \BKOFFICE\SAMPLES\EXCHANGE\EDKINSTU directory.
  2. Type NMAKE.

These programs do not copy files. Instead, they take care of creating various objects in Microsoft Exchange Server. Therefore, when you run them, you must do the following:

  • Ensure that all the files you need are located in the appropriate directories.
  • Include the full path when entering parameters that use file names.
  • Ensure that the directory access function DLL (DAPI.DLL) is located on your path.

In all the installation programs, you must leave a space between the parameters, as shown in the syntax examples.


ADDRINST: Installing an Addr-Type Object

This program installs an Addr-Type object and a proxy generation DLL associated with the object in the Microsoft Exchange Server directory. For more information, see The Addr-Type Object.

To run ADDRINST, type the following at the command prompt:

ADDRINST /SITEDN=<site distinguished name>
/NAME=<display name> /MACHINE=<computer type>
/TYPE=<address type> /PROXYDLL=<proxy generation DLL>
/SERVER=<server computer name>
/GWPROXY=<gateway site proxy address>
[/DELETE] [/HELP or /?]

ADDRINST Parameters

Parameter | Description
SITEDN | Site distinguished name for this address type.
NAME | Display name for the address type.
MACHINE | Type of computer on which the proxy generation DLL is installed.
TYPE | Address type.
PROXYDLL | Full path to proxy generation DLL for this address type.
SERVER | Server computer name.
GWPROXY | Site proxy address for the gateway.
DELETE | Deletes the address type. (This operation does not delete the proxy generation DLL associated with the address type. You must delete the DLL manually.)
HELP or ? | Displays Help information.

An example of calling ADDRINST is:

ADDRINST /SITEDN=/o=Microsoft/ou=APPS-WGA
/NAME=EDK /MACHINE=i386 /TYPE=EDK
/PROXYDLL=\\myserver\address\EDK\i386\proxygen.dll
/SERVER=server1 /GWPROXY=EDK:%m@.microsoft.com


EXTNINST: Installing an Administrator Extension

This program installs an Administrator extension DLL for a gateway. For more information about installing extension DLLs, see Installing the Administrator Extension DLL. For general information about Administrator extensions, see Administrator Program Extensions.

To run EXTNINST, type the following at the command prompt:

EXTNINST /SITEDN=<distinguished name>
/DISPLAY_NAME=<display name> /MACHINE=<machine name>
/NAME=<admin extension name> /SERVER=<server computer>
/EXTDLL=<DLL name>[ /DELETE] [/HELP or /?]

EXTNINST Parameters

Parameter | Description
SITEDN | Site distinguished name for the Administrator extension.
DISPLAY_NAME | Display name for the Administrator extension.
MACHINE | Type of computer on which the extension DLL is installed.
NAME | Administrator extension name.
EXTDLL | Full path to Administrator extension DLL.
SERVER | Server computer name.
DELETE | Deletes the Administrator extension.
HELP or ? | Displays Help information.

An example of calling this program is:

EXTNINST /SITEDN=/o=Microsoft/ou=Redmond
/DISPLAY_NAME="EDK Queue Viewer Extension for I386" /MACHINE=i386 /NAME=QUEVIEW
/EXTDLL=\\myserver\add-ins\queview\i386\queview.dll
/SERVER=myserver


GWINST: Installing a Mail-Gateway Object

This program installs the Mail-Gateway object in the Microsoft Exchange Server directory. To run GWINST, type the following at the command prompt:

GWINST /SITEDN=<site distinguished name>
/DISPLAY_NAME=<gateway display name>
/NAME=<gateway name> /ADDRTYPE=<address type>
/SERVER=<server computer name>
[/EXTNAME=<extension name>]
[/EXTDATA=<extension data>]
[/ACCOUNT=<account name>]
[/PRESERVE_DNS=<preserve>]
[/DELETE] [/HELP or /?]

GWINST Parameters

Parameter | Description
SITEDN | Gateway site distinguished name.
DISPLAY_NAME | Gateway display name. This name will be displayed in the directory.
NAME | Gateway name.
ADDRTYPE | Address type.
SERVER | Server computer name.
EXTNAME | Administrator extension name.
EXTDATA | Absolute path and file name for the extension data. (Use CFGCODE to create this file.)
ACCOUNT | Account name.
PRESERVE_DNS | Indicates whether this gateway can preserve distinguished names. (Valid values are YES and NO.)
DELETE | Deletes the gateway.
HELP or ? | Displays Help information.

An example of calling this program is:

GWINST /SITEDN=/o=Microsoft/ou=APPS-WGA
/DISPLAY_NAME=samplgw /NAME=gw1
/ADDRTYPE=edk /SERVER=server1
/EXTNAME=sgwadmin /EXTDATA=c:\bin\sgwadmin.dat


PERFINST: Installing Performance Monitoring

This program installs the counters for gateway performance monitoring. To run PERFINST, type the following at the command prompt:

PERFINST /SERVICE=<service name> /CLASS=<service class>
/DLL=<performance DLL name> /OPEN=<openentry>
/COLLECT=<collectentry> /CLOSE=<closeentry>
[/DELETE] [/HELP or /?]

PERFINST Parameters

Parameter | Description
SERVICE | Name of the gateway service.
CLASS | Class of the gateway service.
DLL | Full path to the performance monitoring DLL.
OPEN | OPEN function entry point to DLL.
COLLECT | COLLECT function entry point to DLL.
CLOSE | CLOSE function entry point to DLL.
DELETE | Deletes performance monitoring.
HELP or ? | Displays Help information.

An example of calling this program is:

PERFINST /SERVICE=samplegw /CLASS=perftesttype
/DLL=\\myserver\address\EDK\i386\perfmon.dll
/OPEN=OpenGatewayPerformanceData
/COLLECT=CollectGatewayPerformanceData
/CLOSE=CloseGatewayPerformanceData


PROFINST: Installing a MAPI Profile

This program installs a MAPI profile for a gateway. The gateway can use the profile to log on to MAPI.

To run PROFINST, type the following at the command prompt:

PROFINST /SERVICE=<service name> /NAME=<profile name>
/TYPE=<profile type> [/DELETE] [/HELP or /?]

PROFINST Parameters

Parameter | Description
SERVICE | Service name for the gateway. This is the name that was assigned when the gateway was installed.
NAME | Profile name.
TYPE | Profile type (for a gateway, this is GATEWAY).
DELETE | Deletes the profile.
HELP or ? | Displays Help information.

An example of calling this program is:

PROFINST /SERVICE=samplegw /NAME=gw1 /TYPE=GATEWAY


SERVINST: Installing a Service

This program installs a gateway as a service of Windows NT Server. To run SERVINST, type the following at the command prompt:

SERVINST /SITEDN=<site distinguished name>
/OBJNAME=<object name> /OBJTYPE=<object type>
/SERVICE=<service name> /DISPLAY_NAME=<service display name>
/DEPENDENCIES=<service dependencies>
/EXE=<executable name> /SERVER=<server computer name>
/ACCOUNT=<account name> /PASSWORD=<account password>
[/DELETE] [/HELP or /?]

SERVINST Parameters

Parameter | Description
SITEDN | Site distinguished name for the gateway.
OBJNAME | Object name for the gateway. This can be the same as the display name.
OBJTYPE | Object type (for a gateway, this is GATEWAY).
SERVICE | Name to be assigned to the gateway. This becomes the final entry in the service key for the gateway object. This name can be the same as the display name.
DISPLAY_NAME | Display name of the installed gateway. This name is used in the service registry to refer to the gateway object.
DEPENDENCIES | Services that should be started before this gateway (separated by %).
EXE | File name and path for the gateway executable file.
SERVER | Server on which to install the gateway.
ACCOUNT | Account name for accessing the gateway. This must include the domain name.
PASSWORD | Password for accessing the gateway.
DELETE | Deletes the gateway service.
HELP or ? | Displays Help information.

An example of calling this program is:

SERVINST /SITEDN=/o=Microsoft/ou=APPS-WGA
/OBJNAME=gw1 /OBJTYPE=GATEWAY
/SERVICE=gw1 /DISPLAY_NAME=samplgw
/DEPENDENCIES=msexchangesa%msexchangeds
/EXE=\\myserver\myshare\samplegw\samplegw.exe
/SERVER=server1 /ACCOUNT=mydomain\myaccount
/PASSWORD=mypassword


TMPLINST: Installing an Address Entry Template

This program installs the templates associated with an address type. You can use it to install templates for entering address types, per-message options, and per-recipient options.

To run TMPLINST, type the following at the command prompt:

TMPLINST /SITEDN=<site distinguished name>
/DISPLAY_NAME=<template display name> /NAME=<template name>
/TYPE=<address type> /SYNTAX=<address syntax>
/SERVER=<server computer name>
/MESSAGE_DT=<per-message display table>
/RECIPIENT_DT=<per-recipient display table>
/ADDRESS_DT=<address entry display table>
/LANGUAGE=<language code>
/DATA16=<16-bit help file> /DATA32=<32-bit help file>
/FILE=<help file name> [/DELETE] [/HELP or /?]

TMPLINST Parameters

Parameter | Description
SITEDN | Site distinguished name.
DISPLAY_NAME | Template display name.
NAME | Name of address type.
TYPE | Type of address.
SYNTAX | Name and location of file containing the syntax for the address entry template.
SERVER | Server on which to install these templates.
MESSAGE_DT | Name and location of the per-message display table.
RECIPIENT_DT | Name and location of the per-recipient display table.
ADDRESS_DT | Name and location of the address entry display table.
LANGUAGE | Code for the language in which to install the templates (for example, 409 is English).
DATA16 | Name of file containing the 16-bit Help information.
DATA32 | Name of file containing the 32-bit Help information.
FILE | Help file name used by clients (for example, SMTP.HLP).
DELETE | Deletes the template.
HELP or ? | Displays Help information.

An example of calling this program is:

TMPLINST /SITEDN=/o=Microsoft/ou=APPS-WGA /DISPLAY_NAME=sdktmpl /NAME=sdk
/TYPE=sdk /SYNTAX=c:\temp\sdkadt.oel /SERVER=server1
/MESSAGE_DT=c:\temp\sdkpmt.blt /RECIPIENT_DT=c:\temp\sdkprt.blt
/ADDRESS_DT=c:\temp\sdkadt.blt /LANGUAGE=409
/DATA16=smtp16.hlp /DATA32=smtp32.hlp /FILE=smtp.hlp


XLATINST: Installing a Message Conversion

This program installs a message conversion DLL for a gateway. To run XLATINST, type the following at the command prompt:

XLATINST /DLL=<conversion DLL name>
/CLASSES=<message classes>
/OPTIONS=<options string> /POINT=<point string>
[/DELETE] [/HELP or /?]

XLATINST Parameters

Parameter | Description
DLL | Message conversion DLL name (no path name).
CLASSES | Message classes, separated by %.
OPTIONS | Options string.
POINT | Point string.
DELETE | Deletes the conversion DLL.
HELP or ? | Displays Help information.

An example of calling this program is:

XLATINST /DLL=MESGCNV.DLL /CLASSES=SDK%SMTP
/OPTIONS=options string /POINT=point string


Sample Gateway Message Format

This appendix describes the format of messages in the Microsoft Exchange Server SDK sample gateway. These messages are based on RFC 822. The message format is as follows:

Message Component | Format
Message | Envelope Content
Envelope | TnefAttachName EnvOriginator EnvRecipients EnvDataLine
TnefAttachName | “X-Tnef-Attach:” <EOL> | “X-Tnef-Attach:” MAPIMAIL.DAT <EOL>
EnvOriginator | “MAIL FROM:” Address <EOL>
EnvRecipients | EnvRecip | EnvRecip EnvRecipients
EnvRecip | “RCPT TO:” Address <EOL>
EnvDataLine | “DATA:” <EOL>
Content | IPMContent | ReportContent
IPMContent | ClassIPM IPMHeader IPMBody TNEFAttach | ClassIPM IPMHeader IPMBody
ReportContent | ClassReport ReportHeader ReportBody TNEFAttach | ClassReport Report Header ReportBody
ClassIPM | “X-Message-Class:IPM.” SubClass<EOL>
ClassReport | “X-Message-Class:Report.” SubClass<EOL>
IPMHeader | IPMDate IPMSource IPMDestinations IPMHumanDetails
IPMDate | “Date:” DateTime <EOL>
DateTime | Day, <SP> Date <SP> Month <SP> Year <SP> Hours “:” Minutes “:” Seconds “UT”
IPMSource | IPMID [IPMSubjectID] IPMTrace IPMFrom
IPMID | “X-Message-ID:” MessageIdString <EOL>
IPMSubjectID | “X-Subject-Message-ID:” MessageIdString <EOL>
IPMTraceEntries | IPMTraceEntry | IPMTraceEntry IPMTraceEntries
IPMFrom | “From:” Address <EOL>
IPMTraceEntry | X400RcvdBy X400RcvdAt X400AttBy X400DefdAt
X400RcvdBy | “X400-Received-By:” StringRepOfTraceInfo<EOL>
X400RcvdAt | “X400-Received-At:” DateTime<EOL>
X400AttBy | “X400-Attempted-By:” StringRepOfTraceInfo<EOL>
X400DefdAt | “X400-Deferred-At:” DateTime<EOL>
StringRepOfTraceInfo | “/P=“ Prmd “/A=“ Admd “/C=“ Country “/” “;” Action
Action | “Redirected” | “Expanded” | “Relayed” | “Rerouted”
IPMDestinations | IPMDestination | IPMDestination IPMDestinations BlankLine
IPMDestination | IPMDestinationPrefix Address <EOL>
IPMDestinationPrefix | “TO:” | “CC:” | “BCC:”
BlankLine | <EOL>
<EOL> | “\r\n”
IPMHumanDetails | IPMHumanDetails
ImportanceVal | “High” | “Normal” | “Low”
PriorityVal | “Normal” | “Non-Urgent” | “Urgent”
IPMBody | BodyText BodyText AttachmentText
BodyText | BodyHeader BodyLines BodyFooter
BodyHeader | “----beginbody:” LengthOfTextInBytes(decimal represented as ASCII)
BodyLines | BodyLine BodyLines | BodyLine
BodyFooter | <EOL>“----endbody”<EOL>
BodyLine | RegularLineOfText
AttachmentText | <NULL> |
AttachmentHeader | “----beginattach:” AttachId “:” AttachLength <EOL>
AttachId | BaseFileName
AttachmentTail | <EOL>“----endattach”<EOL>
BaseFileName | The name of the file in 8.3 format.
AttachmentLength | The length of the file in bytes (decimal number represented as ASCII digits)
ReportHeader | IPMDate IPMSource IPMDesination IPMHumanDetails
ReportBody | NDRBodies | DRBodies | NRNBody | RNBody
NDRBodies | NDRBody NDRBodies | NDRBody
NDRBody | NDRNonDeliverLine NDRTextLine NDRDiagLine NDRCodeLine
NDRNonDeliverLine | “Your message was not delivered to:” Address<EOL>
NDRTextLine | “for the following reason:” ReportText<EOL>
NDRDiagLine | “Diagnostic code:” DiagnosticCode<EOL>
NDRCodeLine | “NDR code:” ReasonCode<EOL>
DRBodies | DRBody DRBodies | DRBody
DRBody | DRDeliverLine AtTimeLine
DRDeliverLine | “Your message was successfully delivered to:” Address<EOL>
AtTimeLine | “at:” DateTime<EOL>
NRNBody | NRNNotReadLine AtTimeLine NRNDiscardLine NRNCodeLine
NRNNotReadLine: | “Your message was not read by:” Address<EOL>
NRNDiscardLine | “Discard code:” DiscardCode<EOL>
NRNCodeLine | “Non-reciept code:” NonReceiptCode<EOL>
RNBody | RNReadByLine AtTimeLine
RNReadByLine | “Your message was read by:” Address<EOL>
TNEFAttach | TNEFHeader TNEFData
TNEFHeader | “MAPIMAIL.DAT:”<EOL>
TNEFData | binary TNEF data

Line Formatting Rules

The tag and data portion of a line (tag:data) is printed on one line, regardless of length. A line is terminated with the carriage return/new line sequence (\r\n).

The message text data, binary attachment data, and TNEF data are handled individually. The message text is printed out exactly as it was formatted in the original message. No line breaks are added.

The binary attachment data is encoded. Each byte in the original attachment is converted to a two-character hexadecimal representation of that byte. (For example, 256 becomes FF.) Each two-character hexadecimal representation is separated from the next one by an ASCII space. A total of 24 hexadecimal byte pairs are printed per line.

The TNEF data is printed out directly by the TNEF encoding function. No formatting is done on the data printed out by TNEF.


Gateway Event Logging

The following events should be logged by all Microsoft Exchange Server gateways. An individual gateway may log additional events.

Category | ID | Type | Event | Description
1 | 1100 | Informational | Gateway starting. | Gateway starting.
1 | 1101 | Informational | Gateway started. | Gateway started.
1 | 1102 | Informational | Gateway stopping. | Gateway stopping.
1 | 1103 | Informational | Gateway stopped. | Gateway stopped.
2 | 1200 | Error | MAPI logon failed. | MAPI logon failed: Error (%1).
2 | 1201 | Error | Unexpected error from MAPI. | MAPI Error (%1).
4 | 1400 | Error | Unable to access registry. | Error accessing registry: Error (%1).
4 | 1401 | Error | Unable to access configuration information. | Error accessing configuration information: Error (%1).
4 | 1402 | Error | Unable to open audit log. | Unable to open audit log: Error (%1).
4 | 1403 | Error | Unable to write audit log. | Unable to write audit log: Error (%1).
4 | 1404 | Error | Unable to initialize gateway. | Unable to initialize gateway.
5 | 1500 | Error | Memory allocation error. | Thread (%1): Memory allocation error.
5 | 1501 | Error | Unable to create thread. | Thread create failed.
5 | 1502 | Error | Unknown system error. | Unknown system error (%1).
6 | 1600 | Warning | Address mapping failed. | Address mapping failed. Message (%1) may be non-delivered for recipient (%2).
6 | 1601 | Warning | Message translation failed. | Message translation failed. Message (%1) may be non-delivered.
6 | 1602 | Warning | Unexpected message class received. | Unexpected message class received: Class (%1), ID (%2).
6 | 1602 | Warning | Message nondelivered. | Message (%1) nondelivered for recipient (%2).
7 | 1700 | Warning | Failed connection attempt to foreign system. | Failed connection attempt to foreign system (%1).
7 | 1701 | Error | Communications error. | Communications error (%1).
7 | 1702 | Warning | Connection attempt from unknown foreign system. | Connection attempt from unknown foreign system.


A

Abstract Syntax Notation (ASN)
An ISO standard for encoding of human-readable symbols, such as header tags, into condensed binary form. ASN.1 corresponds to CCITT standards X.208 (for the notation) and X.209 (for the encoding rules). In turn, it forms part of the specifications for the X.400 and X.500 series of standards, as well as for various other specifications.
address book
A subset of the directory that includes mailboxes, custom recipients, distribution lists (DLs), and public folders. Users can access information about the organization from the address book just as they would from a printed directory. The address book can contain one or more address lists. See also global address list, personal address book.
address entry template
A component of an Addr-Type object. The address entry template consists of the controls for a dialog box that administrators can use to enter custom addresses. It provides a friendly interface for creating custom recipients for a foreign system. It is represented by the Address-Template directory object.
address space
The address information that identifies the type of messages handled by a connector or gateway. Address spaces are typically subsets of complete addresses; they contain only the elements needed to identify the route that a message should take.
Addr-Type object
An object associated with a gateway that is used to convert the address format of the foreign system to its representation in the Microsoft Exchange Server system. Components of the Addr-Type object are the proxy generation DLL, the address entry template, per-message and per-recipient options, and online Help.
Administration Management Domain (ADMD)
An X.400 term describing a message transfer system. ADMDs are usually large public carriers such as AT&T and MCI.
Administrator extension DLL
See extension DLL.
Administrator program
A graphical user interface that enables system administrators to manage and configure all Microsoft Exchange Server objects, including organizations, sites, and computers.
alias
A name or label used as an alternative way to address e-mail to a user’s mailbox. An alias is typically a shortened version of the mailbox owner’s name. For example, “jrdoe” might be the alias for John R. Doe.
ASN
See Abstract Syntax Notation.
attachment
A MAPI object that contains additional data, such as a file or OLE object, associated with a message.
attribute
A piece of data that stores information that is specific to an object. A set of attributes store the data that define an object. An attribute of a MAPI object is called a property.


B

backboning (backbone)
The process used to transmit messages between two Microsoft Exchange Server systems through a foreign system. The foreign system is called the backbone. Backboning can also provide connections between different Microsoft Exchange Server organizations.


C

class
See message class.
connector
A software service that allows users at one Microsoft Exchange Server site to connect to users at other Microsoft Exchange Server sites using specific protocols such as X.400, SMTP, and Microsoft Mail. Microsoft Exchange Server includes an Internet connector, a site connector for linking two Microsoft Exchange Server sites, and a RAS connector. A connector can perform all the functions of a gateway. See also backboning (backbone).
conversion
A program that translates a message from one messaging system format to another.
conversion engine
A set of functions that convert messages between multiple messaging systems.
custom recipient
An address book entry representing a recipient from another messaging system. A client application user can create a custom recipient with a template supplied by the address book provider.


D

delivery report
A report sent to the originator of a message when the message is successfully delivered to one of its intended recipients.
directory
The central repository of user and Microsoft Exchange Server system information for an organization.
directory access functions
A set of functions included with the Microsoft Exchange Server SDK that are used to manage information in the directory. Directory access functions are typically used for managing objects when creating and maintaining custom add-on services, managing a large number of directory objects at one time, synchronizing Microsoft Exchange Server directory objects with other directory services, and automatically updating Windows NT Server user accounts as directory objects are updated.
distinguished name (DN)
A unique name that identifies an object. In Microsoft Exchange Server, the combination of an object’s name and the path leading to the object.
distribution list (DL)
A MAPI address book object that represents a set of individual recipients addressed together as a group, which implements the MAPI IDistList interface. Distribution lists can contain other distribution lists and individual recipients. A distribution list is one type of a MAPI address book objects that can receive messages; the other type is a mail user object.


E

embedded object
An object that is included in a second object. An object embedded in a Microsoft Exchange Server message and represented as an icon is called an attachment.
event logging
The recording to a file of any significant occurrences in the system or in an application.
EX
Address type for native Microsoft Exchange Server addresses.
extension data
Data with fields other than the standard configuration data provided by the Microsoft Exchange Server Administrator program, stored by a directory object. One extension data attribute can contain a number of extension data fields of varying data types. Extension data is commonly used when an application must expose information that is outside the application’s schema.
extension DLL
A DLL that controls the property sheets that display extension data. Also called Administrator extension DLL.


F

folder
A MAPI object in a message store that is accessible for sharing. Folders can contain objects such as messages, files, and other folders.
foreign address
The address of an object in a foreign system.
foreign system
A mail system that is not a Microsoft Exchange Server system.


G

gateway
A software service that allows Microsoft Exchange Server users to communicate with other mail systems, such as IBM PROFS. Gateways can be used to send messages between two Microsoft Exchange Server sites through an intermediate mail system through a process called backboning (backbone), but do not support directory replication.
gateway address routing table (GWART)
A table that contains information about the gateways available to Microsoft Exchange Server and the address types associated with each one. When a message needs to be routed through a gateway, the GWART is used to determine the appropriate gateway to use for each address type.
global address list
A list of names of all possible recipients in a Microsoft Exchange Server organization.


I

information store
The server-based message store where received messages are maintained for and organized by mail system users. The information store is the interface between mail clients and the message transfer system.
interpersonal message (IPM)
An electronic memo.
interpersonal note (IPN)
A high-level acknowledgment of the receipt of an interpersonal message by one of its intended recipients.


M

mailbox
The delivery location for all incoming mail messages addressed to a designated owner. Information in a user’s mailbox is stored in the private information store on a Microsoft Exchange Server computer. A mailbox can contain received messages, message attachments, folders, and more.
MAPI
The Messaging Application Programming Interface (MAPI) is a medium-independent messaging architecture that enables multiple applications to interact with multiple systems across a variety of hardware platforms. As a client interface component, MAPI is the complete set of functions and object-oriented interfaces that forms the foundation for the MAPI subsystem’s client application and service provider interfaces.
message
In electronic mail, an object representing information being passed from the originator to the recipient(s). It can be a note composed by a user, computer-generated mail, or a diagnostic generated by the mail system. It usually has a textual body and can have file attachments and/or embedded OLE objects.
message class
The MAPI property (PR_MESSAGE_CLASS) that provides information about a message’s characteristics.
message transfer agent (MTA)
The mechanism that provides the addressing and routing information for sending messages and distributing information through the system. Each MTA is associated with an information store. The Microsoft Exchange Server MTA conforms to the 1988 X.400 specification.
message transfer envelope (MTE)
A MAPI message that holds the delivery information for a message. An MTE contains another MAPI message that represents the contents of a message. MTEs are only created in gateway folders. In contrast, regular user folders contain the message contents only.
MTS-IN
Gateway message folder in the message database to hold messages to be submitted to Microsoft Exchange Server by the gateway. It is created as the gateway is installed.
MTS-OUT
A gateway message folder in the message database that holds messages coming into the gateway from Microsoft Exchange Server. It is created as the gateway is installed.


N

name space
A hierarchy of values that makes up an X.400 Originator/Recipient Name used for a Microsoft Exchange Server message address. This hierarchy contains address information including country, organization, common name, and personal name.
nondelivery report
A report sent to the originator of a message to indicate that the message could not be delivered to one or more of its intended recipients.


O

object
A set of information that consists of properties and functions used to manipulate the properties, collected into an interface (usually a DLL). Windows objects can be linked to or embedded into a document. They are created by using a Windows-based application with OLE capabilities.
one-off address
An address of any type that does not appear in a Microsoft Exchange Server address book. One-off addresses are either constructed once and not saved, or are saved in a user’s personal address book, inaccessible to Microsoft Exchange Server.
organization
A collection of servers, grouped into sites, that are linked together to provide workgroup connectivity, information, and messaging services. The organization is the largest administrative unit in a Microsoft Exchange Server system. It encompasses all the Microsoft Exchange Server computers in a company’s messaging infrastructure.


P

personal address book
A list of recipients created and maintained by an individual user for personal use. The personal address book is a subset of the global address list.
primary proxy address
The proxy address used when sending mail to a foreign system. A user can have only one primary proxy address. See also secondary proxy address.
Private Management Domain (PRMD)
An X.400 term describing a message transfer system. PRMDs are usually smaller than ADMDs, often existing at the organization level. When Microsoft Exchange Server creates X.400 addresses, the default is to assign PRMD the name of the Microsoft Exchange Server organization.
property
An attribute common to all instances of a MAPI object type. Examples of message object properties are message text and list of recipients. MAPI properties are included as part of the message objects or other objects they describe, and they derive from the IMAPIProp interface. Each property is a structure that consists of identifier, data type, and value.
property page
A dialog box that displays configuration information to the user and enables the user to modify the information. One or more property pages makes up a property sheet.
property sheet
A dialog box that displays configuration information to the user and enables the user to modify the information. A property sheet is composed of one or more property pages.
proxy address
A user’s Microsoft Exchange Server address translated to a foreign system address type. For example, the Microsoft Exchange Server address “EX:/o=microsoft/ou=sales/cn=PatParkes” can have the SMTP proxy address “SMTP:PatParkes@Microsoft.com” and the MS Mail proxy address “MS:Microsoft/Sales/PatParkes.” In the Microsoft Exchange Server Administrator program, a proxy address is called an e-mail address.


R

recipient
An object in the directory that can receive messages and information. Microsoft Exchange Server recipients are mailboxes, distribution lists (DLs), public folders, and custom recipients.
recipient table
A MAPI object that provides access to information about a message’s recipient list. Each row in the table contains information about one recipient.
remote procedure call (RPC)
A message-passing facility that is independent of the underlying network and allows a distributed application to call services available on various computers in a network. Microsoft Exchange Server uses RPC for client-server communications.


S

secondary proxy address
A proxy address used when receiving mail from the foreign system. A user can have more than one secondary proxy address. See also primary proxy address.
service control manager
A Windows NT Server process that manages all the services in the Windows NT Registry.
setup program
A utility program whose main function is to copy all necessary files from floppy disks or CD to the server’s hard disk. The setup program must also ensure that the components are recognized by each other and can communicate with each other.
Simple Mail Transfer Protocol (SMTP)
The message standard used by the Internet to transfer mail.
site
One or more Microsoft Exchange Server computers that provide services to a set of users. Sites can be centrally managed and can span physical locations.
site proxy address
The portion of a proxy address that corresponds to the site rather than to the individual user. For example, @trager.com might be the site proxy address for the Trager company.


T

target address
The foreign e-mail address associated with a custom recipient.
Transport Neutral Encoding Format (TNEF)
A standard method defined by MAPI for passing textual and binary message data. The method involves wrapping unsupported MAPI properties in a binary attachment file that accompanies a message through the transport and decoding the file on the receiving side to reconstitute the MAPI properties.


U

Unicode
A worldwide character-encoding standard that allows more information to be contained in each string by defining 16-byte character strings rather than the standard 8-byte character strings. Unicode allows universal data exchange and improves multilingual text processing. Unicode strings are also called wide strings.
Universal Naming Convention (UNC)
A standard naming convention for applications that enables users to browse documents on the network directly and to open an application’s files on remote machines without requiring the user to specify the location of the file on the network or connect to that network. Universal names are location-independent. They also allow users to transfer files to other computers.


W

Windows Messaging System (WMS)
The Windows subsystem consisting of MAPI and service provider DLLs that gives client applications access to messaging systems such as Microsoft Exchange Server.
Windows NT Registry
The control mechanism for services of Windows NT Server. Each service is registered and from that time it is controlled by the Windows NT service control manager.


X

X.400
An international message-handling standard for connecting e-mail networks and for connecting users to e-mail networks. X.400 is published by the X.400 Application Programming Interface Association (XAPIA). MAPI applications are fully interoperable with X.400 messaging applications.
X.500
An international message-handling standard for directory services, published by the International Telegraph and Telephone Consultative Committee (CCITT) standards body.


Legal Information

Microsoft Schedule+ Programmer's Reference

Information in this document is subject to change without notice. This document is provided for informational purposes only and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Microsoft.

© 1996-1998 Microsoft Corporation. All rights reserved.

Microsoft, Microsoft Press, MS, Visual Basic, Visual C++, Visual FoxPro, Windows, Windows NT, and Win32 are registered trademarks of Microsoft Corporation.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Using the Microsoft Schedule+ Programmer's Reference

Using the Microsoft Schedule+ Programmer’s Reference

The Microsoft Schedule+ Programmer’s Reference is designed for use with Microsoft® Schedule+ Automation (formerly OLE Automation). Automation is a feature of the Component Object Model (COM), an industry standard used by applications to expose objects to development tools and other applications. The Schedule+ Automation interface exposes objects that enable applications, such as those developed with Microsoft® Visual Basic® and Microsoft® Visual C++®, to manipulate Schedule+ information. This information includes appointments, contacts, tasks, projects, events, alarms, and other Automation controllers.

Using these tools, you can customize menus and write stand-alone applications that extend Schedule+ capabilities.

This reference should be used in conjunction with the following documents:

  • Microsoft Visual Basic Programming System for Windows Programmer’s Guide
  • Microsoft Active Messaging Library Programmer’s Reference
  • MAPI Programmer’s Reference in the Microsoft® Win32® Software Development Kit (SDK)


Intended Audience

To use the Schedule+ Automation interface, your background should include:

  • Familiarity with basic features and capabilities of Schedule+.
  • Proficiency with Visual Basic programming in the Windows® environment. Reviewing the Microsoft Win32 SDK and Microsoft Visual Basic Programming System for Windows documentation is recommended.
  • Proficiency with the Active Messaging Library. Reviewing the Microsoft Active Messaging Library Programmer’s Reference is recommended.
  • Familiarity with Message Application Programming Interface (MAPI). Reviewing the MAPI Programmer’s Reference is recommended.
  • Expertise with network environments.


Organization

This reference is organized into the following sections:

  • Overview introduces the basic concepts of Microsoft Schedule+ and examines how to extend its functionality and customize its menus. It also describes the Schedule+ Automation interface, the objects it exposes, and the types of operations that can be performed using those objects.
  • Programming Tasks contains a selection of sample programming tasks. Source code samples are provided.
  • Objects provides a reference for Schedule+ Automation objects and their corresponding properties, data members, and methods in table format.
  • Properties contains an alphabetic listing of Schedule+ Automation properties, their data types, and the objects to which they apply.
  • Data Members contains an alphabetic listing of Schedule+ Automation data members, their data types, and the objects to which they apply.
  • Methods contains an alphabetic listing of Schedule+ Automation methods, their parameters, and the objects to which they apply.


Document Conventions

This reference uses the following typographical conventions.

Convention | Description
monospaced text
 Examples and program code appear in a nonproportional typeface.
Bold text | Bold text indicates literal expressions that must be typed exactly as shown, such as function names, structure names, and keywords.
Italic text | Italic text indicates variable expressions, such as parameters, where you fill in the actual value.
CAPITAL LETTERS | Filenames, directory names, paths, function flags, and error messages appear in capital letters.
( ) In syntax statements, parentheses enclose one or more parameters that you pass to a function.
[ ] Brackets enclose optional syntax items. Type only the syntax within the brackets, not the brackets themselves.


Hardware Requirements

The following hardware is recommended when using the Schedule+ Automation interface:

  • Personal computer with a 32-bit 486/25 or higher; Pentium, or supported RISC-based processor, such as the MIPS R4000, Digital Alpha AXP; and PowerPC (running Windows NT® Server for RISC, or Windows, Windows 95 or Windows NT Server for 486/25 or higher)
  • VGA 16-color display (Super VGA (800 x 600) 256-color display recommended)
  • One or more hard disks with 30 megabytes (MB) minimum free hard disk space on the partition containing Windows NT Server files (50 MB recommended)
  • CD-ROM drive
  • 12 MB RAM minimum for 486- or Pentium-based systems (16 MB recommended)
  • 16 MB RAM minimum for RISC-based systems
  • Network adapter card


Software Requirements

To design applications for Schedule+, you need the following software installed on your system:

  • Microsoft Windows NT Server version 3.51 or later, or Windows 95
  • Microsoft Win32 SDK
  • Microsoft Windows-compatible C or C++ compiler and development environment

The following list provides examples of development environments that support Automation:

  • Microsoft Visual Basic version 4.0 or later
  • Microsoft Visual Basic for Applications (included with Microsoft Access, Microsoft Excel, Microsoft Project, and Microsoft Visual FoxPro™)
  • Microsoft Access version 2.0 or later
  • Microsoft Excel version 5.0 or later
  • Microsoft Project version 4.0 or later
  • Microsoft Visual C++ version 1.5 or later (version 2.0 recommended)

Note Although you can use Microsoft Visual Basic version 3.0 as the development environment for Schedule+, you cannot get or set multiple properties in one call. Therefore, Visual Basic version 4.0 should be used when developing for the Schedule+ Automation interface.


For More Information

For more information about Visual Basic, refer to the Microsoft Visual Basic Programming System for Windows Programmer’s Guide.

For more information about Automation programming, see Inside OLE, Second Edition, by Kraig Brockschmidt (Redmond, WA: Microsoft Press, August 1995) and the Automation in the Microsoft Win32 SDK.

For more information about Windows 95 and Windows NT Server programming, see the Microsoft Win32 SDK.

For information on Messaging Application Programming Interface (MAPI), see the MAPI Programmer’s Reference in the Microsoft Win32 SDK.


Overview

Microsoft® Schedule+ enables users to schedule group meetings, manage their daily appointment schedules, track projects and tasks, maintain lists of contacts, and perform many other time- and resource-management tasks.

Using the Microsoft Schedule+ Programmer’s Reference and the Schedule+ Automation interface (formerly OLE Automation), you can extend Schedule+ functionality by writing stand-alone programs and by adding custom commands to Schedule+ menus.

This section covers the following topics:

  • Key concepts of writing programs using Automation, which provides the foundation for the Schedule+ Automation interface
  • Objects exposed by Automation
  • Types of operations that can be performed using these objects
  • Customizing Schedule+ menus


Programmable Objects

The Schedule+ Automation interface enables you to create and manipulate objects. After you have created a new object, you can reference it with programming tools that support Automation, such as Microsoft® Visual Basic® and Microsoft® Visual C++®.

For the purposes of this document, an object is a Schedule+ Automation object — a software component that exposes its properties and methods. Such an object follows the Visual Basic programming model. You get and set properties, call methods, and query data members on these objects.

Schedule+ programmable objects can be thought of as additions or extensions to the programmable objects that are offered as part of Visual Basic, such as forms and controls that expose their properties and methods so that developers can tailor these objects for their program’s needs.

In addition to forms and controls, Visual Basic provides the CreateObject and LoadObject functions, which allow you to define a wide variety of other programmable objects.

Note These functions do not have specialized names, such as CreateSpreadsheet or CreateDatabase. They are general-purpose functions that provide for an unlimited number of programmable objects, including Automation objects.

Visual Basic programs drive Automation. These programs can also drive other programmable object libraries that support Automation, such as the libraries provided by Microsoft Excel version 5.0 and Microsoft Access version 2.0. Visual Basic can call many different programmable object libraries and act as the glue that holds all of these objects together.

Each programmable object library can create its own objects, set properties, and call methods. A Visual Basic program can coordinate the work of all the libraries. For example, it can direct the Microsoft Access object to find data in a specific table, instruct the Microsoft Excel object to perform calculations using that data, and then direct Automation objects to incorporate the results of those calculations in a Schedule+ Task object.


Using the Type Library

The Schedule+ Type Library (SP7EN32.OLB or SP7EN16.OLB) provides an abstract definition of the Schedule+ Automation object model, along with definitions of important constants. The Type Library provides specific type information relevant to C or C++ programmers. It should be used to supplement the information provided in this document.


Schedule+ Objects

Automation defines programmable objects that can be used to extend the capabilities of Schedule+. The two main Schedule+ object types are tables and items. Tables contain a series of rows, each of which is an item, and each item contains a set of properties. You can think of these properties as the columns of a row. This structure is shown in the following figure.

All objects can also have data members, which can be thought of as attributes. Properties are objects that can have a class (type) and value. They can be accessed by querying data members, or accessed directly by assigning the property to a variable of the appropriate type, as shown in the following sample code:

Dim objText As Object
Dim strText As Object

Set objText = objAppt.Text
    strText = objText.Value
'or
    strText = objAppt.Text


Application Object

At the top of the object hierarchy is the Application object, which represents an instance of the Schedule+ application. It is the base object through which all other objects are accessed. It is also the only object that can be retrieved directly by applications. In Visual Basic, this means that the Application object is the only object that the CreateObject function returns.

The following sample code uses the CreateObject function to return the Application object into an object variable:

Dim objApp As Object
Set objApp = CreateObject("SchedulePlus.Application")

For more information on the CreateObject function, see the Microsoft Visual Basic Programming System for Windows Programmer’s Guide.

All other objects, such as appointments and tasks, are accessed through properties defined on the Application object. All primary table objects are nested within the Schedule object. The table object hierarchy, as shown in the following figure, is important because it determines the correct syntax to use in your Visual Basic applications.


Schedule Object

The Schedule object represents an entire schedule that contains all appointments, projects, tasks, alarms, events, and contacts for a single user. In most cases, a Visual Basic program opens the currently logged-on user’s schedule. However, you can manipulate any schedule belonging to any user (subject to access privileges). For example, you can write an application that opens the schedules of everyone in a department and downloads the contents of everyone’s Contacts table into a Microsoft Access database.

The following sample code shows how to create an Application object and then retrieve the Schedule object from the topmost open schedule:

Dim objApp As Object
Dim objSched As Object

Set objApp = CreateObject("SchedulePlus.Application")

‘Retrieve the Schedule object for the topmost open schedule.
Set objSched = objApp.ScheduleSelected

The ScheduleLogged data member returns the Schedule object of the current user. To access another schedule, specify which schedule you want to work with by using the Application object’s ScheduleForFile or ScheduleForUser method. Both of these methods return a Schedule object. After retrieving the Schedule object, you can retrieve any Table object shown in the diagram and manipulate individual items within these tables.


Tables

When creating a table with Visual Basic, reference the table or item within it as an instance of a specific object. This object is a representation of the abstract table or item type. For example, when creating an appointment, you create an instance of an Appointment object.

Schedule+ defines an Appointments table that contains all appointments within a user’s schedule file. Each row of the Appointments table is an Appointment item that contains a set of properties you can get and set. Properties defined on an Appointment object include Start and OwnerName.

In some cases, a property itself can be a table. For example, an Appointment object might include the Attendees property, which returns a table that contains all the attendees for the appointment.

The following figure shows the Table object hierarchy for the preceding examples.

To support operations on tables, the Schedule+ Automation interface defines methods and data members common to all tables.

Instances of tables have the following data members.

Data Member | Description
AccessPermitted | Returns access control information for items in a table.
Application | Returns an Application object.
ChangeNumber | Returns the current change number of the table.
Class | Returns the data type of the property.
IsEndOfTable | Returns whether the cursor position is at the end of the table.
Name | Returns the name of the table object.
Parent | Returns to an object’s parent.
Position | Returns the current cursor position in the table.
Rows | Returns the number of rows in the table.

Instances of tables have the following methods.

Method | Description
DeleteItem | Deletes an item from the table.
GetRows | Retrieves a two-dimensional array of properties where each row corresponds to an item and each column corresponds to the specified name or property identifier.
Item | Returns the Item object to which the cursor points.
New | Creates a new item in the table.
Reset | Sets the current item cursor to the top of the table.
SetChangeIndex | Positions the cursor so that the rows following the cursor have change indexes greater than the specified value.
SetRange | Restricts the table to a specified date range.
SetRestriction | Sets a restriction on a table. Does not work for merged tables.
Skip | Skips a specified number of rows forward or backward in the table.


Single vs. Recurring Tables

The Schedule object provides additional support for creating recurring items (items that occur on a regular basis) for many of its table types. For example, you can set a recurring appointment for every Friday at 1 p.m. When programming with Schedule+ objects, recurring items are handled differently from single items, which only occur once.

It is possible for recurring items to have no defined end date. In this case, there could be an infinite number of items. Because Schedule+ cannot store an infinite number of recurring items, it stores a recurring item as a recurrence pattern.

In addition, because recurring items are stored as patterns, they have a different structure from single items and are kept in a separate table. In the case of appointments, recurring appointments are stored in the RecurringAppointments table. Single appointments are kept in a separate table known as the SingleAppointments table.


Merged Tables

The Schedule object simplifies programming by providing an additional table that contains the merged contents of the single and recurring tables of a given object. For example, the merged contents of the SingleAppointments and RecurringAppointments tables are available in the Appointments table.

These three tables can be accessed separately by program code. All three tables are linked, so changing an item in the RecurringAppointments table automatically updates the Appointments table. The only way to add a recurring appointment is by adding it to the RecurringAppointments table. You can add a single appointment by adding an item to either the SingleAppointments table or the Appointments table.

In most cases, you will access existing appointments through the Appointments table. Because the Appointments table includes recurring items, it is possible that your program will encounter an infinite number of items. For example, if a recurring meeting is set for every Monday at 10 a.m. and your program is designed to read the entire Appointments table, an infinite loop will result because a new item will be generated every Monday at 10 a.m.

Important When looping through tables that include recurring items, you should use the SetRange method to set boundary conditions that restrict the number of items retrieved; for example, only the appointments set for a particular day, month, or year. Failure to use the SetRange method will cause data members, such as Rows and Position, to return an error.


Exceptions Table

In some cases, it is necessary to specify exceptions to recurring items. For example, you may want to set up a recurring meeting for every Monday at 4 p.m., except for Mondays that fall on a holiday. To handle exceptions, items in the RecurringAppointments table have an Exceptions property, which is a table that contains all exceptions for the recurring item. Each exception is a separate item in the Exceptions table.

The easiest way to create an exception is to delete an instance of a recurring item in the merged table. Schedule+ automatically places the deleted instance in the Exceptions table under the recurrence pattern. For more information on creating exceptions, see Creating Exceptions to Recurring Appointments, Creating Exceptions to Recurring Events, and Creating Exceptions to Recurring Tasks.


Items

The item type simplifies programming because it allows you to manipulate all the primary Schedule+ objects in the same way. For example, an Appointment item is manipulated in the same way as a Task item because all items support the same properties and methods. The only difference is that you specify different sets of properties when dealing with different objects. For example, properties defined on an Appointment item include Start and OwnerName. In contrast, properties defined on a Task item include Billing, Mileage, Priority, and TaskSource.

All items have the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

All items have the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.

The following sample code illustrates how to create a new item in the Contacts table and manipulate its properties:

Sub CreateContact()
    Dim objTable As Object, objItem As Object

    'Get the Contacts table from the global Schedule object.
    Set objTable = gobjSchedule.Contacts

    'Create a new item in the Contacts table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    objItem.SetProperties FirstName:="First", LastName:="Last", _
        Notes:="Notes", _
        PhoneBusiness:="206-555-1212", _
        PhoneFax:="206-93-MS-FAX"

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing
End Sub

Some items in one table can be associated with items in another. For example, each Task item has a ProjectItemId property that identifies the Project item to which the task is related. Similarly, a Contact item can be associated with a project or a task. These relationships are frequently used by the Schedule+ user interface, but are not required. For example, it is not necessary to associate a Contact item with any other item in any other table.

The following sample code shows how to establish a relationship between a task and a project. It relates the first task in the Tasks table to the first project in the Projects table.

Dim objApp As Object, objSchedule As Object
Dim objProjects As Object, objTasks As Object
Dim objMyTask As Object, objMyProj As Object

‘Retrieve the Schedule object for the topmost open schedule.
Set objSchedule = objApp.ScheduleSelected

Set objProjects = objSchedule.Projects ‘Get the Projects table.
Set objTasks = objSchedule.Tasks       'Get the Tasks table.
Set objMyTask = objTasks.Item          ‘Get first item in Tasks table.
Set objMyProj = objProjects.Item       ‘Get first item in Projects table.
objMyTask.ProjectItemId = objMyProj.ItemId

Item relationships enable you to retrieve sets of associated items, such as all tasks associated with a particular project. To do this in your code, you can set a restriction on the Task table and Schedule+ will return only those tasks that meet the restriction. You can also loop through all Task items and find those with a specific ProjectItemId property.


Properties

The properties on an object are an extension of the Visual Basic properties available on that object.

The following data members are available on all properties.

Data Member | Description
Application | Returns an Application object.
ChangeNumber | Returns the current change number of the property.
Class | Returns the data type of the property.
Count | Returns the number of properties on a property.
Name | Returns the friendly name of the user or name of the table.
Parent | Returns to an object’s parent.

The following method is available on all properties.

Method | Description
Value | Gets or sets a specified value in a property.


Date and Time Properties

Schedule+ has a special way of dealing with dates and times. Items can have Date, Time, and Date/Time properties. Date/Time properties contain both the date and time components, and map directly to the Visual Basic Date data type. Date, Time, and Date/Time properties must be converted to a special 32-bit format before they can be used by Schedule+, then converted back before being assigned to the Visual Basic Date data type.

The following sample code uses the Visual Basic DateConvertFromLong function to convert the Long parameter to a Visual Basic Date:

Function DateConvertFromLong(ByVal DateSrc As Long) As Date

‘Use integer division to avoid rounding up.
DateConvertFromLong = DateSerial((DateSrc \ 512),
((DateSrc \ 32) Mod 16), (DateSrc Mod 32))

End Function

The following sample code uses the Visual Basic TimeConvertFromLong function to convert the Long parameter to a Visual Basic Time:

Function TimeConvertFromLong(ByVal TimeSrc As Long) As Date

‘Use integer division to avoid rounding up.
TimeConvertFromLong = TimeSerial((TimeSrc \ 4096),
(TimeSrc \ 64) Mod 64, (TimeSrc Mod 64))

End Function

The following sample code uses the Visual Basic LConvertTo32bitDate function to convert the Date parameter to a 32-bit date, which can be used as the date in Automation:

Function LConvertTo32bitDate(ByVal DateSrc As Date) As Long

LConvertTo32bitDate = (Year(DateSrc) * 512) +
(Month(DateSrc) * 32) + (Day(DateSrc))

End Function

The following sample code uses the Visual Basic LConvertTo32bitTime function to convert the Date parameter to a 32-bit time, which can be used as the time in Automation:

Function LConvertTo32bitTime(ByVal DateSrc As Date) As Long

LConvertTo32bitTime = (Hour(DateSrc) * 4096) +
(Minute(DateSrc) * 64) + Second(DateSrc)

End Function


Group Enabling

Schedule+ can be run in group-enabled mode (also known as mail-enabled) or stand-alone mode. Group enabling lets the user send e-mail, meeting requests, and so on, but requires that the user be logged on to a MAPI-compliant e-mail system.

In group-enabled mode, the Logon and Logoff methods on the Application object can be used to log the user on or off when starting or quitting the application.

For the Visual Basic application to create meetings, access privileges, and so on, MAPI properties must be used. See the MAPI Programmer’s Reference for more information.


Performance Issues

The following topics describe how reading multiple rows of data, using transactions, and caching maximize performance with Schedule+ Automation.


Reading Multiple Rows of Data

The table interface is an efficient way of reading large amounts of data with little overhead. It should be used extensively in the performance-sensitive areas of the application.

The following sample code shows how to use the table interface to read large amounts of data:

Private Sub GetData()
    Dim objAppts As Object
    Dim arrData As Variant
    Dim i As Integer

    Set objAppts = objSchedule.Appointments
    arrData = Array(9, 2)
    arrData = objAppts.GetRows(10, "Start", "End", "Text")

    For i = 0 To 9
        Debug.Print arrData(i, 0), arrData(i, 1), arrData(i, 2)
    Next
End Sub


Using Transactions

Transactions should be used whenever data is written. Writing multiple rows of data in a transaction not only improves performance, but also ensures data integrity while providing the option of undoing the changes. However, transactions should be kept open as briefly as possible. No user interface polling should occur while a transaction is open.

See the BeginTransaction, EndTransaction, and RollbackTransaction methods on the Schedule object.


Caching

Another way to improve the performance of your application is to cache as much as possible. For example, the list of projects for a typical schedule is small, and the project ItemId property can be easily cached and used when creating new tasks that are linked to a particular project. In this case, all the ProjectItemId property values can be read from the Projects table using a single call to the GetRows method.


Customizing Schedule+ Menus

You can provide users with custom functionality through commands on the Schedule+ menu bar. For example, you can add a custom menu command named Statistics that enables users to retrieve statistical information from their schedule files. Choosing Statistics can start a Visual Basic or Visual C++ program that displays schedule file statistics about items, such as the total number of contacts in the schedule file, total number of hours during which meetings are scheduled for the week or month, and so on.

You can remove menu commands from existing Schedule+ menus or remove entire menus. You can also add or remove menus by adding entries to the SCHDPLUS.INI file on Microsoft® Windows® version 3.1 and Microsoft Windows for Workgroups version 3.11, or to the Microsoft® Windows NT® or Windows 95 Registry. New menus can be added to the Schedule+ menu bar, or you can add new commands to existing Schedule+ menus.

On Windows NT Server and Windows 95, you should add entries to one or both of the following registry keys, depending on whether you are adding or removing menus:

hkey_current_user\software\microsoft\schedule+\custom menus
hkey_current_user\software\microsoft\schedule+\deleted menus


Adding Menus

To add a menu to the Schedule+ menu bar, add the following line to your SCHDPLUS.INI file or registry:

tag=version;menu to precede;new menu;reserved;command string;status bar text;help file;help id

The following table describes the parameters used in the syntax line.

Parameter | Description
tag | Identifies the command in the SCHDPLUS.INI file or registry, but serves no other purpose.
version | Specifies the Schedule+ version number with which the command is compatible.
menu to precede | Specifies a path to an existing menu item. The new menu item is added before the menu specified by this path. The menu name is case-insensitive. Ampersands are ignored. Commas should be used to specify the path to the menu. For example, the path Edit,Undo specifies the path to the Undo command on the Edit menu. To specify an absolute menu position, use # followed by the absolute number for the position. If -1 is specified for the position, the new menu will be added at the end of the specified menu.
new menu | Specifies the name of the menu to be added to the menu bar. You can include an ampersand (&) before the letter that is to serve as an ALT-key shortcut. If no name is provided, a separator will be added to the menu.
reserved | Reserved for future use and should be left blank.
command string | Specifies the command line needed to start the custom program.
status bar text | Contains text to be displayed in the Schedule+ status bar when the menu is selected.
help file | Specifies the Help file path to be invoked when the user presses F1 while the command is selected. This path is passed to the Windows Help program.
help id | Identifies the help identifier passed to the Windows Help program along with the Help file name. Use -1 if there is no specific entry in the Help file for this command.

The following line creates a new menu:

NewMenu=7.0;help;Sample;;;Status for sample;helpfile.hlp;0

The following line creates a new command on a menu:

NewCommand = 7.0;Sample,#-1;Schedule+ Ini;;notepad schdplus.ini;Edit Schedule+ Ini file;helpfile.help;0

The following line creates a separator bar on a menu:

Separator=7.0;Sample,#-1;;;;;;

Note On Windows NT Server and Windows 95, the text specified for the tag parameter maps to the registry value Name. The remaining text maps to the value Data. For example, in the last preceding sample entry, the value Name is Separator, and the value Data contains 7.0;Sample,#-1;;;;;;.


Deleting Menus

To remove a menu from the Schedule+ menu bar, add the following line to your SCHDPLUS.INI file or registry:

tag=version;menu to delete

The following table describes the parameters used in the syntax line.

Parameter | Description
tag | Identifies the command in the SCHDPLUS.INI file or registry, but serves no other purpose.
version | Specifies the Schedule+ version number with which the command is compatible.
menu to delete | Specifies a path to the menu item to be removed. The menu name is case-insensitive. Ampersands are ignored. Commas should be used to specify the path to the menu. For example, the path Edit,Undo specifies the path to the Undo command on the Edit menu. To specify an absolute menu position, use # followed by the absolute number for the position.

The following lines delete the Help and Undo commands:

DeleteHelp=7.0;help;
DeleteUndo=7.0;edit,undo


Programming Tasks

This section examines specific programming tasks you can perform with the Schedule+ Automation interface (formerly Schedule+OLE Automation).


Logging on to Schedule+

An application should log on to Schedule+ before performing any other tasks. If Schedule+ is running in group-enabled mode, the application must also log on to a MAPI session to be able to create meetings, modify access privileges, and so on.

Your application should follow the procedures shown here:

To log on to Schedule+
  1. Log on to a MAPI session.
  2. Get the user’s schedule.
To log off Schedule+
  1. Log off the MAPI session.
  2. Release the objects.

The following sample code shows a typical initialization and deinitialization:

Dim objSession As Object
Dim objApp As Object
Dim objSched As Object

'Log on to a MAPI session.
Set objSession = CreateObject ("MAPI.Session")
objSession.Logon

'Get the user's schedule.
Set objApp = CreateObject ("SchedulePlus.Application")
objApp.Logon
Set objSched = objApp.ScheduleLogged

'Log off the MAPI session.
objApp.Logoff

'Release the objects.
Set objSession = Nothing
Set objApp = Nothing
Set objSched = Nothing


Creating Single Appointments

A single (nonrecurring) appointment can be created using either the SingleAppointments table or the Appointments table, which contains the merged contents of the single and recurring tables. Because these tables are linked together, creating an item in one table automatically creates that item in the other table. For more information on the Appointments table, see Merged Tables.

To create a single appointment
  1. Get the SingleAppointments table from the global Schedule object.
  2. Use the New method to create a new item in the SingleAppointments table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates a SingleAppointment object and sets several properties:

Sub CreateAppt()
    Dim objTable As Object, objItem As Object
    Dim dt As Date

    'Get the SingleAppointments table from the global Schedule object.
    Set objTable = gobjSched.SingleAppointments

    dt = DateAdd("d", 1, Now)

    'Create a new item in the SingleAppointments table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    objItem.SetProperties Text:="OLE: CreateAppt " & Now(), _
        Notes:="Notes", _
        Start:=DateAdd("h", 1, dt), _
        End:=DateAdd("h", 2, dt)

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing

End Sub


Adding Alarms

You can add an alarm to a single appointment by setting the necessary properties, as shown in the following sample code:

objItem.SetProperties AlarmTypeUnit:=0, AlarmAmount:=15, Ring:=TRUE

For tasks, the following sample code shows how the BeforeEnd property can be used to indicate that the alarm should ring before the end of the item:

objItem.SetProperties , _
    AlarmTypeUnit:=0, AlarmAmount:=15, _
    Ring:=True, BeforeEnd:=True


Creating Meetings

A meeting is an appointment that has attendees. Before you can create a meeting, Schedule+ must be running in group-enabled mode as a valid user.

To create a meeting
  1. Create a single or recurring appointment.
  2. Use the New method to add one or more attendees to the appointment.
  3. Set the desired MAPI properties.
  4. Release the objects.

Note The logged-on user does not need to be added as an attendee because that user is the meeting organizer.

The UserDisplay, UserEntryId, UserSearchKey, UserWell, IsUserDistributionList and AttendeeStatus properties are necessary for creating a single attendee. The first three are MAPI properties (PR_DISPLAY_NAME, PR_ENTRY_ID, and PR_SEARCH_KEY) on the Recipient object. Also, the PR_OBJECT_TYPE property is needed to determine whether a recipient is a Distribution List. For more information on these MAPI properties, the Recipient object, and Distribution Lists, see the MAPI Programmer's Reference.

The following sample code shows how to add attendees to an Appointment object:

Public Sub AddAttendee (objItem As Object)
    Dim objAttendee As Object
    Dim objMessage As Object
    Dim objOneRecip As Object
    Const ulPrSearchKey = 806027522 ' 0x300B0102
    Const ulPrObjectType = 268304387 ' 0x0FFE0003

    'Create a new attendee.
    Set objAttendee = objItem.Attendees.New

    'Create the recipient.
    Set objMessage = objSession.Outbox.Messages.Add
    Set objOneRecip = objMessage.Recipients.Add

    objOneRecip.Name = "Dave Whitney"
    objOneRecip.Type = mapiTo
    objOneRecip.Resolve

    'Set recipient properties into an attendee.
    objAttendee.SetProperties _
        UserDisplay:=objOneRecip.AddressEntry.Name _
        UserEntryId:=objOneRecip.AddressEntry.Id _
        UserSearchKey:=objOneRecip.AddressEntry.Fields.Item(ulPrSearchKey), _
        IsUserDistributionlist = CBool(objOneRecip.AddressEntry.Fields.Item(ulPrObjectType) = 8) _
        UserWell:=1, _
        AttendeeStatus:=0

    'Release the objects.
    Set objMessage = Nothing
    Set objOneRecip = Nothing
    Set objAttendee = Nothing
End Sub


Creating Recurring Appointments

Schedule+ allows you to define recurring appointments. The exact appointment dates are determined by a recurrence pattern that specifies on which days, weeks, months, or years the appointment recurs. Recurring appointments can be created only in the RecurringAppointments table.

To create a recurring appointment
  1. Get the RecurringAppointments table from the global Schedule object.
  2. Use the New method to create a new item in the RecurringAppointments table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates a new appointment that recurs weekly on Tuesday and sets a reminder two days before the appointment:

Public Sub CreateRecurAppt()
    Dim objTable As Object
    Dim objItem As Object
    Dim dt As Date

    'Get the RecurringAppointments table from the global Schedule object.
    Set objTable = objSchedule.RecurringAppointments

    'Create a new item in the RecurringAppointments table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    dt = Now
    objItem.SetProperties Text:="Weekly Recurring Appointment" & Now(), _
        BusyType:=btfNormal1Busy, Ring:=True, AlarmAmount:=CLng(2), _
        AlarmTypeUnit:=CLng(2), BeforeEnd:=False, _
        RecurringType:=trecurWeekly, WeekInterval:=CLng(1), _
        DayOfWeekMask:=CLng(4), DayOfWeekStart:=CLng(0), _
        StartRecurringDate:=LConvertTo32bitDate(dt), _
        EndRecurringDate:=LConvertTo32bitDate(DateAdd("yyyy", 1, dt)), _
        StartRecurringTime:=LConvertTo32bitTime(DateAdd("h", 1, dt)), _
        EndRecurringTime:=LConvertTo32bitTime(DateAdd("h", 2, dt))

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing
End Sub


Creating Exceptions to Recurring Appointments

After creating a recurring appointment, you can specify exceptions to the recurrence pattern. For example, you can define an appointment that recurs on Monday of every week, except for those weeks in which Monday is a holiday.

The following procedure shows how to create an exception to recurring appointments by explicitly adding items to the Exceptions table.

To create an exception to a recurring appointment
  1. Use the New method to create a new item in the Exceptions table.
  2. Set the desired properties on the item.
  3. Release the objects.

The following sample code creates an exception to a recurring appointment:

Public Sub AddException2(objItem As Object)
    Dim objException As Object
    Dim dt As Date

    'Note: objItem is a RecurringAppointment object.

    'Create an exception that deletes an instance of the recurrence pattern.
    dt = #11/16/95#
    Set objException = objItem.Exceptions.New

    'Set the desired properties on the item.
    objException.SetProperties InstanceDate:=LConvertTo32bitDate(dt), Deleted:=True

    'Release the object.
    objException = Nothing

    'Create an exception that modifies an instance of the recurrence pattern.
    dt = DateAdd("w", 1, dt)
    Set objException = objItem.Exceptions.New

    'Set the desired properties on the item.
    objException.SetProperties InstanceDate:=LConvertTo32bitDate(dt), Deleted:=False
    Text:="Exception"

    'Release the object.
    objException = Nothing
End Sub

You can also create exceptions to recurring appointments by deleting or modifying specific instances in the merged tables.

After you delete an instance of the recurring appointment, Schedule+ automatically removes that instance from the Appointments table and creates a new item in the Exceptions table. To determine which items are exceptions, an application can scan each Exceptions table and examine the properties of each Exception item. For example, the InstanceDate property indicates the date on which the item would have occurred if it had not been deleted.

The series of steps for creating a recurring event or task is similar, but you must delete instances of the recurring event from the Events table and instances of the recurring task from the Tasks table.


Reading Appointments

The simplest way to read appointments is from the Appointments table, which automatically merges instances of single and recurring appointments.

To read an appointment
  1. Get the Appointments table from the global Schedule object.
  2. Set the desired date range.
  3. Examine each row in the table.
  4. Release the objects.

The following sample code reads an appointment from the Appointments table:

Public Sub ReadAppts()
    Dim objTable As Object
    Dim objAppt As Object

    'Get the Appointments table from the global Schedule object.
    Set objTable = objSchedule.Appointments

    'Set the desired date range.
    objTable.SetRange #11/16/95#, #11/16/95#

    'Iterate over all the rows in the table.
    While Not objTable.IsEndOfTable
        Set objAppt = objTable.Item
        Debug.Print objAppt.Text, objAppt.Start, objAppt.End
        objTable.Skip
    Wend

    'Release the objects.
    Set objAppt = Nothing
    Set objTable = Nothing
End Sub


Modifying Appointments

To modify an appointment, retrieve an Appointment object and change its properties as necessary. The following sample code shows how to modify the text of an appointment:

objAppt.SetProperties Text:="New Text"

The SetProperties method is an efficient way to change or create properties on items because you can set multiple properties with a single call to this method. You can also set the value directly, as shown in the following sample code:

objAppt.Text = "New Text"


Creating Projects

The Projects table on the Schedule object contains all the project information. Projects are used for organizing tasks. After creating a project, you can link tasks to it. Tasks linked to a project can be thought of as belonging to that project.

To create a project
  1. Get the Projects table from the global Schedule object.
  2. Use the New method to create a new item in the Projects table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code retrieves the Project table from the global Schedule object and then creates a new project:

Public Sub CreateProject()
    Dim objTable As Object
    Dim objItem As Object

    'Get the Projects table from the global Schedule object.
    Set objTable = objSchedule.Projects

    'Create a new item in the Projects table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    objItem.SetProperties Text:="Home Improvement", Priority:=LConvertTo32bitPriority("A5")

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing
End Sub


Linking Tasks to a Project

Link a task to a project by setting its ProjectItemId property.

The following sample code links a task to a project:

Public Sub LinkTask(objTask As Object, objProject As Object)
    objTask.SetProperties ProjectItemId:=objProject.ItemId
End Sub


Creating Single Tasks

A single (nonrecurring) task can be created using either the SingleTasks table or the Tasks table, which contains the merged contents of the single and recurring tables. Because these tables are linked together, creating an item in one table automatically creates that item in the other table. For more information on the Tasks table, see Merged Tables.

To create a single task
  1. Get the SingleTasks table from the global Schedule object.
  2. Use the New method to create a new item in the SingleTasks table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates a SingleTask object and sets several properties:

Sub CreateTask()
    Dim objTable As Object, objItem As Object
    Dim dt As Date

    'Get the SingleTasks table from the global Schedule object.
    Set objTable = gobjSchedule.SingleTasks

    dt = DateAdd("d", 1, Now)

    'Create a new item in the SingleTasks table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    objItem.SetProperties Text:="OLE: CreateTask " & Now(), _
        Notes:="Notes", _
        StartDate:=LConvertTo32bitDate(DateAdd("d", 1, dt)), _
        EndDate:=LConvertTo32bitDate(DateAdd("d", 2, dt))

    'Release item object
    Set objItem = Nothing

    'Release table object
    Set objTable = Nothing

End Sub


Creating Recurring Tasks

Schedule+ allows you to define recurring tasks. The exact task dates are determined by a recurrence pattern that specifies on which days, weeks, months, or years the task recurs.

To create a recurring task
  1. Get the RecurringTasks table from the global Schedule object.
  2. Use the New method to create a new item in the RecurringTasks table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates a task that recurs weekly on Tuesday and sets a reminder two days before the task:

Public Sub CreateRecurTask()
    Dim objTable As Object
    Dim objItem As Object
    Dim dt As Date

    'Get the RecurringTasks table from the global Schedule object.
    Set objTable = objSchedule.RecurringTasks

    'Create a new item in the RecurringTasks table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    dt = Now
    objItem.SetProperties Text:="Weekly Recurring Task" & Now(), _
        Ring:=True, AlarmAmount:=2, _
        AlarmTypeUnit:=typeunitDay, BeforeEnd:=False, _
        RecurringType:=trecurWeekly, WeekInterval:=1, _
        DayOfWeekMask:=4, DayOfWeekStart:=0, _
        StartRecurringDate:=LConvertTo32bitDate(dt), _
        EndRecurringDate:=LConvertTo32bitDate(DateAdd("yyyy", 1, dt)), _
        StartRecurringTime:=LConvertTo32bitTime(DateAdd("h", 1, dt)), _
        EndRecurringTime:=LConvertTo32bitTime(DateAdd("h", 2, dt))

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing
End Sub


Creating Exceptions to Recurring Tasks

After creating a recurring task, you can specify exceptions to the recurrence pattern. For example, you can define a task that recurs on Monday of every week, except for those weeks in which Monday is a holiday.

To create an exception to a recurring task
  1. Use the New method to create a new item in the Exceptions table.
  2. Set the desired properties on the item.
  3. Release the objects.

The following sample code creates an exception to a recurring task:

Public Sub AddException2(objItem As Object)
    Dim objException As Object
    Dim dt As Date

    'Note: objItem is a RecurringTask object.

    'Create an exception that deletes an instance of the recurrence pattern.
    dt = #11/16/95#
    Set objException = objItem.Exceptions.New

    'Set the desired properties on the item.
    objException.SetProperties InstanceDate:=LConvertTo32bitDate(dt), Deleted:=True

    'Release the object.
    objException = Nothing

    'Create an exception that modifies an instance of the recurrence pattern.
    dt = DateAdd("w", 1, dt)
    Set objException = objItem.Exceptions.New

    'Set the desired properties on the item.
    objException.SetProperties InstanceDate:=LConvertTo32bitDate(dt), Deleted:=False
    Text:="Exception"

    'Release the object.
    objException = Nothing
End Sub

You can also create exceptions to recurring tasks by deleting or modifying specific instances in the merged tables.

After you delete an instance of the recurring task, Schedule+ automatically removes that instance from the Tasks table and creates a new item in the Exceptions table. To determine which items are exceptions, an application can scan the Exceptions table and examine the properties of each Exception item. For example, the InstanceDate property indicates the date on which the item would have occurred if it had not been deleted.

The series of steps for creating a recurring appointment or event is similar, but you must delete instances of the recurring appointment from the Appointments table and instances of the recurring event from the Events table.


Creating Single Events

A single (nonrecurring) event can be created using either the SingleEvents table or the Events table, which contains the merged contents of the single and recurring tables. Because these tables are linked together, creating an item in one table automatically creates that item in the other table. For more information on the Events table, see Merged Tables.

To create a single event
  1. Get the SingleEvents table from the global Schedule object.
  2. Use the New method to create a new item in the SingleEvents table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates a SingleEvent object and sets several properties:

Sub CreateEvent()
    Dim objTable As Object, objItem As Object
    Dim dt As Date

    'Get the SingleEvents table from the global Schedule object.
    Set objTable = gobjSchedule.SingleEvents

    dt = DateAdd("d", 1, Now)

    'Create a new item in the SingleEvents table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    objItem.SetProperties Text:="OLE: CreateEvent " & Now(), _
        Notes:="Notes", _
        StartDate:=LConvertTo32bitDate(dt + 1), _
        EndDate:=LConvertTo32bitDate(dt + 2)

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing

End Sub


Creating Recurring Events

Schedule+ allows you to define recurring events. The exact event dates are determined by a recurrence pattern that specifies on which days, weeks, months, or years the event recurs.

To create a recurring event
  1. Get the RecurringEvents table from the global Schedule object.
  2. Use the New method to create a new item in the RecurringEvents table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates an annual event starting on the current date and sets a reminder two days before the event:

Sub CreateRecurringEvent ()
    Dim objTable As Object, objItem As Object
    Dim dt As Date, dtNotify As Date

    'Get the RecurringEvents table from the global Schedule object.
    Set objTable = gobjSchedule.RecurringEvents

'Create a new item in the RecurringEvents table.
Set objItem = objTable.New

    'Set the desired properties on the item.
    dt=Now
    objItem.SetProperties Text:="OLE: CreateAnnualEvent " & Now(), _
        AccessActual:=saclOwner, _
        Ring:=True, AlarmAmount:=2, _
        AlarmTypeUnit:=typeunitDay, BeforeEnd:=False, _
        RecurringType:=trecurYearlySpecific, YearInterval:=1, _
        DayOfMonthMask:=(2 ^ (Day(dt) - 1)), _
        MonthOfYearMask:=(2 ^ (Month(dt) - 1)), _
        StartRecurringDate:=LConvertTo32bitDate(dt)

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing

End Sub


Creating Exceptions to Recurring Events

After creating a recurring event, you can specify exceptions to the recurrence pattern. For example, you can define an event that recurs on Monday of every week, except for those weeks in which Monday is a holiday.

To create an exception to a recurring event
  1. Use the New method to create a new item in the Exceptions table.
  2. Set the desired properties on the item.
  3. Release the objects.

The following sample code creates an exception to a recurring event:

Public Sub AddException2(objItem As Object)
    Dim objException As Object
    Dim dt As Date

    'Note: objItem is a RecurringEvent object.

    'Create an exception that deletes an instance of the recurrence pattern.
    dt = #11/16/95#
    Set objException = objItem.Exceptions.New

    'Set the desired properties on the item.
    objException.SetProperties InstanceDate:=LConvertTo32bitDate(dt), Deleted:=True

    'Release the object.
    objException = Nothing

    'Create an exception that modifies an instance of the recurrence pattern.
    dt = DateAdd("w", 1, dt)
    Set objException = objItem.Exceptions.New

    'Set the desired properties on the item.
    objException.SetProperties InstanceDate:=LConvertTo32bitDate(dt), Deleted:=False
    Text:="Exception"

    'Release the object.
    objException = Nothing
End Sub

You can also create exceptions to recurring events by deleting or modifying specific instances in the merged tables.

After you delete an instance of the recurring event, Schedule+ automatically removes that instance from the Events table and creates a new item in the Exceptions table. To determine which items are exceptions, an application can scan the Exceptions table and examine the properties of each Exception item. For example, the InstanceDate property indicates the date on which the item would have occurred if it had not been deleted.

The series of steps for creating a recurring appointment or task is similar, but you must delete instances of the recurring appointment from the Appointments table and instances of the recurring task from the Tasks table.


Creating Contacts

The Contacts table on the Schedule object contains all the information about a contact. After you create a contact, you can link tasks to it. Tasks linked to a contact can be thought of as belonging to that contact.

To create a contact
  1. Get the Contacts table from the global Schedule object.
  2. Use the New method to create a new item in the Contacts table.
  3. Set the desired properties on the item.
  4. Release the objects.

The following sample code creates a new item in the Contacts table and sets several properties:

Sub CreateContact()
    Dim objTable As Object, objItem As Object

    'Get the Contacts table from the global Schedule object.
    Set objTable = gobjSchedule.Contacts

    'Create a new item in the Contacts table.
    Set objItem = objTable.New

    'Set the desired properties on the item.
    objItem.SetProperties FirstName:="First", LastName:="Last", _
        Notes:="Notes",PhoneBusiness:="206-555-1212", _
        PhoneFax:="206-93-MS-FAX"

    'Release the objects.
    Set objItem = Nothing
    Set objTable = Nothing
End Sub


Linking Tasks to a Contact

Link a task to a contact by setting its ContactItemId property.

The following sample code links a task to a contact:

Public Sub LinkTask(objTask As Object, objContact As Object)
    objTask.SetProperties ContactItemId:=objContact.ItemId
End Sub


Reading the AlarmsToRing Table

The AlarmsToRing table contains the date and time for currently active alarms, as well as a path to the item on which each alarm is set. Schedule+ automatically maintains this table as a convenience to the programmer. It is not necessary to update the table when alarms on items are deleted or modified.

Note Do not explicitly add or modify items in the table. This can produce unexpected results.

To read the AlarmsToRing table
  1. Get the AlarmsToRing table from the global Schedule object.
  2. Set the desired restriction on the table.
  3. Examine all items in the table.
  4. Release the objects.

The following sample code shows how to read the currently active alarms in the AlarmsToRing table:

Public Sub GetNextAlarm()
    Dim objAlarmsToRing As Object
    Dim objAlarm As Object

    'Get AlarmsToRing table from the global Schedule object.
    Set objAlarmsToRing = objSchedule.AlarmsToRing

    'Set the desired restriction on the table.
    objAlarmsToRing.SetRestriction "Notify", Now, ">="
    objAlarmsToRing.SetRestriction "Notify", DateAdd("d", 1, Now), "<="

    'Iterate on all items in the table.
    While Not objAlarmsToRing.IsEndOfTable
        Set objAlarm = objAlarmsToRing.Item
        Debug.Print objAlarm.Notify
        objAlarmsToRing.Skip
    Wend

    'Release the objects.
    Set objAlarm = Nothing
    Set objAlarmsToRing = Nothing
End Sub


Setting Access Controls

In a group-enabled environment, users and applications can set access controls on objects to prevent unauthorized access to objects in a schedule file.

Access controls are defined within the AccessControls table, which consists of individual Access items. Each of these items can be visualized as a row in the AccessControls table. Each row in the table identifies a user and a set of access privileges that apply to that user. The following figure shows the properties that define the user and the access controls.

Note The AccessLists and TableList properties are not accessible if the AccessDefault property is set to saclOwner.

Specify access controls for the user by setting the appropriate values in the multivalued properties AccessLists and TableList. The AccessLists property is a list of integer values that define the access level for each table in the AccessLists property. The TableList property is a list of tables the user is restricted from accessing. The values in the AccessLists and TableList properties must be listed in the same order.

The UserSearchKey, UserEntryId, and UserDisplay properties identify the user to which the access controls apply.

The following table shows access levels that can be defined for each table in the schedule.

Value | Meaning
0 | No access
1 | Minimal (read-only free or busy time for the schedule)
2 | Read
3 | Create
4 | Write
5 | Owner

The AccessDefault property is the default access level that is granted to the user for all tables whose access is not explictly given in the AccessLists and AccessControls properties. If the AccessLists and TableList properties have no entries or are not present, other users can access all tables with the access level specified in the AccessDefault property.

Define rows in the AccessControls table only for users whose access rights you explicitly want to set. For all other users in the organization, set the values in the first row of the table, which is called the default row. The default row is a special row that consists of default access controls for all users not listed in other rows of the table. In the default row, the UserSearchKey and UserEntryId properties must be set to Null. The AccessDefault, AccessLists, and TableList properties can be set to any valid values.

Note The ReceiveMeetingRequest property identifies whether the user is a delegate to the meeting and receives all of the schedule owner’s meeting requests. This property should not be set on the default row.

The following sample code modifies the default access for the user’s default row:

Public Sub ModifyAcls()
    Dim objAccessControls As Object
    Dim objAccess As Object

    Set objAccessControls = objSchedule.AccessControls

    ' Get the default row
    objAccessControls.SetRestriction "UserEntryId", "", "=="
    Set objAccess = objAccessControls.Item

    ' Print out the default access
    Debug.Print objAccess.AccessDefault

    ' Change the default access to be None
    objAccess.SetProperties AccessDefault:=CLng(0)

    ' Release the objects
    Set objAccess = Nothing
    Set objAccessControls = Nothing
End Sub


Objects

This section provides a reference for Schedule+ Automation objects and their corresponding properties, data members, and methods in table format. The tables provide a brief description of each property, data member, and method. All objects discussed in this section are items, except the Application and Schedule objects.


Application Object

The Application object represents the running instance of a Schedule+ application. It is the only Schedule+ object that can be retrieved by other applications.

The Application object has the following data members.

Data Member | Description
Application | Returns an Application object.
EndRange | Returns the end date of the range of dates in view on the topmost open schedule.
EndSelection | Returns the end date and time of the selection in the topmost open schedule.
IsItemSelected | Returns a Boolean value indicating whether an item is selected in the topmost open schedule.
IsMailEnabled | Returns a Boolean value indicating whether Schedule+ is working in a group-enabled environment.
IsScheduleSelected | Returns a Boolean value indicating whether a Schedule+ user has a currently open schedule.
ItemIdSelected | Returns the item identifier for the selected item in the topmost schedule.
LoggedOn | Returns a Boolean value indicating whether a user has logged on.
Parent | Returns to the object’s parent object.
ScheduleLogged | Returns the Schedule object for the currently logged-on user.
ScheduleSelected | Returns the Schedule object for the topmost open schedule.
StartRange | Returns the start range of the range of dates in the view for the topmost open schedule.
StartSelection | Returns the start date and time of the selection in the topmost open schedule.
TableSelected | Returns the name of the table that contains the selected item, or an error if no table is selected.
UserEntryId | Returns the MAPI entry identifier for the logged-on Schedule+ user.
UserName | Returns the name of the user that is currently logged on to Schedule+.
UserSearchKey | Returns the MAPI search key of the currently-logged-on Schedule+ user.

The Application object has the following methods.

Method | Description
Logoff | Logs off Schedule+.
Logon | Logs on to Schedule+.
ScheduleForFile | Opens a schedule file for a filename.
ScheduleForUser | Opens a schedule file for a specific user.


Schedule Object

The Schedule object represents the entire schedule and all the objects contained therein. Using the Schedule object, applications can get and set user preferences for the schedule. Additionally, applications can use the Schedule object to retrieve tables for all the Schedule+ objects.

The Schedule object has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessControls | Table of Access objects.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmountDefault | Default time interval before the start of an appointment when an alarm will ring.
AlarmAmountDefaultTask | Default time interval before the start of a task when an alarm will ring.
AlarmsEnabled | Determines whether alarms have been enabled.
AlarmsToRing | Table of Alarm objects.
AlarmTypeUnitDefault | Time unit to use for the alarm.
AlarmTypeUnitDefaultTask | Time unit to use for the alarm for tasks.
Appointments | Single appointments merged with instances of recurring appointments.
AutoAlarms | Determines whether an alarm should be set for new appointments and events.
AutoAlarmsTask | Determines whether an alarm should be set for new tasks.
AutoProcessMeetingCancellations | Determines whether Schedule+ should automatically process incoming meeting cancellations for the user.
AutoProcessMeetingRequests | Determines whether Schedule+ should automatically process incoming meeting requests for the user.
BeforeEndDefaultTask | Indicates that the alarm is set relative to the end rather than to the start of a new task by default.
BossWantsCopy | Determines whether the owner, in addition to the meeting delegates, receives a copy of meeting mail.
ChangeNumber | Change number for the schedule.
Contacts | Table of contacts.
DailyAlarm | Determines whether daily alarms should ring.
DayEndsAt | Number of half hours from midnight for the end of day.
DayStartsAt | Number of half hours from midnight for the start of day.
DefaultEstimatedEffortAmount | Amount used as default for estimated effort.
DefaultEstimatedEffortTypeUnit | Type of unit for default estimated effort.
DefaultHomePhone1 | First default home phone type.
DefaultHomePhone2 | Second default home phone type.
DefaultProjectPriority | Priority assigned to new projects.
DefaultTaskDurationAmount | Amount of time used as default for task duration.
DefaultTaskDurationTypeUnit | Type of unit for default task duration.
DefaultTaskPriority | Priority assigned to new tasks.
DelegateEntryId | Multivalued property containing a list of string values for the MAPI entry identifiers of delegates.
DelegateName | Multivalued property containing a list of string values for the human-readable names of delegates.
DeleteDataAfter | Number of months of data to keep before prompting the user for archiving.
DisallowAppointmentOverlap | Boolean value indicating whether to allow overlapping appointments to be scheduled. Designed particularly for resources.
DisallowRecurringItems | Boolean value indicating whether to allow recurring items to be scheduled.
Events | Single events merged with instances of recurring events.
LastCleanup | Last date that schedule cleanup was performed.
LastDailyAlarm | Date that the daily alarm was last rung.
LastSynchronized | Date and time of the last schedule synchronization.
Name | Calendar-friendly name of the schedule.
Password | Password for the schedule file.
Projects | Table of all projects.
PublishFreeBusy | Number of months to publish whether the user is free or busy.
Ranges | Range of change numbers.
ReceivedRanges | Range of change numbers received from the master schedule.
ReceivedRangesTable | Table of change numbers.
RecurringAppointments | Recurring appointments.
RecurringEvents | Recurring events.
RecurringTasks | Recurring tasks.
ResourceType | Determines whether the schedule is for a resource such as a conference room.
Roles | Table of Role items.
ScheduleId | Item identifier associated with a Schedule object.
SentRanges | Range of change numbers sent to the master schedule.
SentRangesTable | Table of change numbers.
SingleAppointments | Appointments that occur only once.
SingleEvents | Events that occur only once.
SingleTasks | Tasks that occur only once.
SoundDefault | Default value for the sound level of an alarm.
SoundLevel | Sound level of an alarm.
TableForRange | Identifier for a table to which a range of change numbers refers.
Tasks | Single tasks merged with instances of recurring tasks.
TimeUnitsPerHour | Number of time units per hour shown in appointment and planner views.
Timezone | Current time zone for the schedule.
UserEntryId | User’s MAPI entry identifier.
UserSearchKey | User’s MAPI search key.
WeekStartOn | Day on which to start the week.

The Schedule object has the following data members.

Data Member | Description
Application | Returns an Application object.
CanUndo | Returns whether the last transaction can be undone.
Parent | Returns to the object’s parent object.
Properties | Returns the count and values of the properties defined on an object, or the property itself if used with an index.
SupportedOperations | Returns the operations available for the schedule.
Timezone | Returns the current time zone for the schedule.
Usage | Returns information on how actively the Schedule object is being used.
UserAddress | Returns the e-mail address of the currently logged-on Schedule+ user.
UserEntryId | Returns the MAPI entry identifier for the logged-on Schedule+ user.
UserName | Returns the name of the user currently logged on to Schedule+.
UserSearchKey | Returns the MAPI search key of the currently logged-on Schedule+ user.
Visible | Returns whether the schedule is displayed.

The Schedule object has the following methods.

Method | Description
Activate | Activates a Schedule+ window to display the schedule.
BeginTransaction | Begins a transaction to buffer changes to a schedule.
ClearUndo | Clears any undo operations available for the schedule.
DeleteProperties | Deletes a specified property.
EndTransaction | Saves all buffered changes to a schedule.
Flush | Removes properties that have been changed.
FreeBusy | Indicates whether a user is free or busy.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
RollbackTransaction | Rolls back all buffered changes to a schedule.
SetProperties | Sets the value of one or more properties.
Synchronize | Synchronizes the logged-on user’s local and server schedules (if group-enabled).
Undo | Undoes the last operation performed on the schedule.


Access Object

The Access object stores access control information for a user’s schedule file and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessDefault | Default ACL level for Access objects.
AccessEffective | ACL level granted to the user viewing an item.
AccessLists | Multivalued property that contains ACL levels of a table.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | Mail entry identifier for the creator of an item.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key of an item’s creator.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
ReceiveMeetingRequest | Determines whether a delegate, in addition to the meeting owner, should receive meeting requests.
TableList | Multivalued list of tables for ACLs.
UserDisplay | MAPI display name of the user associated with an item.
UserEntryId | MAPI entry identifier for a user associated with an item.
UserSearchKey | MAPI search key of a user associated with an item.

The Access object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Access object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Alarm Object

The Alarm object represents a single alarm in the AlarmsToRing table. For more information, see Reading The AlarmsToRing Table.

The Alarm object has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | Mail entry identifier for the creator of an item.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key of an item’s creator.
ItemId | Item identifier for an object.
ItemIdPath | Multivalued property that contains the item identifiers in a path.
LastModified | Date and time at which the object was last modified.
Notify | Date and time for an alarm to ring.
TablePath | Multivalued property that contains the tables in a path.

The Alarm object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Alarm object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Appointment Object

The Appointment object represents an appointment within the Schedule object and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmount | Time interval before the start of an appointment when an alarm will ring.
AlarmAmountAgain | Default amount of time to wait when the user sets the alarm snooze option.
AlarmAmountOriginal | Time interval before an appointment for which an alarm was set before the user set the alarm snooze option.
AlarmTypeUnit | Time unit to use for the alarm.
AlarmTypeUnitAgain | Time unit to use as the default in the Reminder dialog box.
AlarmTypeUnitOriginal | Time unit used for an alarm before the user set the alarm snooze option.
Attendees | Table of all the attendees for an item.
BusyType | Determines whether an item should make the user busy during that time.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
CriticalChange | Date and time that a critical change occurred for an item.
End | End date and time for an item.
IsFromOther | Set of flags indicating that the item was created by another application.
IsRecurringInstance | Determines whether an item is an instance of a recurrence pattern.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
Notify | Date and time for an alarm to ring.
Notes | Notes on an item.
OwnerEntryId | MAPI entry identifier for the meeting owner of an item.
OwnerName | MAPI display name for the meeting owner of an item.
OwnerSearchKey | MAPI search key for the meeting owner of an item.
Ring | Determines whether an alarm has been set to ring for an item.
RingAgain | Preference used when ringing an alarm.
RingOriginal | Determines whether there used to be an alarm on an item before the alarm rang.
Start | Required. Start date and time for an item.
Text | Text value of an item.
Where | Location of a meeting.

The Appointment object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Appointment object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Attendee Object

An Attendee object represents a single attendee in the Attendees table, which is a property defined in an Appointment object.

The Attendee object has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AttendeeStatus | Current status of a meeting attendee.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
CriticalChange | Date and time that a critical change occurred for an item.
IsUserDistributionList | Boolean value indicating that the user associated with an item is a distribution list.
ItemId | Item identifier for an object.
LastModified | Date and time at which an object was last modified.
LastReceived | Send date and time of the last response that was received.
UserDisplay | MAPI display name of the user associated with an item.
UserEntryId | MAPI entry identifier for a user associated with an item.
UserSearchKey | MAPI search key of a user associated with an item.
UserWell | User well associated with a user.

The Attendee object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Attendee object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Contact Object

The Contact object represents a single contact in the Contacts table and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AddressBusiness | Contact’s business street address.
AddressHome | Contact’s home street address.
AnniversaryItemId | Item identifier for the anniversary of an item in the RecurringEvents table.
Assistant | Assistant for an item.
BirthdayItemId | Item identifier for the birthday of an item in the RecurringEvents table.
CityBusiness | City for the contact’s business address.
CityHome | City for the contact’s home address.
Company | Company.
CountryBusiness | Country for the business address.
CountryHome | Country for the home address.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
CurrentAddress | Contact’s home address. Reserved for the Schedule+ user interface.
CurrentBusinessAddress | Business address.
CurrentBusinessPhone1 | Business phone.
CurrentBusinessPhone2 | Second business phone.
CurrentCardviewBusinessPhone1 | First business phone number in card view.
CurrentCardviewBusinessPhone2 | Second business phone number in card view.
CurrentCardviewHomeAddress | Home address in card view.
CurrentCardviewHomePhone1 | First home phone number in card view.
CurrentCardviewHomePhone2 | Second home phone number in card view.
CurrentPhone1 | First phone number.
CurrentPhone2 | Second phone number.
DefaultBusinessPhone1 | First default business phone type.
DefaultBusinessPhone2 | Second default business phone type.
Department | Department name.
ExportToWatch | Boolean value indicating that information about the contact should be exported to the Timex Data Link watch.
ExportToWatchPhones | Combination of flags indicating which of the contact’s telephone numbers should be exported to the Timex Data Link watch.
FirstName | First name for an item.
ItemId | Item identifier for an object.
JobTitle | Job title.
LastModified | Date and time at which the object was last modified.
LastName | Last name for an item.
Notes | Notes on an item.
Office | Office location.
PhoneAssistant | Phone number of the assistant.
PhoneBusiness | First business phone number.
PhoneBusiness2 | Second business phone number.
PhoneFax | Fax phone number.
PhoneHome | Home phone number.
PhoneHome2 | Second home phone number.
PhoneMobile | Mobile phone number.
PhonePager | Pager phone number.
Spouse | Name of the contact’s spouse.
StateBusiness | State or province of the business address.
StateHome | State or province of the home address.
User1 | User-defined string (only exposed in contacts).
User2 | User-defined string (only exposed in contacts).
User3 | User-defined string (only exposed in contacts).
User4 | User-defined string (only exposed in contacts).
ZipCodeBusiness | Postal or zip code of the contact’s business street address.
ZipCodeHome | Postal or zip code of the contact’s home street address.

The Contact object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Contact object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


DeletedItem Object

The DeletedItem object contains the path to a deleted object. All DeletedItem objects are listed in the DeletedItems table.

The DeletedItem object has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
ItemId | Item identifier for an object.
ItemIdPath | Multivalued property that contains the item identifiers in a path.
LastModified | Date and time at which the object was last modified.
TablePath | Multivalued property that contains the tables in a path.

The DeleteItem object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The DeletedItem object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Event Object

The Event object represents an event in an Events table and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmount | Time interval before the start of an event when an alarm will ring.
AlarmAmountAgain | Default amount of time to wait when the user sets the alarm snooze option.
AlarmAmountOriginal | Time interval before an event for which an alarm was set before the user set the alarm snooze option.
AlarmTypeUnit | Time unit to use for the alarm.
AlarmTypeUnitAgain | Time unit to use as the default in the Reminder dialog box.
AlarmTypeUnitOriginal | Time unit used for an alarm before the user set the alarm snooze option.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
EndDate | End date for an item.
IsRecurringInstance | Determines whether an item is an instance of a recurrence pattern.
ItemId | Item identifier for an object.
LastModified | Date and time at which an object was last modified.
Notify | Date and time for an alarm to ring.
Ring | Determines whether an alarm has been set to ring for an item.
RingAgain | Determines whether an alarm rings again.
RingOriginal | Determines whether there used to be an alarm on an item before the alarm rang.
StartDate | Start date for an item.
Text | Text value of an item.

The Event object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Event object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Project Object

The Project object represents a project and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
Goal | Goal for the project.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
Priority | Priority of an item.
Text | Text value of an item.

The Project object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Project object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


RecurringAppointment Object

The RecurringAppointment object represents recurring appointments described as a pattern and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
Attendees | Table of all the attendees for an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
CriticalChange | Date and time that a critical change occurred for an item.
DayInterval | Number of days between instances of a recurring appointment.
DayOfMonthMask | Combination of flags indicating which days of the month are valid for a recurrence pattern.
DayOfWeekMask | Combination of flags indicating which days of the week are valid for a recurrence pattern.
DayOfWeekStart | Day on which the week starts for a recurrence pattern.
EndRecurringDate | End date for a recurring appointment.
EndRecurringTime | End time for a recurring appointment.
Exceptions | Table of exceptions to recurring items.
FirstRecurringAlarmDate | Date of the first recurring appointment with an alarm.
HiddenPattern | Determines whether a recurring appointment should be shown to the user.
IsRecurringInstance | Determines whether an item is an instance of a recurrence pattern.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
MonthInterval | Interval between months for a recurrence pattern.
MonthOfYearMask | Combination of flags indicating which months of the year are valid for a recurrence pattern.
Notes | Notes on an item.
RecurringType | Type of recurrence pattern.
StartRecurringDate | Start date for a recurring appointment.
StartRecurringTime | Start time for a recurring appointment.
WeekInterval | Interval between weeks for a recurrence pattern.
YearInterval | Interval between years for a recurring appointment.

The RecurringAppointment object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The RecurringAppointment object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Attendee Object

An Attendee object represents a single attendee in the Attendees table, which is a property defined in an Appointment object.

The Attendee object has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AttendeeStatus | Current status of a meeting attendee.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
CriticalChange | Date and time that a critical change occurred for an item.
IsUserDistributionList | Boolean value indicating that the user associated with an item is a distribution list.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
LastReceived | Date and time of the last response that was received.
UserDisplay | MAPI display name of the user associated with an item.
UserEntryId | MAPI entry identifier for a user associated with an item.
UserSearchKey | MAPI search key of a user associated with an item.
UserWell | User well associated with a user.

The Attendee object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Attendee object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Exception Object

The Exceptions table stores exceptions to recurring appointments, events, and tasks. In addition to the Deleted and InstanceDate properties, the Exception object contains a copy of the properties of the recurring object at the time it was made an exception, but not the recurrence pattern properties.

The Exception object has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
Deleted | Boolean value indicating whether an item in the Exceptions table has been marked as deleted.
InstanceDate | Date on which an exception would have occurred if it had not been deleted.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.

The Exception object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Exception object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


RecurringEvent Object

The RecurringEvent object represents recurring events described as a pattern and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
DayInterval | Number of days between instances of a recurring event.
DayOfMonthMask | Combination of flags indicating which days of the month are valid for a recurrence pattern.
DayOfWeekMask | Combination of flags indicating which days of the week are valid for a recurrence pattern.
DayOfWeekStart | Day on which the week starts for a recurrence pattern.
EndRecurringDate | End date for a recurring event.
Exceptions | Table of exceptions to recurring items.
FirstRecurringAlarmDate | Date of the first recurring event with an alarm.
HiddenPattern | Determines whether a recurring event should be shown to the user.
IsRecurringInstance | Determines whether an item is an instance of a recurrence pattern.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
MonthInterval | Interval between months for a recurrence pattern.
MonthOfYearMask | Combination of flags indicating which months of the year are valid for a recurrence pattern.
RecurringType | Type of recurrence pattern.
StartRecurringDate | Start date for a recurring event.
WeekInterval | Interval between weeks for a recurrence pattern.
YearInterval | Interval between years for a recurring event.

The RecurringEvent object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The RecurringEvent object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


RecurringTask Object

The RecurringTask object represents recurring tasks described as a pattern and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
DayInterval | Number of days between instances of a recurring task.
DayOfMonthMask | Combination of flags indicating which days of the month are valid for a recurrence pattern.
DayOfWeekMask | Combination of flags indicating which days of the week are valid for a recurrence pattern.
DayOfWeekStart | Day on which the week starts for a recurrence pattern.
EndRecurringDate | End date for a recurring task.
Exceptions | Table of exceptions to recurring items.
FirstRecurringAlarmDate | Date of the first recurring task with an alarm.
HiddenPattern | Determines whether a recurring task should be shown to the user.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
MonthInterval | Interval between months for a recurrence pattern.
MonthOfYearMask | Combination of flags indicating which months of the year are valid for a recurrence pattern.
Notes | Notes on an item.
RecurringType | Type of recurrence pattern.
StartRecurringDate | Start date for a recurring task.
WeekInterval | Interval between weeks for a recurrence pattern.
YearInterval | Interval between years for a recurring task.

The RecurringTask object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The RecurringTask object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Role Object

The Role object describes a Role as defined by the Covey Seven Habits Tools module, and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
RoleColor | Color of the Role object.
RolePosition | Position of the Role object.
Text | Text value of an item.

The Role object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.


SingleAppointment Object

The SingleAppointment object represents an appointment that occurs only once, and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmount | Time interval before the start of an appointment when an alarm will ring.
AlarmAmountAgain | Default amount of time to wait when the user sets the alarm snooze option.
AlarmAmountOriginal | Time interval before an event for which an alarm was set before the user set the alarm snooze option.
AlarmTypeUnit | Time unit to use for the alarm.
AlarmTypeUnitAgain | Time unit to use as default in the Reminder dialog box.
AlarmTypeUnitOriginal | Time unit used for an alarm before the user set the alarm snooze option.
Attendees | Table of all the attendees for an item.
BusyType | Determines whether an item should make the user busy during that time.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
CriticalChange | Date and time that a critical change occurred for an item.
End | End date time for an item.
IsFromOther | Set of flags indicating that the item was created by another application.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
Notes | Contains notes on an item.
Notify | Date and time for an alarm to ring.
OwnerEntryId | MAPI entry identifier for the meeting owner of an item.
OwnerName | MAPI display name for the meeting owner of an item.
OwnerSearchKey | MAPI search key for the meeting owner of an item.
Ring | Determines whether an alarm has been set to ring for an item.
RingAgain | Preference used when ringing an alarm.
RingOriginal | Determines whether there used to be an alarm on an item before the alarm rang.
Start | Start date and time for an item.
TaskItemId | Item identifier for the task with which the item (usually appointment) is related.
Text | Text value of an item.
Where | Location of a meeting.

The SingleAppointment object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The SingleAppointment object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


SingleEvent Object

The SingleEvent object represents an event that occurs only once, and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmount | Time interval before the start of an event when an alarm will ring.
AlarmAmountAgain | Default amount of time to wait when the user sets the alarm snooze option.
AlarmAmountOriginal | Time interval before an event for which the alarm was set before the user set the alarm snooze option.
AlarmTypeUnit | Time unit to use for the alarm.
AlarmTypeUnitAgain | Time unit to use as default in the Reminder dialog box.
AlarmTypeUnitOriginal | Time unit used for an alarm before the user set the alarm snooze option.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
EndDate | Returns the end date for an item.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
Notify | Date and time for an alarm to ring.
Ring | Determines whether an alarm has been set to ring for an item.
RingAgain | Determines whether an alarm rings again.
RingOriginal | Determines whether there used to be an alarm on an item before the alarm rang.
StartDate | Start date for an item.
Text | Text value of an item.

The SingleEvent object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The SingleEvent object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


SingleTask Object

The SingleTask object represents a task that occurs only once, and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmount | Time interval before the start of a task when an alarm will ring.
AlarmAmountAgain | Default amount of time to wait when the user sets the alarm snooze option.
AlarmAmountOriginal | Time interval before a task for which an alarm was set before the user set the alarm snooze option.
AlarmTypeUnit | Time unit to use for the alarm.
AlarmTypeUnitAgain | Time unit to use as the default in the Reminder dialog box.
AlarmTypeUnitOriginal | Time unit used for an alarm before the user set the alarm snooze option.
AmountActualEffort | Amount of actual effort required to perform a task.
AmountEstimatedEffort | Amount of estimated effort required to perform a task.
AmountStartWork | Start date of the task.
BeforeEnd | Indicates that the alarm is set relative to the end rather than the start of an item.
BeforeEndOriginal | State of the BeforeEnd property before the user set the alarm snooze option.
Billing | Billing information.
CompletedDate | Date that an item was completed.
ContactItemId | Item identifier for an item in the Contacts table.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
EndDate | End date for an item.
Goal | Goal for the project.
IsFromOther | Set of flags indicating that the item was created by another application.
IsRecurringInstance | Determines whether an item is an instance of a recurrence pattern.
IsTaskAutoDone | Determines whether a task should appear as done automatically on its end date.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
Mileage | Mileage.
Notes | Notes on an item.
PercentCompleted | Percentage of the task that is currently complete.
Priority | Priority of an item.
ProjectItemId | Item identifier for an item in the Projects table to which the task is linked.
Ring | Determines whether an alarm has been set to ring for an item.
RingAgain | Preference used when ringing an alarm.
RingOriginal | Determines whether there used to be an alarm on an item before the alarm rang.
Roles | Table of Role items.
RoleColor | Color of the Role object.
RoleItemId | Item identifier for the Role object.
RolePosition | Position of the Role object.
StartDate | Start date for an item.
TaskOwner | Task place holder for the owner.
TaskRecipients | Task place holder for recipients.
TaskSource | Task place holder for the source.
Text | Text value of an item.
TypeUnitActualEffort | Type of unit for actual effort for an item.
TypeUnitEstimatedEffort | Type of unit for estimated effort for an item.
TypeUnitStartWork | Type of unit for amount of time before the end date to start work.

The SingleTask object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The SingleTask object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Task Object

The Task object represents a task and has the following properties.

Property | Description
AccessActual | Overrides the current access control list (ACL) level to mark the item private.
AccessEffective | ACL level granted to the user viewing an item.
AlarmAmount | Time interval before the start of a task when an alarm will ring.
AlarmAmountAgain | Default amount of time to wait when the user sets the alarm snooze option.
AlarmAmountOriginal | Time interval before a task for which an alarm was set before the user set the alarm snooze option.
AlarmTypeUnit | Time unit to use for the alarm.
AlarmTypeUnitAgain | Time unit to use as the default in the Reminder dialog box.
AlarmTypeUnitOriginal | Time unit used for an alarm before the user set the alarm snooze option.
AmountActualEffort | Amount of actual effort required to perform a task.
AmountEstimatedEffort | Amount of estimated effort required to perform a task.
AmountStartWork | Start date of the task.
BeforeEnd | Indicates that the alarm is set relative to the end rather than the start of an item.
BeforeEndOriginal | State of the BeforeEnd property before the user set the alarm snooze option.
Billing | Billing information.
CompletedDate | Date that an item was completed.
ContactItemId | Item identifier for an item in the Contacts table.
ChangeNumber | Change number for the schedule.
Created | Date and time at which an object was created.
CreatorEntryId | MAPI entry identifier for an item's creator.
CreatorName | MAPI display name of an item's creator.
CreatorSearchKey | MAPI search key for an item's creator.
EndDate | End date for an item.
Goal | Goal for the project.
IsFromOther | Set of flags indicating that the item was created by another application.
IsRecurringInstance | Determines whether an item is an instance of a recurrence pattern.
IsTaskAutoDone | Determines whether a task should appear as done automatically on its end date.
ItemId | Item identifier for an object.
LastModified | Date and time at which the object was last modified.
Mileage | Mileage.
Notes | Notes on an item.
PercentCompleted | Percentage of the task that is currently complete.
Priority | Priority of an item.
ProjectItemId | Item identifier for an item in the Projects table to which the task is linked.
Ring | Determines whether an alarm has been set to ring for an item.
RingAgain | Preference used when ringing an alarm.
RingOriginal | Determines whether there used to be an alarm on an item before the alarm rang.
Roles | Table of Role items.
RoleColor | Color of the Role object.
RoleItemId | Item identifier for the Role object.
RolePosition | Position of the Role object.
StartDate | Start date for an item.
TaskOwner | Task placeholder for the owner.
TaskRecipients | Task placeholder for recipients.
TaskSource | Task placeholder for the source.
Text | Text value of an item.
TypeUnitActualEffort | Type of unit for actual effort for an item.
TypeUnitEstimatedEffort | Type of unit for estimated effort for an item.
TypeUnitStartWork | Type of unit for amount of time before the end date to start work.

The Task object has the following data members.

Data Member | Description
Application | Returns an Application object.
Parent | Returns to an object’s parent.
Properties | Returns the number of properties defined for an object.

The Task object has the following methods.

Method | Description
DeleteProperties | Deletes a specified property.
Flush | Removes properties that have been changed.
GetProperties | Gets the value of one or more specified properties.
GetProperty | Gets the value of a specified property for Visual Basic version 3.0.
SetProperties | Sets the value of one or more properties.


Properties

This section contains an alphabetic listing of all Schedule+ Automation properties, their data type, and the objects to which they apply. These properties can be accessed either as objects or directly by way of their data type, which is the data type whose value is returned by the Value method.


AccessActual

The AccessActual property overrides the current access control list (ACL) level to mark the item private.

Applies To

All Item objects

Data Type

Long

Access

Read/write

Remarks

The AccessActual property has the following values.

Value | Description
0 | No access
1 | Minimal read
2 | Read
3 | Create
4 | Write
5 | Owner

Only the owner can write to the AccessActual property, which specifies the minimum ACL level needed by another user to see normal properties of an object. For example, the following sample code shows how you can mark individual appointments as private by setting this property to the value sacOwner.

Sub MakeTaskPrivate()
Dim objApp As Object
Dim objSchedule As Object
Dim objTable As Object
Dim objTask As Object

Set objApp = CreateObject("SchedulePlus.Application")
objApp.Logon
Set objSchedule = objApp.ScheduleLogged
Set objTable = objSchedule.SingleTasks
Set objTask = objTable.Item

Debug.Print objTask.Text

' Make task private by setting the AccessActual property to saclOwner
' To make the task public, set AccessActual to saclNone
'
' Also works for any object that you can make private through the Schedule+ UI,
' i.e. appointments, events, projects, contacts
'
objTask.AccessActual = saclOwner

Set objTask = Nothing
Set objTable = Nothing
Set objSchedule = Nothing

objApp.Logoff
Set objApp = Nothing
End Sub

See Also

AccessDefault
AccessLists
AccessControls


AccessControls

The AccessControls property returns a table of Access objects.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

Remarks

Only the owner of the schedule file can read or modify the AccessControls table and the properties therein.

See Also

AccessDefault
AccessLists
AccessControls


AccessDefault

The AccessDefault property identifies the default access control list (ACL) level for objects.

Applies To

AccessControls table

Data Type

Long

Access

Read/write

Remarks

Only the owner of the schedule file can read or modify the AccessControls table. This property identifies the default ACL level for items in the table. You can override this default by specifying the ACLs on a per-table basis. The default should always be present.

The AccessDefault property has the following values.

Value | Description
0 | No access
1 | Minimal read
2 | Read
3 | Create
4 | Write
5 | Owner

See Also

AccessActual
AccessLists
AccessControls


AccessEffective

The AccessEffective property identifies the access control list (ACL) level that has been granted to the user viewing an item.

Applies To

All Item objects

Data Type

Long

Access

Read-only

Remarks

The AccessEffective property has the following values.

Value | Description
0 | No access
1 | Minimal Read
2 | Read
3 | Create
4 | Write
5 | Owner

See Also

AccessLists
AccessControls


AccessLists

The AccessLists property is a multivalued property that contains access levels of a table.

Applies To

AccessControls table

Data Type

Object (Table)

Access

Read/write

Remarks

Only the owner of the schedule file can read this table. The values in the AccessLists property have a one-to-one correspondence with values in the AccessControls property, which lists the access level assigned to each table specified by the AccessLists property. For more information on how to use the AccessLists property, see Overview.

See Also

AccessControls
AccessEffective


AddressBusiness

The AddressBusiness property identifies a contact’s business street address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

AddressHome
ZipCodeBusiness


AddressHome

The AddressHome property identifies a contact’s home street address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

AddressBusiness
ZipCodeHome


AlarmAmount

The AlarmAmount property specifies the time interval before the start of an appointment, event, or task when an alarm will ring.

Applies To

Appointment, Event, RecurringAppointment, RecurringEvent, RecurringTask, and Task objects

Data Type

Long

Access

Read/write

Remarks

The AlarmAmount property is used in combination with the AlarmTypeUnit property to specify the time interval before the start or end of the object when the alarm will occur.

See Also

AlarmAmountAgain
AlarmAmountDefault
AlarmAmountOriginal
AlarmTypeUnit
Notify
Ring


AlarmAmountAgain

The AlarmAmountAgain property specifies the default amount of time to wait when the user sets the snooze option.

Applies To

Appointment, Event, RecurringAppointment, RecurringEvent, RecurringTask, and Task objects

Data Type

Long

Access

Read/write

Remarks

The AlarmAmountAgain property is used in combination with the AlarmTypeUnit property to specify the default amount of time to wait when the user sets the snooze option. It causes an alarm to ring again after the specified time interval. Because users set this value in the Schedule+ user interface, most applications will use this property only to set a default value that appears in the appointment, event, and task Reminder dialog boxes.

See Also

AlarmAmount
AlarmAmountDefault
AlarmAmountOriginal
AlarmTypeUnit
RingAgain


AlarmAmountDefault

The AlarmAmountDefault property specifies the default time interval before the start of an appointment when an alarm will ring.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The unit of time for this default is set by the AlarmTypeUnitDefault property.

See Also

AlarmAmount
AlarmAmountDefaultTask
AlarmTypeUnitDefault


AlarmAmountDefaultTask

The AlarmAmountDefaultTask property specifies the default time interval before the start or end of a task when an alarm will ring.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The BeforeEnd property setting on the Task object determines whether the default time interval specified is before the start or end of a task.

Because this property is set by the user in the Schedule+ Options dialog box, applications read the value of this property, but do not write a value to it. For more information, see the Schedule+ Help.

See Also

AlarmAmount
AlarmAmountDefault
AlarmAmountOriginal
AlarmTypeUnitDefaultTask
BeforeEnd
Task


AlarmAmountOriginal

The AlarmAmountOriginal property specifies the time interval before an appointment, event, or task for which an alarm was set before the user set the snooze option.

Applies To

Appointment, Event, RecurringAppointment, RecurringEvent, RecurringTask, and Task objects

Data Type

Long

Access

Read/write

Remarks

To illustrate the use of the AlarmAmountOriginal property, consider an Appointment object that has recently been created. If AlarmAmountDefault is one hour, then AlarmAmount and AlarmAmountOriginal will both be one hour. If the user sets the snooze option for the alarm to 15 minutes, then AlarmAmount will be reset to 15 minutes, but AlarmAmountOriginal will remain at one hour.

See Also

AlarmAmount
AlarmAmountAgain
AlarmAmountDefault
AlarmTypeUnitOriginal


AlarmsEnabled

The AlarmsEnabled property returns a Boolean value that indicates whether the alarms processing feature has been enabled.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

If the AlarmsEnabled property is set to True, meeting reminders are displayed. If this property is set to False, the user will never see alarm notification. This does not affect daily task reminders.

See Also

AlarmsToRing


AlarmsToRing

The AlarmsToRing property returns a table of Alarm objects.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

Remarks

Only the owner of the schedule file can read and write to the AlarmsToRing property. This table can be used to determine when the next alarm will ring. To do this, examine the Notify property of all the Alarm objects contained in the table.

See Also

AlarmsEnabled
Notify


AlarmTypeUnit

The AlarmTypeUnit property specifies the time unit to use for the alarm.

Applies To

Appointment, Event, RecurringAppointment, RecurringEvent, RecurringTask, and Task objects

Data Type

Long

Access

Read/write

Remarks

The AlarmTypeUnit property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

AlarmAmount
AlarmTypeUnitAgain
AlarmTypeUnitDefault


AlarmTypeUnitAgain

The AlarmTypeUnitAgain property specifies the default unit for the alarm amount in the Reminder dialog box.

Applies To

Appointment, Event, RecurringAppointment, RecurringEvent, RecurringTask, and Task objects

Data Type

Long

Access

Read/write

Remarks

The AlarmTypeUnitAgain property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

AlarmAmountAgain
AlarmTypeUnit


AlarmTypeUnitDefault

The AlarmTypeUnitDefault property specifies the type of unit for the default alarm for appointments and events.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The AlarmTypeUnitDefault property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

AlarmAmountDefault
AlarmTypeUnit


AlarmTypeUnitDefaultTask

The AlarmTypeUnitDefaultTask property specifies the type of unit for the default alarm for tasks.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The AlarmTypeUnitDefaultTask property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

AlarmAmountDefaultTask
AlarmTypeUnit
AlarmTypeUnitDefault


AlarmTypeUnitOriginal

The AlarmTypeUnitOriginal property specifies the time unit defined for an alarm before the user set the snooze option.

Applies To

Appointment, Event, RecurringAppointment, RecurringEvent, RecurringTask, and Task objects

Data Type

Long

Access

Read/write

Remarks

The AlarmTypeUnitOriginal property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

AlarmAmountOriginal
AlarmTypeUnit


AmountActualEffort

The AmountActualEffort property specifies the actual amount of effort required to perform a task.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

The number to which the AmountActualEffort property is set has meaning only to the application that sets it. Schedule+ does not interpret or process the value stored in this property. The unit of measure for this value is also application-specific.

See Also

AmountEstimatedEffort
TypeUnitActualEffort


AmountEstimatedEffort

The AmountEstimatedEffort property specifies the estimated amount of effort required to perform a task.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

The number to which the AmountEstimatedEffort property is set has meaning only to the application that sets it. Schedule+ does not interpret or process the value stored in this property. The unit of measure for this value is also application-specific.

See Also

AmountActualEffort
TypeUnitEstimatedEffort


AmountStartWork

The AmountStartWork property specifies the amount of time before the end date to start work.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

The AmountStartWork property works in conjunction with the TypeUnitStartWork property to determine the start date of the task.

See Also

TypeUnitStartWork


AnniversaryItemId

The AnniversaryItemId property returns an identifier for the anniversary of a contact in the RecurringEvents table.

Applies To

Contact object

Data Type

String

Access

Read/write

Remarks

The AnniversaryItemId property is used to link a Contact object to a RecurringEvent object. In this case, the recurring event is the anniversary of the contact. This is the ItemId property in a RecurringEvents table.

See Also

BirthdayItemId


Appointments

The Appointments property returns a table of single appointments merged with instances of recurring appointments.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

Remarks

The merged instances of the recurring appointment appear as normal appointments in the Appointments table. For example, the properties specific to recurring appointments (recurring pattern properties) are not available. The IsRecurringInstance property can be used to determine whether a given item in this table is an instance.

Also note that for the Appointments table, some operations, such as retrieving the number of rows, are meaningless because of the possible existence of open-ended appointments.

See Also

IsRecurringInstance


Assistant

The Assistant property specifies a contact’s assistant.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact


Attendees

The Attendees property returns a table of all attendees for an appointment.

Applies To

Attendee object

Data Type

Object (Table)

Access

Read/write

Remarks

For more information on creating and using Table objects, see Overview and Programming Tasks.

See Also

Attendee


AttendeeStatus

The AttendeeStatus property returns the current status of a meeting attendee.

Applies To

Attendee object

Data Type

Long

Access

Read/write

Remarks

The AttendeeStatus property value should be set by Schedule+ and can have one of the following values.

Value | Description
0 | User has not been notified of the meeting.
1 | Mail has been sent to the user, but a response has not been received.
2 | User has responded to confirm attendance.
3 | User has responded to decline attendance.
4 | User has responded and is undecided about whether to attend.
5 | All users have responded to indicate that they will attend.
6 | All users have responded and at least one has confirmed attendance.

Values 0 through 4 are used for the AttendeeStatus property of Attendee objects. Values 5 and 6 are used for the AttendeeStatus property of Appointment objects.

See Also

Attendee


AutoAlarms

The AutoAlarms property returns a Boolean value that determines whether an alarm should be set for new appointments and events.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

The AutoAlarms property is usually set by users through the Schedule+ user interface. If this property is set to True, all new Appointment and Event objects will automatically have their AlarmAmount property set to the value of the AlarmAmountDefault property.

See Also

AlarmAmount
AlarmAmountDefault
AutoAlarmsTask


AutoAlarmsTask

The AutoAlarmsTask property returns a Boolean value that indicates whether an alarm should be set for new tasks.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

The AutoAlarmsTask property is usually set by users through the Schedule+ user interface. If this property is set to True, all new Task objects will automatically have their AlarmAmount property set to the value of the AlarmAmountDefaultTask property.

See Also

AlarmAmount
AlarmAmountDefaultTask
AutoAlarmsTask


AutoProcessMeetingCancellations

The AutoProcessMeetingCancellations property returns a Boolean value that indicates whether Schedule+ should automatically process incoming meeting cancellations for the user.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

Only the owner can write to the AutoProcessMeetingCancellations property — everyone else has normal access. Schedule+ must be running in group-enabled mode.

If this property is set to True and Schedule+ receives a meeting cancellation, the meeting will automatically be cancelled and removed from the user’s schedule.

See Also

AutoProcessMeetingRequests


AutoProcessMeetingRequests

The AutoProcessMeetingRequests property returns a Boolean value that indicates whether Schedule+ should automatically process incoming meeting requests for the user.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

Only the owner can write to the AutoProcessMeetingRequests property — everyone else has normal access. Schedule+ must be running in group-enabled mode.

If this property is set to True and Schedule+ receives a meeting request, the meeting is automatically booked onto the user’s schedule and a confirmation response is sent to the meeting request sender. If a conflicting meeting is already booked onto the user’s schedule when the request is received, the meeting is not booked and the request remains in the user’s Inbox.

See Also

AutoProcessMeetingCancellations


BeforeEnd

The BeforeEnd property returns a Boolean value that indicates if an alarm is set relative to the end rather than the start of an item.

Applies To

Task object

Data Type

Boolean

Access

Read/write

Remarks

Typically, the BeforeEnd property is set to False. The amount of time relative to the end of a task is set in the AlarmTypeUnit property.

See Also

AlarmTypeUnit


BeforeEndDefaultTask

The BeforeEndDefaultTask property returns a Boolean value that indicates whether an alarm is set relative to the end rather than the start of a new task by default.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

Typically, the BeforeEndDefaultTask property is set to False. The amount of time relative to the end of an item is set in the AlarmTypeUnit property.

See Also

AlarmTypeUnit
BeforeEnd


BeforeEndOriginal

The BeforeEndOriginal property returns a Boolean value that indicates the value of the BeforeEnd property before the user set the snooze option for an alarm.

Applies To

Task object

Data Type

Boolean

Access

Read/write

Remarks

To illustrate the use of the BeforeEndOriginal property, consider a Task object that has recently been created. If BeforeEndDefaultTask is one hour, then BeforeEnd and BeforeEndOriginal will both be one hour. If the user sets the snooze option for the alarm to 15 minutes, then BeforeEnd will be reset to 15 minutes, but BeforeEndOriginal will remain at one hour.

See Also

BeforeEnd


Billing

The Billing property lists billing information for a task.

Applies To

Task object

Data Type

String

Access

Read/write

Remarks

The format of the Billing property is application-specific and Schedule+ does not interpret or process it. Typically, applications use this property to store billing infomation for a task, such as a client’s billing address, purchase order number, how much the task cost, hourly billing rate, invoice number, or any other billing information.

See Also

Task


BirthdayItemId

The BirthdayItemId property returns an identifier for the birthday of a contact in the RecurringEvents table.

Applies To

Contact object

Data Type

String

Access

Read/write

Remarks

The BirthdayItemId property is used to link a Contact object to a RecurringEvent object. In this case, the recurring event is the birthday of the contact. This is the ItemId property in a RecurringEvents table.

See Also

AnniversaryItemId
ItemId
RecurringEvent


BossWantsCopy

The BossWantsCopy property returns a Boolean value indicating whether the owner, in addition to any delegates, would like to receive a copy of the meeting mail.

Applies To

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

Only the owner can write to the BossWantsCopy property — everyone else has read-only access. For more information, see the Schedule+ Help.

See Also

Schedule


BusyType

The BusyType property determines whether an item should make the user busy during that time.

Applies To

Appointment object

Data Type

Long

Access

Read/write

Remarks

Applications should set the BusyType property to 0 to make an appointment tentative in the Schedule+ user interface. The property should be set to 1 if the appointment is to be firm in the Schedule+ user interface. If this property is not set, the appointment is displayed as tentative.

The following sample code makes an appointment tentative by setting the BusyType property to btfNone:

Sub MakeApptTentative()
Dim objApp As Object
Dim objSchedule As Object
Dim objTable As Object
Dim objAppt As Object

Set objApp = CreateObject("SchedulePlus.Application")
objApp.Logon
Set objSchedule = objApp.ScheduleLogged
Set objTable = objSchedule.SingleAppointments
Set objAppt = objTable.Item

Debug.Print objAppt.Text

' Make appt tentative by setting the BusyType property to btfNone.
' To change the appt so it is not tentative, set BusyType to btfNormalBusy.
objAppt.BusyType = btfNone

Set objAppt = Nothing
Set objTable = Nothing
Set objSchedule = Nothing

objApp.Logoff
Set objApp = Nothing
End Sub

See Also

Appointment


ChangeNumber

The ChangeNumber property returns the change number for the schedule.

Applies To

All Item objects

Data Type

Double

Access

Read-only

Remarks

The ChangeNumber property allows Schedule+ to synchronize local and server schedules on a per-property basis. If a change is made to any object in the schedule file, this property is increased by one on that object and on all objects that are parents of the object. For example, if the current change number of an Attendee object is 10 and a change is made to that object, the new change number of the Attendee object will be 11, the change number of the Appointment object that contains the Attendee object will be increased by one, and the change number of the Schedule object will be increased by one. In other words, change numbers propagate upward through the object hierarchy.

This property is useful in situations where multiple applications or users are using different copies of the same schedule file. For example, if a user takes a copy of a schedule on a laptop computer, an application can read the ChangeNumber property upon reattaching the laptop computer to the network to see whether information in the network server copy of the schedule has changed. If objects have changed, the application can perform custom operations, such as showing the user a list of all objects in the server-based copy of the schedule that changed while the user was on the road.

Change numbers are schedule-specific, which means that a different set of change numbers are maintained for each schedule. Therefore, applications should not compare change numbers from different schedules and should always check the value of the ScheduleId property of the two files being synchronized to ensure that the same schedule is being used.

See Also

DeletedItems
LastModified
LastSynchronized
ScheduleId


CityBusiness

The CityBusiness property specifies the city for the contact’s business address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

CityHome


CityHome

The CityHome property specifies the city for the contact’s home address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

CityBusiness


Company

The Company property specifies the company or organization with which the contact is associated.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact


CompletedDate

The CompletedDate property specifies the date when a task was completed.

Applies To

Task object

Data Type

Date/Time

Access

Read/write

Remarks

If a value is set to the CompletedDate property, Schedule+ places a check mark next to the task and draws a line through it to denote that the task has been completed. Also, the PercentCompleted property is set to 100.

See Also

PercentCompleted


ContactItemId

The ContactItemId property returns an item identifier for an item in the Contacts table.

Applies To

Task object

Data Type

String

Access

Read/write

Remarks

The ContactItemId property is used to link a contact to a task. The ContactItemId is an ItemId from the Contacts table.

SeeAlso

Contacts
ItemId


Contacts

The Contacts property returns a table of contacts.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

ContactItemId


CountryBusiness

The CountryBusiness property specifies the country for the business address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

CountryHome


CountryHome

The CountryHome property specifies the country for the home address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

CountryBusiness


Created

The Created property returns the date and time at which an object was created.

Applies To

All objects

Data Type

Date/Time

Access

Read-only

Remarks

The Created property is set by Schedule+.

See Also

Application


CreatorEntryId

The CreatorEntryId property returns the mail entry identifier for the creator of an item.

Applies To

All Item objects

Data Type

String

Access

Read/write

Remarks

The CreatorEntryId property is set on an item only if another user creates the item; it is not available to an item created by the owner. The value is determined by the underlying mail transport system.

Applications should use this property to verify that a user created a particular item, or to send mail to the creator of an item. The format of the data in this property is usually a mail address that is understood by the mail system. For example, this property might have a value of SMTP:brianw@microsoft.com. However, some mail transports may set this property to an uninterpretable string.

The Schedule+ security system uses this property to retrieve information about an item’s creator.

See Also

CreatorName
CreatorSearchKey


CreatorName

The CreatorName property returns the display name of the item’s creator.

Applies To

All Item objects

Data Type

String

Access

Read/write

Remarks

The CreatorName property is set on an item only if another user creates the item; it is not available to an item created by the owner.

See Also

CreatorEntryId
CreatorSearchKey


CreatorSearchKey

The CreatorSearchKey property returns an identity stamp that uniquely identifies an item’s creator.

Applies To

All Item objects

Data Type

String

Access

Read/write

Remarks

The CreatorSearchKey property is set on an item only if another user creates the item; it is not available to an item created by the owner. The value is determined by the underlying mail transport system. Applications should use this property to verify that a user created a particular item. The format of the data in the property is not interpretable by most applications and should be treated like a handle.

See Also

CreatorEntryId
CreatorName
OwnerSearchKey


CriticalChange

The CriticalChange property returns the date and time at which a critical change occurred for an item.

Applies To

Appointment and Attendee objects

Data Type

Date/Time

Access

Read/write

Remarks

Applications can use the CriticalChange property to determine if items are the most current. For example, suppose a meeting request is sent to a number of users, and then later, a revised version of the meeting request is sent that includes a critical change such as a new meeting location. Before the revised version is sent, a user responds to the original version of the meeting request. This property enables the application to determine that the user’s response to the original meeting request is out of date.

This property is used only with meeting requests. Normally, applications will use this property in combination with the ChangeNumber property to determine if critical changes have occurred and when they occurred.

See Also

ChangeNumber


CurrentAddress

The CurrentAddress property returns the contact’s address.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentAddress property is used internally by the Schedule+ user interface.

See Also

CurrentBusinessAddress


CurrentBusinessAddress

The CurrentBusinessAddress property returns the contact’s business address.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentBusinessAddress property is used internally by the Schedule+ user interface.

See Also

CurrentAddress


CurrentBusinessPhone1

The CurrentBusinessPhone1 property returns the contact’s business phone number.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentBusinessPhone1 property is used internally by the Schedule+ user interface.

See Also

CurrentBusinessPhone2


CurrentBusinessPhone2

The CurrentBusinessPhone2 property returns the contact’s second business phone number.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentBusinessPhone2 property is used internally by the Schedule+ user interface.

See Also

CurrentBusinessPhone1


CurrentCardviewBusinessPhone1

The CurrentCardviewBusinessPhone1 property returns the contact’s business phone number in card view.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentCardviewBusinessPhone1 property is used internally by the Schedule+ user interface.

See Also

CurrentCardviewBusinessPhone2


CurrentCardviewBusinessPhone2

The CurrentCardviewBusinessPhone2 property returns the contact’s second business phone number in card view.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentCardviewBusinessPhone2 property is used internally by the Schedule+ user interface.

See Also

CurrentCardviewBusinessPhone1


CurrentCardviewHomeAddress

The CurrentCardviewHomeAddress property returns the contact’s address in card view.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentCardviewHomeAddress property is used internally by the Schedule+ user interface.

See Also

CurrentAddress


CurrentCardviewHomePhone1

The CurrentCardviewHomePhone1 property returns the contact’s phone number in card view.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentCardviewHomePhone1 property is used internally by the Schedule+ user interface.

See Also

CurrentCardviewHomePhone2
CurrentPhone1


CurrentCardviewHomePhone2

The CurrentCardviewHomePhone2 property returns the contact’s second phone number in card view.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentCardviewHomePhone2 property is used internally by the Schedule+ user interface.

See Also

CurrentCardviewHomePhone1
CurrentPhone2


CurrentPhone1

The CurrentPhone1 property returns the contact’s phone number.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentPhone1 property is used internally by the Schedule+ user interface.

See Also

CurrentPhone2


CurrentPhone2

The CurrentPhone2 property returns the contact’s second phone number.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The CurrentPhone2 property is used internally by the Schedule+ user interface.

See Also

CurrentPhone1


DailyAlarm

The DailyAlarm property returns a Boolean value that determines whether daily reminders are displayed.

Applies to

Schedule object

Data Type

Boolean

Access

Read/write

Remarks

The DailyAlarm property controls the Daily Reminder dialog box that appears every day if there is an active task for the day. This is a user option that can also be changed using the Options dialog box.

Note This option should not be modified unless it is important to do so.

See Also

LastDailyAlarm


DayEndsAt

The DayEndsAt property returns the number of half hours from midnight for the end of day.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DayEndsAt property is usually set by the user in the Options dialog box. For more information, see the Schedule+ Help.

See Also

DayStartsAt


DayInterval

The DayInterval property returns the number of days between instances of a recurring item.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

The DayInterval property is valid only if the RecurringType property is set to Daily. When creating a daily recurring appointment or task, set this value to the number of days that should occur between instances of the item. For example, to create an appointment that recurs every three days, set this property to 3.

See Also

RecurringType


DayOfMonthMask

The DayOfMonthMask property returns a combination of flags indicating which days of the month are valid for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

The DayOfMonthMask property specifies the days of the month for a recurring item. The flags are set in a 32-bit integer where the first bit is bit 0 and the last bit is bit 31.

For example, to set a recurring monthly meeting to occur on the first and fifteenth days of the month, set bits 0 and 14. Bit 31 is ignored because no month has 32 days.

This property must be used with the MonthInterval property to define a recurring monthly appointment, event, or task. This property can also be used for yearly recurrences that specify instances in terms of months.

See Also

MonthInterval
RecurringType


DayOfWeekMask

The DayOfWeekMask property returns a combination of flags that indicates which days of the week are valid for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

The DayOfWeekMask property can have one of the following values.

Value | Description
0 | Sunday (default)
1 | Monday
2 | Tuesday
3 | Wednesday
4 | Thursday
5 | Friday
6 | Saturday

For example, to define an appointment that occurs every week on Monday and Wednesday, set bits 1 and 3 of this property. Bits 7 through 31 are ignored.

This property can also be used for yearly recurrences that specify instances in terms of months.

See Also

DayOfWeekStart
RecurringType


DayOfWeekStart

The DayOfWeekStart property returns the day on which the week starts for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

The DayOfWeekStart property is used by Schedule+ when a weekly recurring item, such as a weekly appointment, is created.

This property can have one of the following values.

Value | Description
0 | Sunday (default)
1 | Monday
2 | Tuesday
3 | Wednesday
4 | Thursday
5 | Friday
6 | Saturday

See Also

DayOfWeekMask
RecurringType


DayStartsAt

The DayStartsAt property returns the number of half hours from midnight for the start of day.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DayStartsAt property is usually set by the user in the Options dialog box. For more information, see the Schedule+ Help.

See Also

DayEndsAt


DefaultBusinessPhone1

The DefaultBusinessPhone1 property returns the first default business phone type.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultBusinessPhone1 property is used internally by the Schedule+ user interface to display the first default business phone number.

See Also

DefaultBusinessPhone2


DefaultBusinessPhone2

The DefaultBusinessPhone2 property returns the second default business phone type.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultBusinessPhone2 property is used internally by the Schedule+ user interface to display the second default business phone number.

See Also

DefaultBusinessPhone1


DefaultEstimatedEffortAmount

The DefaultEstimatedEffortAmount property returns the default estimated effort for a task.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultEstimatedEffortAmount property and the DefaultEstimatedEffortTypeUnit property are both required to specify the default estimated effort.

See Also

DefaultEstimatedEffortTypeUnit


DefaultEstimatedEffortTypeUnit

The DefaultEstimatedEffortTypeUnit property returns the type of unit for the default estimated effort.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultEstimatedEffortTypeUnit property and the DefaultEstimatedEffortAmount property are both required to specify the default estimated effort.

The DefaultEstimatedEffortTypeUnit property has the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

DefaultEstimatedEffortAmount


DefaultHomePhone1

The DefaultHomePhone1 property returns the first default home phone type.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultHomePhone1 property is used internally by the Schedule+ user interface to display the first default home phone number.

See Also

DefaultHomePhone2


DefaultHomePhone2

The DefaultHomePhone2 property returns the second default home phone type.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultHomePhone2 property is used internally by the Schedule+ user interface to display the second default home phone number.

See Also

DefaultHomePhone1


DefaultProjectPriority

The DefaultProjectPriority property returns the priority level assigned to new projects.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

A Schedule+ priority is one of two types: 0-9 or A0-Z9. In each case, the priority is stored in a loword specifying the lower part, and a hiword specifying the upper part. Both parts are stored as ASCII characters.

This property is set by the user in the Schedule+ Options dialog box. For more information, see the Schedule+ Help.

See Also

DefaultTaskPriority


DefaultTaskDurationAmount

The DefaultTaskDurationAmount property returns the default duration of a task.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultTaskDurationAmount is set by the user in the Schedule+ Options dialog box. For more information, see the Schedule+ Help.

See Also

DefaultTaskDurationTypeUnit


DefaultTaskDurationTypeUnit

The DefaultTaskDurationTypeUnit property returns the unit of time for the default duration of a task.

Applies to

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultTaskDurationTypeUnit property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

DefaultTaskDurationAmount


DefaultTaskPriority

The DefaultTaskPriority property returns the default priority assigned to new tasks.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DefaultTaskPriority property is set by the user in the Schedule+ Options dialog box. For more information, see the Schedule+ Help.

See Also

DefaultProjectPriority


DelegateEntryId

The DelegateEntryId property returns a list of mail entry identifiers for delegates.

Applies To

Schedule object

Data Type

String (multivalued)

Access

Read/write

Remarks

Only the owner can write to the DelegateEntryId property — everyone else has read-only access. This property is used to assign delegates for the schedule’s owner. Because the property is multivalued, you can set it to any number of delegate entry identifiers. When a meeting request is received, each delegate in this property will receive meeting requests on behalf of the schedule’s owner.

This property must reflect the delegates specified in the AccessControls table. The values of this property should only be changed by the Schedule+ user interface.

See Also

DelegateName


DelegateName

The DelegateName property returns the display names of delegates listed in the DelegateEntryId property.

Applies To

Schedule object

Data Type

String (multivalued)

Access

Read/write

Remarks

Only the owner can write to the DelegateName property — everyone else has read-only access. Use this multivalued property to set the display names of delegates that have been set in the DelegateEntryId property. The order of the display names must correspond to the order of the entry identifiers in the DelegateEntryId property.

This property must reflect the delegates specified in the AccessControls table. The values of this property should only be changed by the Schedule+ user interface.

See Also

DelegateEntryId


Deleted

The Deleted property returns a Boolean value that indicates whether an exception in the Exceptions table has been marked as deleted.

Applies To

Exception object

Data Type

Boolean

Access

Read/write

Remarks

The Deleted property applies only to recurring items that have been deleted. A deleted instance is an Exception item in the Exceptions table that has its Deleted property set to True.

For example, if a user creates a weekly recurring appointment, but during the third week of the appointment the user is scheduled to be on vacation, the user deletes the third instance of the appointment. Schedule+ places the deleted instance in the Exceptions table with its Deleted property set to True.

Applications can use this property to scan the Exceptions table for all instances of recurring appointments that users have deleted.

See Also

Exception
Exceptions Table


DeleteDataAfter

The DeleteDataAfter property specifies the number of months of data to keep before prompting the user for archiving.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The DeleteDataAfter property is set by users in the Schedule+ Options dialog box. For more information, see the Schedule+ Help.

See Also

Schedule


DeletedItems

The DeletedItems property returns a table containing a list of all deleted items in the schedule file.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

Remarks

Only the owner of the schedule file can read the DeletedItems table. The DeletedItems property can be used with the ChangeNumber property to synchronize different copies of a schedule file. For example, an application can determine which items in one copy of a schedule have been deleted, and then determine whether these items have also been deleted from another copy of the schedule.

Items in the DeletedItems table are permanently removed from the schedule and cannot be recovered.

See Also

ChangeNumber
Tables


Department

The Department property returns the department to which a contact belongs.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact


DisallowAppointmentOverlap

The DisallowAppointmentOverlap property determines whether to allow overlapping appointments to be scheduled.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

Only the owner can write to the DisallowAppointmentOverlap property.

See Also

DisallowRecurringItems


DisallowRecurringItems

The DisallowRecurringItems property determines whether to allow recurring items to be scheduled.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

Only the owner can write to DisallowRecurringItems property.

See Also

DisallowAppointmentOverlap


End

The End property returns the end date and time for an item.

Applies To

Appointment object

Data Type

Date/Time

Access

Read/write

See Also

EndRecurringDate
EndRecurringTime


EndDate

The EndDate property returns the end date for an item.

Applies To

Event object

Data Type

Date

Access

Read/write

See Also

EndRecurringDate
EndRecurringTime


EndRecurringDate

The EndRecurringDate property returns the end date for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Date

Access

Read/write

Remarks

The EndRecurringDate property does not have to be set if the recurrence pattern is indefinite.

SeeAlso

EndRecurringTime
StartRecurringDate


EndRecurringTime

The EndRecurringTime property returns the end time for a recurrence pattern.

Applies To

RecurringAppointment objects

Data Type

Time

Access

Read/write

Remarks

The StartRecurringTime and EndRecurringTime properties determine the block of time for the recurring appointment on the days specified by the recurrence pattern.

See Also

EndRecurringDate
StartRecurringTime


Events

The Events property returns a table of single events merged with instances of recurring events.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

Remarks

Do not attempt to access all items of the Events table; this can result in an endless loop. Use the SetRange method to restrict the date range before using this table.

See Also

RecurringEvents
SetRange
SingleEvents


Exceptions

The Exceptions property returns a table of exceptions to recurring items.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Object (Table)

Access

Read/write

See Also

RecurringAppointments
RecurringEvents
RecurringTasks


ExportToWatch

The ExportToWatch property returns a Boolean value indicating that information about the contact should be exported to the Timex Data Link watch.

Applies To

Contact object

Data Type

Boolean

Access

Read/write

Remarks

The ExportToWatch property is reserved for internal use by the Schedule+ user interface.

See Also

Contact
Contacts


ExportToWatchPhones

The ExportToWatchPhones property returns a combination of flags indicating which of the contact’s telephone numbers should be exported to the Timex Data Link watch.

Applies To

Contact object

Data Type

Long

Access

Read/write

Remarks

The ExportToWatchPhones property is reserved for internal use by the Schedule+ user interface. It can have one or more of the following flags set.

Value | Description
1 | Business phone 1
2 | Business phone 2
4 | Home 1
8 | Home 2
16 | Fax
32 | Mobile
64 | Pager
128 | Assistant

See Also

Contact
Contacts


FirstName

The FirstName property returns the contact’s first name.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
Contacts
LastName


FirstRecurringAlarmDate

The FirstRecurringAlarmDate property returns the first date on which an alarm should ring for a recurring item.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Date

Access

Read/write

Remarks

No recurring alarms will ring prior to the date specified in the FirstRecurringAlarmDate property. Applications should set this property to the current date for all new recurring items.

See Also

RecurringAppointments
RecurringEvents
RecurringTasks


Goal

The Goal property returns the goal of the task or project.

Applies To

Project and Task objects

Data Type

String

Access

Read/write

Remarks

The Goal property is used by the Schedule+ Covey Seven Habits Tool.

See Also

Project
Task


HiddenPattern

The HiddenPattern property determines whether the recurring item should be shown to the user.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Boolean

Access

Read/write

Remarks

The HiddenPattern property is reserved for use by Schedule+.

See Also

RecurringAppointments
RecurringEvents
RecurringTasks


InstanceDate

The InstanceDate property returns the date on which an instance of a recurring item is an exception.

Applies To

Exception object

Data Type

Date

Access

Read/write

Remarks

The date specified in the InstanceDate property is the date on which the recurring item would have occurred if it were not an exception.

For example, suppose that an instance of a recurring appointment is scheduled to occur on 10/14/95, but the user moves that instance of the appointment to 10/21/95. When the appointment is moved to the new date, Schedule+ creates a new entry in the Exceptions table with its InstanceDate property set to 10/14/95 and its Start property set to 10/21/95.

See Also

Exceptions Table


IsFromOther

The IsFromOther property returns a set of flags indicating that the item was created by another application.

Applies To

Appointment and Task objects

Data Type

Boolean

Access

Read/write

Remarks

The IsFromOther property is reserved for use by Schedule+. For a list of defined flags, see the Schedule+ object library.

See Also

Appointment
Task


IsRecurringInstance

The IsRecurringInstance property determines whether an item is an instance of a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Boolean

Access

Read-only

Remarks

The IsRecurringInstance property is available only in merged tables, where items can be single items or instances of recurrence patterns.

See Also

RecurringAppointments
RecurringEvents
RecurringTasks


IsTaskAutoDone

The IsTaskAutoDone property returns a Boolean value that indicates whether a task should automatically appear as completed within the Schedule+ user interface when the task's end date occurs.

Applies To

Task object

Data Type

Boolean

Access

Read/write

See Also

CompletedDate
PercentCompleted
Task
Tasks


IsUserDistributionList

The IsUserDistributionList property returns a Boolean value indicating that the user associated with an item is actually a group of users specified by a mail distribution list.

Applies To

Attendee object

Data Type

Boolean

Access

Read/write

Remarks

When an Attendee item is created and its UserEntryId property is set to a distribution list, the IsUserDistributionList property must be set to True on the Attendee item. If it is not, Schedule+ will interpret the Attendee object as a single user and will not expand the name to a list of individual users.

See Also

Attendee
AttendeeStatus
UserDisplay
UserEntryId
UserSearchKey
UserWell


ItemId

The ItemId property returns the item identifier for an object.

Applies to

All Item objects

Data Type

String

Access

Read-only

Remarks

Every item in the schedule has a unique item identifier. The value contained by the ItemId property string is set and managed by Schedule+. Applications can use this value as a unique global item identifier of an item. Only item identifiers returned by Schedule+ are valid.

See Also

ItemIdSelected


ItemIdPath

The ItemIdPath property returns a list of item identifiers that specify a path to the object through the Schedule+ table hierarchy.

Applies To

Alarm object

Data Type

String

Access

Read-only

Remarks

A path consists of a set of tuples (a table and an item identifier). Because tables can be nested, each table and item identifier specifies a level into the Schedule+ table hierarchy. The ItemIdPath and TablePath properties make up a path.

See Also

Alarm
TablePath


JobTitle

The JobTitle property returns the contact’s job title.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact


LastCleanup

The LastCleanup property returns the last date on which a cleanup of the schedule was performed.

Applies To

Schedule object

Data Type

Date

Access

Read/write

Remarks

The LastCleanup property is reserved for use by Schedule+.

See Also

Schedule


LastDailyAlarm

The LastDailyAlarm property returns the date on which the daily alarm was last rung.

Applies To

Schedule object

Data Type

Date/Time

Access

Read/write

Remarks

The LastDailyAlarm property is reserved for use by Schedule+.

See Also

DailyAlarm


LastModified

The LastModified property returns the date and time at which the object was last modified.

Applies To

All Item objects

Data Type

Date

Access

Read-only

Remarks

Applications can use the LastModified property to synchronize two schedules. For example, an application can compare this property on similar sets of objects in two copies of a schedule to determine which object is the latest version.

When synchronizing two different schedules, this property should be used instead of the ChangeNumber property. Change numbers are specific to a single schedule file, whereas this property uses dates that are independent of the schedule file.

See Also

ChangeNumber


LastName

The LastName property returns the last name of a Contact item.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
Contacts
FirstName


LastReceived

The LastReceived property returns the date and time at which the last response to a meeting request was received.

Applies To

Attendee object

Data Type

Date/Time

Access

Read/write

Remarks

When a meeting request is sent and a recipient responds to the request, Schedule+ records the date and time of the response in the LastReceived property of the Attendee object.

See Also

Attendee


LastSynchronized

The LastSynchronized property returns the date and time at which the schedule was last synchronized.

Applies To

Schedule object

Data Type

Date/Time

Access

Read-only

Remarks

The LastSynchronized property is reserved for use by Schedule+. Only the owner of the schedule file can read this property.

See Also

Schedule


MasterScheduleId

The MasterScheduleId property returns the identifier for the master schedule.

Applies To

Schedule object

Data Type

String

Access

Read-only

Remarks

The MasterScheduleId property is reserved for use by Schedule+. Only the owner of the schedule file can read this property.

See Also

Ranges
ReceivedRanges
SentRanges
Synchronize
TableForRange


Mileage

The Mileage property returns the mileage that was incurred as a result of performing a task.

Applies To

Task object

Data Type

String

Access

Read/write

See Also

Task
Tasks


MonthInterval

The MonthInterval property returns the interval between months for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

For example, when defining a recurrence pattern that specifies an appointment that is to occur every other month, set the MonthInterval property to 2.

See Also

RecurringType


MonthOfYearMask

The MonthOfYearMask property returns a combination of flags indicating which months of the year are to be included in a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

The first twelve bits of the MonthOfYearMask property represent the months of the year. Bit 0 is January; bit 11 is December. Bits 12 through 31 are ignored. For example, to indicate January, March, and April with this property, set bits 0, 2, and 3.

See Also

RecurringAppointments
RecurringEvents
RecurringTasks
RecurringType


Name

The Name property returns the calendar-friendly name of the schedule.

Applies To

All Property and Table objects

Data Type

String

Access

Read/write

Remarks

Only the owner can write to the Name property.

See Also

Class


Notes

The Notes property contains notes on an item.

Applies To

Appointment, Contact, RecurringAppointment, RecurringTask, and Task objects

Date Type

String

Access

Read/write


Notify

The Notify property returns the date and time at which an alarm is to ring.

Applies To

Alarm, Appointment, Event, and Task objects

Date Type

Date/Time

Access

Read/write

Remarks

The Notify property is read-only for Alarm objects.

See Also

AlarmAmount
AlarmTypeUnit
Ring


Office

The Office property returns the contact’s office location.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
Contacts


OwnerEntryId

The OwnerEntryId property returns the mail entry identifier for the meeting owner of an item.

Applies To

Appointment and RecurringAppointment objects

Data Type

String

Access

Read/write

Remarks

The value for the OwnerEntryId property is supplied by the MAPI entry identifier. The meeting owner is usually the user who creates the meeting, except when a delegate creates the meeting instead.

See Also

OwnerName
OwnerSearchKey


OwnerName

The OwnerName property returns the MAPI display name for the meeting owner of an item.

Applies To

Appointment and RecurringAppointment objects

Data Type

String

Access

Read/write

Remarks

The value of the OwnerName property is supplied by MAPI. The meeting owner is usually the user who creates the meeting, except when a delegate creates the meeting instead.

See Also

OwnerEntryId
OwnerSearchKey


OwnerSearchKey

The OwnerSearchKey property returns a MAPI search key for the meeting owner of an item.

Applies To

Appointment and RecurringAppointment objects

Data Type

String

Access

Read/write

Remarks

The OwnerSearchKey property is supplied by MAPI and identifies the person who owns the meeting. The meeting owner is usually the user who creates the meeting, except when a delegate creates the meeting instead. For example, Bob could create a meeting request and assign Randy as the meeting owner.

The format of the data in this property is not interpretable by most applications and should be treated like a handle.

See Also

CreatorSearchKey
OwnerEntryId
OwnerName


Password

The Password property specifies a password that enables access to the schedule file.

Applies To

Schedule object

Data Type

String

Access

Write-only

Remarks

Only the owner of the schedule file can write to the Password property, which returns either an empty string or a string with an error message.

See Also

Schedule


PercentCompleted

The PercentCompleted property returns the percentage of the task that is currently complete.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

Although the data type for the PercentCompleted property is Long, applications should set its value in the range zero to 100. When a task is marked completed, the CompletedDate property should be set to True and PercentCompleted set to 100. The exception to this rule is for AutoDone tasks, which are complete at their end date, regardless of the CompletedDate or PercentCompleted property settings.

See Also

CompletedDate
Task
Tasks


PhoneAssistant

The PhoneAssistant property returns the phone number of the contact’s assistant.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneBusiness
PhoneBusiness2
PhoneFax
PhoneHome
PhoneHome2
PhoneMobile
PhonePager


PhoneBusiness

The PhoneBusiness property returns the contact’s business phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness2
PhoneFax
PhoneHome
PhoneHome2
PhoneMobile
PhonePager


PhoneBusiness2

The PhoneBusiness2 property returns the contact’s second business phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness
PhoneFax
PhoneHome
PhoneHome2
PhoneMobile
PhonePager


PhoneFax

The PhoneFax property returns the contact’s fax phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness
PhoneBusiness2
PhoneHome
PhoneHome2
PhoneMobile
PhonePager


PhoneHome

The PhoneHome property returns the contact’s home phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness
PhoneBusiness2
PhoneFax
PhoneHome2
PhoneMobile
PhonePager


PhoneHome2

The PhoneHome2 property returns the contact’s second home phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness
PhoneBusiness2
PhoneFax
PhoneHome
PhoneMobile
PhonePager


PhoneMobile

The PhoneMobile property returns the contact’s mobile phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness
PhoneBusiness2
PhoneFax
PhoneHome
PhoneHome2
PhonePager


PhonePager

The PhonePager property returns the contact’s pager phone number.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact
PhoneAssistant
PhoneBusiness
PhoneBusiness2
PhoneFax
PhoneHome
PhoneHome2
PhoneMobile


PreMigrateCreate

The PreMigrateCreate property returns the original creation date of the schedule.

Applies To

Schedule object

Data Type

Date/Time

Access

Read-only

Remarks

The PreMigrateCreate property is valid only for schedules that were migrated from Schedule+ 1.0. This property is reserved for internal use by Schedule+.

See Also

Schedule


Priority

The Priority property returns a task or project priority.

Applies to

Project and Task objects

Data Type

Long

Access

Read/write

Remarks

The low eight bits of the Priority property’s value is a character.

The following sample code shows how the LConvertTo32bitPriority function converts the string parameter to a Long, which can be used as the priority in Automation (formerly OLE Automation):

‘ Valid formats for the string parameter are:
‘ "1"..."9"
‘ "A"..."Z"
‘ "A1"..."A9", "B1"..."B9", ... , "Z1"..."Z9"
‘ Anything else will return DefaultPriority as the priority,
‘ which is currently "3".

Function LConvertTo32bitPriority(ByVal PriorityText As String) As Long
Const DefaultPriority = &H2033  ' default priority = "3"
Dim PriorityNormal As String
Dim FirstChar As Integer
Dim LastChar As Integer

PriorityNormal = UCase(PriorityText)

Select Case Len(PriorityNormal)
Case 1
    If ((PriorityNormal >= "1") And (PriorityNormal <= "9")) Then
        LConvertTo32bitPriority = &H2000 + Asc(PriorityNormal)
    ElseIf ((PriorityNormal >= "A") And (PriorityNormal <= "Z")) Then
        LConvertTo32bitPriority = (Asc(PriorityNormal) * 256) + &H20
    Else
        LConvertTo32bitPriority = DefaultPriority
    End If

Case 2
    ‘ Verify that the first character is valid.
    FirstChar = Asc(PriorityNormal)
    If ((FirstChar < Asc("A")) Or (FirstChar > Asc("Z"))) Then
        LConvertTo32bitPriority = DefaultPriority
    Else
        ‘ Verify that the second character is valid.
        LastChar = Asc(Right(PriorityNormal, 1))

        If ((LastChar < Asc("1")) Or (LastChar > Asc("9"))) Then
            LConvertTo32bitPriority = DefaultPriority
        Else
            LConvertTo32bitPriority = (FirstChar * 256) + LastChar
        End If
    End If

Case Else
    ' If the string is too short or too long, return "3" as the priority
    ' should use schedule's default priority - left as exercise for the reader...
    LConvertTo32bitPriority = DefaultPriority
End Select

End Function

See Also

Project
Task


ProjectItemId

The ProjectItemId property returns the item identifier for an item in the Projects table to which a task is linked.

Applies to

Task object

Data Type

String

Access

Read/write

Remarks

The ProjectItemId property is used to link a task to a project. All tasks linked to a given project have the same ProjectItemId value.

See Also

Project
Task


Projects

The Projects property returns a table of projects.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read-only

See Also

Tasks


PublishFreeBusy

The PublishFreeBusy property returns the number of months to publish free or busy information.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

Only the owner can write to the PublishFreeBusy property. Free or busy information indicates when a user's appointment schedule is free or busy.

This property indicates the number of months that Schedule+ will make the user's free or busy information available to other users. For example, if this property is set to 3, other users will be able to view the free or busy information for that schedule starting with the current date and extending for the next three months.

See Also

FreeBusy


Ranges

The Ranges property returns a range of change numbers.

Applies To

Schedule object

Data Type

Double (multivalued)

Access

Read-only

Remarks

The Ranges property is used by Schedule+ to synchronize schedules. Only the owner of the schedule file can read this property.

See Also

ChangeNumber
ReceivedRanges
ReceivedRangesTable


ReceivedRanges

The ReceivedRanges property returns a range of change numbers received from the master schedule.

Applies To

Schedule object

Data Type

Double (multivalued)

Access

Read-only

Remarks

The ReceivedRanges property is used by Schedule+ to synchronize schedules. Only the owner of the schedule file can read this property.

See Also

ChangeNumber
Ranges
ReceivedRangesTable


ReceivedRangesTable

The ReceivedRangesTable property returns a table of change numbers.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read-only

Remarks

The ReceivedRangesTable property is used by Schedule+ to synchronize schedules. Only the owner of the schedule file can read this property.

See Also

ChangeNumber
Ranges
ReceivedRanges


ReceiveMeetingRequest

The ReceiveMeetingRequest property returns a Boolean value that determines whether a delegate, in addition to the meeting owner, should receive meeting requests.

Applies To

AccessControls table

Data Type

Boolean

Access

Read/write

Remarks

The ReceiveMeetingRequest property should be set if the user specified within the Access item is a delegate who will receive the schedule owner’s meeting requests. Only the owner of the schedule file can read or write to this property.

It is important to always set this property value to 0 in the default row, which is the row that has no UserEntryId property value (usually, row 0) of the AccessControls table. Otherwise, everyone in the organization will be interpreted as a delegate and receive meeting requests on behalf of the schedule owner.

If you set this property to create a delegate, the DelegateEntryId and DelegateName properties of the Schedule object need to be updated. If the UserDisplay and UserEntryId properties are Null, this item is the default and applies to every user not explicitly mentioned in other items in the AccessControls table.

See Also

AccessControls
DelegateEntryId
DelegateName
UserDisplay
UserEntryId


RecurringAppointments

The RecurringAppointments property returns a table of recurring appointments.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

RecurringEvents
RecurringTasks
Single vs. Recurring Tables


RecurringEvents

The RecurringEvents property returns a table of recurring events.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

RecurringAppointments
RecurringTasks
Single vs. Recurring Tables


RecurringTasks

The RecurringTasks property returns a table of recurring tasks.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

RecurringAppointments
RecurringEvents
Single vs. Recurring Tables


RecurringType

The RecurringType property returns the type of recurrence pattern.

Applies to

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

The RecurringType property is required. Use this property to get or set the type of recurrence pattern that applies to an item. Annual events must be a yearly specific recurrence pattern (for example, the tenth day of the fourth month every year).

The RecurringType property can have one of the following values.

Value | Description
64 | Daily
48 | Weekly
12 | Monthly (on specified days)
56 | Monthly (recurring every nth day of the week, every mth week)
7 | Yearly (on specified days)
51 | Yearly (recurring every nth day of the month, every mth month)

Depending on the RecurringType value, other properties must be set to correctly define a recurring item, as shown in the following table.

Recurring Type | Additional Properties
Daily (64) | DayInterval
Weekly (48) | WeekInterval DayOfWeekMask DayOfWeekStart
Monthly1 (12) | MonthInterval DayOfMonthMask
Monthly2 (56) | WeekInterval DayOfWeekMask MonthInterval
Yearly1 (7) | DayOfMonthMask YearInterval MonthOfYearMask
Yearly2 (51) | WeekInterval DayOfWeekMask YearInterval MonthOfYearMask

See Also

RecurringAppointments
RecurringEvents
RecurringTasks
Single vs. Recurring Tables


ResourceType

The ResourceType property determines whether the schedule is for a resource, such as a conference room.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The ResourceType property is reserved for use by Schedule+. Only the owner can write to this property.

For normal users, this resource type is IResourceTypeUser. For locations, it is IResourceTypeLocation. For all other resources, such as audiovisual equipment, it is IResourceTypeOther.

See Also

Schedule


Ring

The Ring property returns a Boolean value that indicates whether an alarm is set to ring for an item.

Applies To

Appointment, Event, and Task objects

DataType

Boolean

Access

Read/write

Remarks

The Ring property must be set for alarms to ring. Although an application can create a new alarm and set its AlarmAmount and AlarmTypeUnit properties, the alarm will not ring by default — you must set the Ring property to True for an alarm to ring.

See Also

AlarmAmount
AlarmTypeUnit
RingAgain
RingOriginal


RingAgain

The RingAgain property determines whether an alarm rings again.

Applies To

Appointment, Event, and Task objects

Data Type

Long

Access

Read/write

Remarks

The RingAgain property is set when the user sets the alarm snooze option.

See Also

Ring
RingOriginal


RingOriginal

The RingOriginal property returns a Boolean value that indicates if the alarm was previously set on an item before the alarm rang.

Applies To

Appointment, Event, and Task objects

Data Type

Long

Access

Read/write

Remarks

When an alarm is created, the Ring and RingOriginal properties should be set to the same value. After an alarm has rung and the user requests not to be notified again, the Ring property will be set to False, but RingOriginal will be set to True.

For example, if an alarm on an appointment has rung and the appointment is then moved into the future by resetting its Start and End properties, the Ring property can be reset based on the value of RingOriginal.

See Also

End
Ring
RingAgain
Start


Roles

The Roles property returns a table of Role items.

Applies To

Role object

Data Type

Object (Table)

Access

Read/write

Remarks

The Roles property is reserved for use by the Schedule+ Covey Seven Habits Tools.

See Also

RoleColor
RoleItemId
RolePosition


RoleColor

The RoleColor property returns the color of the Role object.

Applies To

Role object

Data Type

Long

Access

Read/write

Remarks

The RoleColor property is reserved for use by the Schedule+ Covey Seven Habits Tools.

See Also

Roles
RoleItemId
RolePosition


RoleItemId

The RoleItemId property returns an item identifier for the Role object.

Applies To

Role object

Data Type

String

Access

Read/write

Remarks

The RoleItemId property is reserved for use by the Schedule+ Covey Seven Habits Tools. This property links a task to a role. All tasks belonging to a given role have the same RoleItemId property value.

See Also

Roles
RoleColor
RoleItemId
RolePosition


RolePosition

The RolePosition property returns the position of the Role object.

Applies To

Role object

Data Type

Long

Access

Read/write

Remarks

The RolePosition property is reserved for use by the Schedule+ Covey Seven Habits Tools.

See Also

Roles
RoleColor
RoleItemId


ScheduleId

The ScheduleId property returns the item identifier associated with a Schedule object.

Applies To

Schedule object

Data Type

String

Access

Read-only

Remarks

The ScheduleId property uniquely identifies a schedule.

See Also

ItemId


SentRanges

The SentRanges property returns a range of change numbers sent to the master schedule.

Applies To

Schedule object

Data Type

Double (multivalued)

Access

Read-only

Remarks

The SentRanges property is used by Schedule+ to synchronize schedules. Only the owner of the schedule file can read this property.

See Also

ChangeNumber
Ranges
ReceivedRanges
SentRangesTable


SentRangesTable

The SentRangesTable property returns a table of change numbers.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read-only

Remarks

The SentRangesTable property is used by Schedule+ to synchronize schedules. Only the owner of the schedule file can read this property.

See Also

ChangeNumber
Ranges
ReceivedRangesTable
SentRanges
Tables


SingleAppointments

The SingleAppointments property returns a table of all appointments that occur only once.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

Appointments
RecurringAppointments


SingleEvents

The SingleEvents property returns a table of all events that occur only once.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

Events
RecurringEvents


SingleTasks

The SingleTasks property returns a table of all tasks that occur only once.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

RecurringTasks
Tasks


SlaveScheduleId

The SlaveScheduleId property returns the item identifier of the slave schedule.

Applies To

Schedule object

Data Type

String

Access

Read-only

Remarks

Only the owner of the schedule file can read the SlaveScheduleId property, which is reserved for internal use by Schedule+.

See Also

ScheduleId


SoundDefault

The SoundDefault property returns the default sound level for an alarm.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The SoundDefault property is reserved for use by Schedule+.

See Also

SoundLevel


SoundLevel

The SoundLevel property returns the sound level for an alarm.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The SoundLevel property is reserved for use by Schedule+.

See Also

SoundDefault


Spouse

The Spouse property returns the name of the contact’s spouse.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

Contact


Start

The Start property returns the start date and time for an item.

Applies To

Appointment, Event, and Task objects

Data Type

Date/Time

Access

Read/write

See Also

End


StartDate

The StartDate property returns the start date for an item.

Applies To

Appointment, Event, and Task objects

Data Type

Date

Access

Read/write

See Also

EndDate


StartRecurringDate

The StartRecurringDate property returns the start date for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Date

Access

Read/write

Remarks

The StartRecurringDate property is required for all recurring objects.

See Also

EndRecurringDate
EndRecurringTime
StartRecurringTime


StartRecurringTime

The StartRecurringTime property returns the start time for a recurrence pattern.

Applies To

Recurring Appointment, RecurringEvent, and RecurringTask objects

Data Type

Time

Access

Read/write

Remarks

The StartRecurringTime and EndRecurringTime properties determine the range of time for the recurring item on every instance of the recurrence pattern. For example, for a recurring appointment from 9:00 A.M. to 10:00 A.M., the StartRecurringTime value is 9:00 A.M.

See Also

EndRecurringDate
EndRecurringTime
StartRecurringDate


StateBusiness

The StateBusiness property returns the state or province of the business address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

AddressBusiness
CityBusiness


StateHome

The StateHome property returns the state or province of the home address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

AddressHome
CityHome


TableForRange

The TableForRange property returns an identifier for a table to which a range of change numbers refers.

Applies To

Schedule object

Data Type

Long

Access

Read-only

Remarks

The TableForRange property is used by Schedule+ to synchronize schedules. Only the owner of the schedule file can read this property.

See Also

ChangeNumber
Tables


TableList

The TableList property returns a list of tables that store access control lists (ACLs).

Applies To

AccessControls table

DataType

Long (multivalued)

Access

Read/write

Remarks

The TableList property is a multivalued property. Only the owner has write access to this property.

See Also

TablePath


TablePath

The TablePath property returns a table in a path to the object through the Schedule+ table hierarchy.

Applies To

Alarm object

Data Type

Long (multivalued)

Access

Read-only

Remarks

A path consists of a set of tuples (a table and an item identifier). Because tables can be nested, each table and item identifier specifies a level into the Schedule+ table hierarchy. The TablePath and ItemIdPath properties make up a path.

See Also

ItemIdPath
Tables


TaskItemId

The TaskItemId property returns an item identifier for the task to which the item is related.

Applies To

Appointment object

Data Type

String

Access

Read/write

Remarks

The related item is usually an Appointment object.

See Also

ItemId
ProjectItemId


TaskOwner

The TaskOwner property returns the task placeholder for the owner.

Applies To

Task object

Data Type

String

Access

Read/write

Remarks

The TaskOwner property is reserved for use by Schedule+.

See Also

TaskRecipients
Tasks
TaskSource


TaskRecipients

The TaskRecipients property returns the task placeholder for recipients.

Applies To

Task object

Data Type

String

Access

Read/write

Remarks

The TaskRecipients property is reserved for use by Schedule+.

See Also

TaskOwner
Tasks
TaskSource


Tasks

The Tasks property returns a table that stores the list of single tasks merged with instances of recurring tasks.

Applies To

Schedule object

Data Type

Object (Table)

Access

Read/write

See Also

RecurringTasks
SingleTasks
Single vs. Recurring Tables


TaskSource

The TaskSource property returns the task placeholder for the source.

Applies To

Task object

Data Type

String

Access

Read-only

Remarks

The TaskSource property is reserved for use by Schedule+.

See Also

TaskOwner
TaskRecipients
Tasks


Text

The Text property returns the text of an item.

Applies To

Appointment, Event, Project, and Task objects

Data Type

String

Access

Read/write

Remarks

The Text property returns the text that describes an appointment, an event, a project, or a task.

See Also

Appointment
Event
Project
Task


TimeUnitsPerHour

The TimeUnitsPerHour property returns the number of time units per hour in appointment and planner views.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The TimeUnitsPerHour property is reserved for use by Schedule+.

See Also

TimeUnitsPerHourDragDrop


TimeUnitsPerHourDragDrop

The TimeUnitsPerHourDragDrop property returns the number of time units per hour to be used when dragging and dropping items.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The TimeUnitsPerHourDragDrop property is reserved for use by Schedule+.

See Also

TimeUnitsPerHour


Timezone

The Timezone property returns the current time zone for the schedule.

Applies To

Schedule object

Data Type

Long

Access

Read-only

See Also

Schedule


TypeUnitActualEffort

The TypeUnitActualEffort property returns the type of unit for the actual effort for an item.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

The TypeUnitActualEffort property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

AmountActualEffort
AmountEstimatedEffort
AmountStartWork
TypeUnitEstimatedEffort


TypeUnitEstimatedEffort

The TypeUnitEstimatedEffort property returns the type of unit for the estimated effort for an item.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

The TypeUnitEstimatedEffort property can have one of the following values.

Value | Description
0 | Minutes
1 | Hours
2 | Days
3 | Weeks
4 | Months

See Also

TypeUnitActualEffort


TypeUnitStartWork

The TypeUnitStartWork property returns the type of unit for amount of time before the end date to start work.

Applies To

Task object

Data Type

Long

Access

Read/write

Remarks

The TypeUnitStartWork property works in conjunction with the AmountStartWork property to determine the start date of the task.

The TypeUnitStartWork property can have one of the following values.

Value | Description
2 | Days
3 | Weeks
4 | Months

See Also

AmountStartWork


User1

The User1 property returns a user-defined string that can be used for any purpose on any object.

Applies To

Contact object

Data Type

String

Access

Read/write

Remarks

Before values are written to the User1 property, applications should determine if it already contains information provided by other applications.

See Also

User2
User3
User4


User2

The User2 property returns a user-defined string that can be used for any purpose on any object.

Applies To

Contact object

Data Type

String

Access

Read/write

Remarks

Before values are written to the User2 property, applications should determine if it already contains information provided by other applications.

See Also

User1
User3
User4


User3

The User3 property returns a user-defined string that can be used for any purpose on any object.

Applies To

Contact object

Data Type

String

Access

Read/write

Remarks

Before values are written to the User3 property, applications should determine if it already contains information provided by other applications.

See Also

User1
User2
User4


User4

The User4 property returns a user-defined string that can be used for any purpose on any object.

Applies To

Contact object

Data Type

String

Access

Read/write

Remarks

Before values are written to the User4 property, applications should determine if it already contains information provided by other applications.

See Also

User1
User2
User3


UserDisplay

The UserDisplay property returns the MAPI display name of the user associated with an item.

Applies To

Access and Attendee objects

Data Type

String

Access

Read/write

Remarks

In the context of a Schedule object, the UserDisplay property returns the display name of the currently logged-on Schedule+ user. In the context of an Attendee item, it returns the display name of the attendee.

Note You should always set the UserDisplay, UserEntryId, and UserSearchKey properties. Failing to set all three of these properties can lead to unexpected results.

See Also

UserEntryId
UserName
UserSearchKey


UserEntryId

The UserEntryId property returns a unique value that identifies the user to the underlying mail system.

Applies To

Access and Attendee objects

Data Type

String

Access

Read/write

Remarks

The UserEntryId property is an opaque identifier whose format is specific to the mail system. Applications can use this property to identify a user to the mail system, such as when sending mail.

Note You should always set the UserDisplay, UserEntryId, and UserSearchKey properties. Failing to set all three of these properties can lead to unexpected results.

See Also

CreatorEntryId
DelegateEntryId
OwnerEntryId
UserDisplay
UserSearchKey


UserSearchKey

The UserSearchKey property returns a unique identifier that is used to compare user identities.

Applies To

Access and Attendee objects

Data Type

String

Access

Read-only

Remarks

The UserSearchKey property can be used to compare the identities of two users. It uniquely identifies the user.

For example, an application can compare a given user’s UserSearchKey property with the UserSearchKey property of all the attendees in an Attendees table to determine if the given user is among the attendees.

Note You should always set the UserDisplay, UserEntryId, and UserSearchKey properties. Failing to set all three of these properties can lead to unexpected results.

See Also

CreatorSearchKey
OwnerSearchKey
UserDisplay
UserEntryId


UserWell

The UserWell property determines whether the user is required, optional, or a resource.

Applies To

Attendee object

Data Type

Long

Access

Read/write

Remarks

The UserWell property is required when specifying attendees for a meeting request. This property can have one of the following values.

Value | Description
0 | Owner.
1 | Required; interpreted by MAPI as a recipient in a message’s To field.
2 | Optional; interpreted by MAPI as a recipient in a message’s CC field.
3 | Resource; interpreted by MAPI as a recipient in a message’s BCC field.

See Also

Attendee


WeekInterval

The WeekInterval property returns the number of weeks between instances of a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

When creating a weekly recurring appointment or task, set the WeekInterval property to the number of weeks that should occur between instances of the item. For example, to create an appointment that recurs every three weeks, set this property to 3.

This property is also used for monthly or yearly recurrences that specify instances in terms of weeks.

See Also

RecurringType


WeekStartOn

The WeekStartOn property returns the day on which to start the week.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The WeekStartOn property can have one of the following values.

Value | Description
0 | Sunday
1 | Monday
2 | Tuesday
3 | Wednesday
4 | Thursday
5 | Friday
6 | Saturday

See Also

Schedule


Where

The Where property returns the location of a meeting.

Applies To

Appointment object

Data Type

String

Access

Read/write

Remarks

The location of the meeting appears before any other resource in a meeting request.

See Also

Appointment


YearInterval

The YearInterval property returns the interval between years for a recurrence pattern.

Applies To

RecurringAppointment, RecurringEvent, and RecurringTask objects

Data Type

Long

Access

Read/write

Remarks

When creating a yearly recurrence pattern, set the YearInterval property to the number of years that should occur between instances of the recurring item. For example, to create a recurrence pattern that recurs every three years, set this property to 3.

See Also

RecurringType


ZipCodeBusiness

The ZipCodeBusiness property returns the postal or zip code of the contact’s business street address.

Applies to

Contact object

Data Type

String

Access

Read/write

See Also

AddressBusiness
ZipCodeHome


ZipCodeHome

The ZipCodeHome property returns the postal or zip code of the contact’s home street address.

Applies To

Contact object

Data Type

String

Access

Read/write

See Also

AddressHome
ZipCodeBusiness


Data Members

This section contains an alphabetic listing of all Schedule+ Automation data members, their data types, and the objects to which they apply.


AccessPermitted

The AccessPermitted data member returns the access control information for items in a table.

Applies To

All Table objects

Data Type

Long

Access

Read-only

Remarks

The AccessPermitted data member returns the access level allowed to the user on a given table.

The AccessPermitted data member has the following values.

Value | Description
0 | No access
1 | Minimal read
2 | Read
3 | Create
4 | Write
5 | Owner

See Also

AccessActual
AccessDefault
AccessLists
AccessControls
Tables


Application

The Application data member returns an Application object.

Applies To

All objects

Data Type

Object (Application)

Access

Read-only

See Also

Parent


CanUndo

The CanUndo data member determines whether the last transaction can be undone.

Applies To

Schedule object

Data Type

Long

Access

Read-only

See Also

Undo
ClearUndo


ChangeNumber

The ChangeNumber data member returns the change number for a property.

Applies To

Property and Schedule objects

Data Type

Double

Access

Read-only

Remarks

The ChangeNumber data member allows Schedule+ to sychronize local and server schedules on a per-property basis. If a change is made to any property in the schedule file, this data member is increased by one on that object and on all objects that are parents of the object. For example, if the current change number of an Attendee object is 10 and a change is made to that object, the new change number of the Attendee object will be 11, the change number of the Appointment object that contains the Attendee object will be increased by one, and the change number of the Schedule object will be increased by one. In other words, change numbers propagate upward through the object hierarchy.

This data member is useful in situations where multiple applications or users are using different copies of the same schedule file. For example, if a user takes a copy of a schedule on a laptop computer, an application can read the ChangeNumber data member upon reattaching the laptop computer to the network to see whether information in the network server copy of the schedule has changed. If objects have changed, the application can perform custom operations, such as showing the user a list of all objects in the server-based copy of the schedule that changed while the user was on the road.

Change numbers are schedule-specific, which means that a different set of change numbers are maintained for each schedule. Therefore, applications should not compare change numbers from different schedules and should always check the value of the ScheduleId property of the two files being synchronized to ensure that the same schedule is being used.

See Also

DeletedItems
LastModified
LastSynchronized
ScheduleId


Class

The Class data member returns the type of the property.

Applies To

All Property and Table objects

Data Type

Long

Access

Read-only

Remarks

The Class data member returns the type of the property, whether or not the property exists. It also returns the type of a multivalued property. Most properties have simple types, such as Long, String, Boolean, and Date. Properties on table objects have one of the table types. In addition, simple property types can be combined in a multivalued property.

The property types are shown in the following sample code:

'Simple types
Const SPTY_NULL As Int = 0
Const SPTY_BOOLEAN As Int = 1
Const SPTY_ULONG As Int = 2
Const SPTY_LONG As Int = 3
Const SPTY_LONGLONG As Int = 4
Const SPTY_DATE As Int = 5
Const SPTY_TIME As Int = 6
Const SPTY_DATETIME As Int = 7
Const SPTY_STRING As Int = 8
Const SPTY_BINARYSTRING As int = 9
Const SPTY_ITEMID As Int = 10        'also a binary string
Const SPTY_SCHID As Int =11            'schedule id
Const SPTY_SCHGN As Int = 12            'change number

'Table types
Const SPTY_TABLE As Int = 256
Const SPTY_BUSYTABLE As Int =257
Const SPTY_BUSYRECURTABLE As Int =258
Const SPTY_BUSYMERGETABLE As Int = 259
Const SPTY_ALARMTABLE As Int = 260

'Error (for example, property not available)
Const SPTY_ERROR As Int =255

'Multivalued properties
Const SPTY_MVBOOLEAN As Int = 32769
Const SPTY_MVULONG As Int = 32770
Const SPTY_MVLONG As Int = 32771
Const SPTY_MVLONGLONG As Int = 32772
Const SPTY_MVDATE     As Int = 32773
Const SPTY_MVTIME As Int = 32774
Const SPTY_MVDATETIME As Int 32775
Const SPTY_MVSTRING As Int = 32776
const SPTY_MVBINARYSTRING As Int = 32777
Const SPTY_MVITEMID As Int = 32778
Const SPTY_MVSCHID As Int = 32779
Const SPTY_MVSCHGN As Int = 32780

See Also

Tables


Count

The Count data member returns the number of values on a multivalued property.

Applies To

All Property objects

Data Type

Long

Access

Read-only

Remarks

The Count data member is used for multivalued properties, such as DelegateEntryId and DelegateName.

See Also

DelegateEntryId
DelegateName
Properties


EndRange

The EndRange data member returns the end date for the range of dates in the view for the topmost open schedule.

Applies To

Application object

Data Type

Date/Time

Access

Read-only

See Also

StartRange


EndSelection

The EndSelection data member returns the end date and time of the selection in the topmost open schedule.

Applies To

Application object

Data Type

Date/Time

Access

Read-only

See Also

StartSelection


IsEndOfTable

The IsEndOfTable data member returns a Boolean value that indicates whether the cursor is at the end of the table.

Applies To

All Table objects

Data Type

Boolean

Access

Read-only

Remarks

The IsEndOfTable data member should be used when looping through items in a table to prevent reading beyond the end of the table.

See Also

Tables


IsItemSelected

The IsItemSelected data member returns a Boolean value that indicates whether an item is selected in the topmost open schedule.

Applies To

Application object

Data Type

Boolean

Access

Read-only

Remarks

The ItemIdSelected and TableSelected data members are valid only if IsItemSelected returns True.

See Also

ItemIdSelected
TableSelected


IsMailEnabled

The IsMailEnabled data member determines whether Schedule+ is running in a group-enabled environment.

Applies To

Application object

Data Type

Boolean

Access

Read-only

See Also

Application


IsScheduleSelected

The IsScheduleSelected data member returns a Boolean value that indicates whether a Schedule+ user has a currently open schedule.

Applies To

Application object

Data Type

Boolean

Access

Read-only

Remarks

The ScheduleSelected data member will only return a valid Schedule object if IsScheduleSelected returns True.

See Also

ScheduleSelected


ItemIdSelected

The ItemIdSelected data member returns the item identifier for the selected item in the topmost schedule.

Applies To

Application object

Data Type

String

Access

Read-only

Remarks

The ItemIdSelected data member is valid only if the IsItemSelected property returns True.

See Also

IsItemSelected
TableSelected


LoggedOn

The LoggedOn data member determines whether Schedule+ is logged on.

Applies To

Application object

Data Type

Boolean

Access

Read-only

Remarks

The LoggedOn data member returns a Boolean value indicating whether a user has logged on.

See Also

IsMailEnabled


Name

The Name data member returns the name of the property or table.

Applies To

All Property and Table objects

Data Type

String

Access

Read/write

See Also

Class


Parent

The Parent data member returns to an object’s parent object.

Applies To

All objects

Data Type

Object

Access

Read-only

See Also

Application


Position

The Position data member returns the current position of the cursor in the table.

Applies To

All Table objects

Data Type

Long

Access

Read-only

Remarks

The Position data member works only on simple tables that have no restrictions. it is guaranteed to be accurate only for tables if the SetRange and SetRestriction methods are used. Using these methods invalidates the position.

Note This property is recommended for use only on small, simple tables such as the Attendees table.

See Also

Rows
SetRange
SetRestriction


Properties

The Properties data member returns the count and values of the properties defined on an object. It returns the property itself if used with an index.

Applies To

Schedule and all Item objects

Data Type

Long or Property-dependent

Access

Read-only

Remarks

The Properties data member can also be indexed to return the actual properties. The following sample code illustrates the use of the Properties data member:

objSchedule.Properties
objSchedule.Properties(1).Name
objSchedule.Properties(1).Class

See Also

Items


Rows

The Rows data member returns the current number of rows in a table.

Applies To

All Table objects

Data Type

Long

Access

Read-only

Remarks

The Rows data member works only on simple tables that have no restrictions. It is guaranteed to be accurate only for tables if the SetRange and SetRestriction methods are not used. Using these methods invalidates the position.

See Also

GetRows
SetRange
SetRestriction
Tables


ScheduleLogged

The ScheduleLogged data member returns the Schedule object for the currently logged-on user.

Applies To

Application object

Data Type

Object (Schedule)

Access

Read-only

See Also

ScheduleForFile
ScheduleForUser


ScheduleSelected

The ScheduleSelected data member returns the Schedule object for the topmost open schedule.

Applies To

Application object

Data Type

Object (Schedule)

Access

Read-only

See Also

IsScheduleSelected


StartRange

The StartRange data member returns the start date of the range of dates in the view for the topmost open schedule.

Applies To

Application object

Data Type

Date/Time

Access

Read-only

See Also

EndRange


StartSelection

The StartSelection data member returns the start date and time of the selection in the topmost open schedule.

Applies To

Application object

Data Type

Date/Time

Access

Read-only

See Also

EndSelection


SupportedOperations

The SupportedOperations data member returns the operations available for the schedule.

Applies To

Schedule object

Data Type

Long

Access

Read-only

Remarks

The SupportedOperations data member determines what type of operations can be performed on the schedule.

The SupportedOperations data member returns the following values.

Value | Description
1 | Application can only determine the schedule owner.
2 | Application can only access free/busy information for the schedule.
3 | Application can only access appointments and tasks.
4 | Application can access any part of the schedule.

See Also

Schedule


TableSelected

The TableSelected data member returns the name of the table that contains the selected item.

Applies To

Application object

Data Type

String

Access

Read-only

Remarks

If there is no currently selected item, the TableSelected data member returns an error. You should use the IsItemSelected data member to verify that an item is selected before using the TableSelected data member.

See Also

IsItemSelected
ItemIdSelected


Timezone

The Timezone data member returns the current time zone for the schedule.

Applies To

Schedule object

Data Type

Long

Access

Read-only

See Also

Schedule


Usage

The Usage data member returns information on how actively the Schedule object is being used.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

The Usage data member can have one of the following values.

Value | Description
0 | The window is not being viewed or accessed (for example, if the window is minimized).
1 | Data is visible but is not currently being accessed.
2 | Data is being viewed and accessed.
3 | The window is not in any of the above conditions.

Set this property to 0 to suppress notifications. This is useful when many changes are made to a schedule, resulting in extra time to perform notifications with each change.

See Also

Schedule


UserAddress

The UserAddress data member returns the e-mail address of the currently logged-on Schedule+ user.

Applies To

Application and Schedule objects

Data Type

String

Access

Read-only

Remarks

The format of the UserAddress data member is a human-readable e-mail address that can be understood by the underlying mail system. For example, a valid value for this data member is SMTP:BrianW@Cyber.Com for an SMTP user on a TCP/IP network.

See Also

UserEntryId
UserName
UserSearchKey


UserEntryId

The UserEntryId data member returns a unique identifier that is used to identify the user to the underlying mail system.

Applies To

Application and Schedule objects

Data Type

String

Access

Read-only

Remarks

The UserEntryId data member is an opaque identifier whose format is specific to the mail system. It uniquely identifies the currently logged-on Schedule+ user. Applications can use this data member to identify a user to the mail system, such as when sending mail.

Use the UserSearchKey data member to compare two user identities. This data member is set by the underlying mail system.

See Also

UserAddress
UserName
UserSearchKey


UserName

The UserName data member returns the name of the user that is currently logged on to Schedule+.

Applies To

Application and Schedule objects

Data Type

String

Access

Read-only

See Also

UserAddress
UserEntryId
UserSearchKey


UserSearchKey

The UserSearchKey data member returns a unique identifier that is used to compare user identities.

Applies To

Application and Schedule objects

Data Type

String

Access

Read-only

Remarks

The UserSearchKey data member can be used to compare the identities of two users. For example, an application can compare a given user’s UserSearchKey property with the UserSearchKey property of all the attendees in an Attendees table to determine if the given user is among the attendees.

You should set the entry identifier, MAPI search key, and display name of all new Attendee objects. Failing to set all three of these properties can lead to unexpected results.

See Also

UserAddress
UserEntryId
UserName


Visible

The Visible data member returns whether the schedule is displayed.

Applies To

Schedule object

Data Type

Long

Access

Read/write

Remarks

Setting the Visible data member to True makes a schedule visible.

See Also

Activate


Methods

This section contains an alphabetic listing of all Schedule+ Automation methods, their parameters, and the objects to which they apply.

Note Parameters to the methods in this section can be either named or supplied by position. If positional parameters are used, ensure that you replace unspecified string parameters with empty strings. For example:

objApplication.Logon "MyProfile", , True

should be specified as:

objApplication.Logon "MyProfile", "", True


Activate

The Activate method activates a Schedule+ window.

Applies To

Schedule object

Syntax

objSchedule.Activate StartDateTime, EndDateTime, TableSelect, ItemIdSelect

Parameters

StartDateTime
Optional. Specifies the start date and time to select when the window is activated.
EndDateTime
Optional. Specifies the end date and time to select when the window is activated.
TableSelect
Optional. Specifies the name of the table from which the object is selected.
ItemIdSelect
Optional. Specifies the item identifier of the item to select.

Remarks

To activate the Contacts window, use the string “Contacts” for the TableSelect parameter. For example:

objSchedule.Activate Now, Now, "Contacts",
objContact.ItemId

If TableSelect is passed in, ItemIdSelect must also be passed in.

See Also

Schedule


BeginTransaction

The BeginTransaction method begins a transaction to buffer changes to a Schedule object.

Applies To

Schedule object

Syntax

objSchedule.BeginTransaction

Parameters

None

Remarks

The BeginTransaction method begins a transaction within a schedule file. Beginning a transaction means that all changes to the Schedule object or to any of its child objects are not saved to disk until the EndTransaction method is called. Only one transaction can be open on a schedule at any one time. However, calls to BeginTransaction can be nested.

For example, if your application enables users to delete multiple items at once, you can call this method before deleting the items and call the RollbackTransaction method if an error occurs during the deletion. If no errors occur, the application can call EndTransaction, which commits the deletions.

Note It is important to call EndTransaction for each call to BeginTransaction.

If an error occurs, do not call the EndTransaction method. You must first call the RollbackTransaction method before continuing.

See Also

EndTransaction
RollbackTransaction


ClearUndo

The ClearUndo method clears any undo operations available for the schedule.

Applies To

Schedule object

Syntax

objSchedule.ClearUndo

Parameters

None

Remarks

The ClearUndo method prevents users from undoing operations that have been performed on the schedule. Good programming practice dictates the use of this method only if the application performs some operation that should not be undone. Otherwise, using this method can confuse the user, or cause the application to be in an unwanted state if the operation is undone.

See Also

Undo


DeleteItem

The DeleteItem method deletes an item from a table.

Applies To

All Table objects

Syntax

objTable.DeleteItem ItemId

Parameters

ItemId
Specifies the identifier of the item to delete.

Remarks

The following sample code deletes the current item from the table:

objTable.DeleteItem
    objTable.Item.ItemId

See Also

DeleteProperties


DeleteProperties

The DeleteProperties method removes specified properties from an object.

Applies To

Schedule and all Item objects

Syntax

objAppt.DeleteProperties Arg1=string, Arg2=string, ..., ArgN=string

Parameters

Arg1=string, …, ArgN=string
Specifies the names of properties to remove.

Remarks

The DeleteProperties method provides an efficient means of deleting multiple properties in a single call. For example, the following sample code uses this method to remove the alarm properties from an appointment:

objAppt.DeleteProperties Ring, AlarmAmount, AlarmTypeUnit

Some properties cannot be deleted, such as ItemId, Created, and LastModified.

See Also

Flush


EndTransaction

The EndTransaction method ends a transaction and saves all buffered changes to a schedule.

Applies To

Schedule object

Syntax

objSchedule.EndTransaction

Parameters

None

Remarks

The EndTransaction method saves all buffered changes to a Schedule object that have occurred since the last call to the BeginTransaction method. If the call to this method fails, you do not have to call the RollbackTransaction method. However, your changes may not be saved.

Note Every call to BeginTransaction must have a matching call to EndTransaction or RollbackTransaction.

See Also

BeginTransaction
RollbackTransaction


Flush

The Flush method removes properties that have been changed.

Applies To

Schedule and all Item objects

Syntax

objContact.Flush

Parameters

None

Remarks

Call the Flush method after modifying an object’s properties, but before releasing the object. This ensures that all changes have been made.

See Also

SetProperties


FreeBusy

The FreeBusy method indicates whether a user is free or busy.

Applies To

Schedule object

Syntax

objSchedule.FreeBusy (MonthsToRetrieve, MinutesPerChar)

Parameters

MonthsToRetrieve
Specifies the month and year for which to retrieve data. The day is ignored.
MinutesPerChar
Optional. Returns the number of minutes for each character. The default is 30.

Returns

String

Remarks

The FreeBusy method returns the information as a string, where each character indicates whether the user is busy during the time specified in the MinutesPerChar parameter. The character 0 indicates the user is free; 1 indicates the user is busy during the year and month specified in the MonthsToRetrieve parameter. For example:

Dim fb As String
Dim dt As Date
dt = #12/1/95#
fb = objSchedule.FreeBusy(dt)
Debug.Print fb

See Also

Schedule


GetProperties

The GetProperties method gets the values of one or more specified properties.

Applies To

Schedule and all Item objects

Syntax

objContact.GetProperties (Arg1, Arg2, ..., ArgN)

Parameters

Arg1, …, ArgN
Specifies the names of properties to get.

Returns

Variant array

Remarks

The variant array is two-dimensional with only one row containing the values of properties specified as parameters. You can include any number of properties defined for an object and specify them in any order.

It is faster to call the GetProperties method with multiple arguments on an object than to call the GetProperty method multiple times. For example:

Dim As Variant
arr = array (1,2)
arr = objContact.GetPropeties ("FirstName", "LastName")
Debug.Print arr (0,0), arr (0,1)

Note This method does not work with Visual Basic version 3.0. You must use the GetProperty method instead.

See Also

GetProperty


GetProperty

The GetProperty method retrieves the value of a specified property.

Applies To

Schedule and all Item objects

Syntax

objContact.GetProperty (Arg1)

Parameters

Arg1
Specifies the name of the property to get.

Returns

Variant

Remarks

The GetProperty method is not supported for table or multivalued properties. From Visual Basic version 3.0 or earlier, this method also provides quicker data access than the GetProperties method. For example:

Dim x As Variant
x = ObjContact.GetPropety ("FirstName")
Debug.Print x

See Also

GetProperties


GetRows

The GetRows method returns a two-dimensional array of properties.

Applies To

All Table objects

Syntax

objAppointmentsTable.GetRows (maximumRows, Arg1, …, ArgN)

Parameters

maximumRows
Specifies the maximum number of rows to retrieve. The maximum is 100.
Arg1, …, ArgN
Specifies the name or identifier of each property whose value is to be returned.

Returns

Variant array

Remarks

Each row in the two-dimensional array that is returned corresponds to an item. Each column in the array corresponds to the specified name or property identifier. Tables and multivalued properties return Null as their property information.

Note The array returned must be created using an Array statement. Using a statically declared array of variants will not work.

The following sample code retrieves three properties from the first 10 rows in the table:

Dim arr As Variant
arr Data = Array (9,2)
arr Data = objAppts.GetRows (10, "Start", "End", "Text")

See Also

GetProperties


Item

The Item method returns the Item object to which the cursor points.

Applies To

All Table objects

Syntax

objContactsTable.Item ItemId

Parameters

ItemId
Optional. Specifies the item identifier of the Item object to return.

Remarks

If ItemId is omitted, the current item in the table is returned. If the cursor is past the end of the table, the call returns an error.

See Also

Tables


Logoff

The Logoff method logs off Schedule+.

Applies To

Application object

Syntax

objApplication.Logoff NotifyEveryone

Parameters

NotifyEveryone
Optional. Specifies whether to notify all MAPI applications when logging off a shared session.

Remarks

If Schedule+ is group-enabled, the Logoff method also logs off MAPI. You should call this method if you call the Logon method.

See Also

LoggedOn
Logon


Logon

The Logon method logs on to Schedule+.

Applies To

Application object

Syntax

objApplication.Logon ProfileName, ProfilePassword, ShowDialog, ParentWindow

Parameters

ProfileName
Optional. Specifies a name for the profile.
ProfilePassword
Optional. Specifies a password for the profile.
ShowDialog
Optional. Sets a flag that determines whether the user interface should be shown.
ParentWindow
Optional. Specifies the hwnd handle of the parent window.

Remarks

If Schedule+ is group-enabled, the Logon method also logs on to MAPI using the values passed in ProfileName and ProfilePassword. In any case, calling this method initializes Schedule+ so that the user’s schedule is available.

See Also

LoggedOn
Logoff


New

The New method creates a new item in a table.

Applies To

All Table objects

Syntax

objEventsTable.New (ItemId)

Parameters

ItemId
Optional. Specifies a string containing the item identifier of the Item object to create.

Returns

Item

Remarks

If the item identifier is passed as a parameter, a new Item object is created with that item identifier. If the item identifier already exists, the Item object corresponding to that item identifer is returned. If ItemId is omitted, Schedule+ creates a new object and generates an item identifier for it.

The following sample code creates a new item in the Events table:

Dim ObjEvent As Object
objEvent = objEventsTable.New

See Also

Tables


Reset

The Reset method sets the current item cursor to the top of a table.

Applies To

All Table objects

Syntax

objProjectsTable.Reset

Parameters

None

Remarks

For example, the next reference to an Item will return the first item in the table.

See Also

Tables


RollbackTransaction

The RollbackTransaction method rolls back a transaction.

Applies To

Schedule object

Syntax

objSchedule.RollbackTransaction

Parameters

None

Remarks

This method rolls back all changes to a schedule file since the last call to the BeginTransaction method. Open transactions should be rolled back on error conditions.

Note Every call to BeginTransaction must have a matching call to EndTransaction or RollbackTransaction.

See Also

BeginTransaction
EndTransaction


ScheduleForFile

The ScheduleForFile method returns a Schedule object when a schedule file name is specified.

Applies To

Application object

Syntax

objApplication.ScheduleForFile (FileName, OpenMode, Password, FileOpenFlags)

Parameters

FileName
Required. Specifies the name of the schedule file to open.
OpenMode
Optional. Specifies the mode in which to open the schedule.
Password
Optional. Specifies the password needed to gain access to the file.
FileOpenFlags
Optional. Specifies the mode in which to open the file.

Returns

Schedule object

Remarks

If the schedule file being opened has a password, it should be specified when attempting to open the file. Passing an incorrect password will return an error.

Note Passing an empty password (zero-length string), will match a nonexistent schedule password. If the password parameter is omitted, access to the schedule file will depend on the access permission granted to the logged-on user by the schedule file. For archives and backup schedule files, only a default access permission, read minimal, will be granted.

Note The ScheduleForFile method does not accept named arguments.

The OpenMode parameter can have the following values.

Value | Description
1 | Never creates an object.
2 | Creates a new schedule file, even if it already exists.
3 | Creates a new schedule file only if the object does not exist.

The FileOpenFlags parameter can have the following values.

Value | Description
1 | Read-only.
2 | Write.
4 | Denies others read access.
8 | Denies others write access.
32 | Creates (if needed) and opens the file for read and write access.
64 | Always creates and opens the file for read and write access.

See Also

ScheduleForUser


ScheduleForUser

The ScheduleForUser method opens a schedule file for a specific user.

Applies To

Application object

Syntax

objApplication.ScheduleForUser (UserAddress, UserName, ScheduleMode, OpenMode, UserEntryId)

Parameters

UserAddress
Required. Specifies the e-mail address of the user to which the schedule file belongs.
UserName
Optional. Specifies the display name of the user to which the schedule file belongs.
ScheduleMode
Optional. Specifies the mode in which to create the schedule file.
OpenMode
Optional. Specifies the mode in which to open the schedule file.
UserEntryId
Optional. Specifies the entry identifier of the user, which is required to open a schedule on the Microsoft Exchange server.

Returns

Schedule object

Remarks

The UserAddress parameter is always required. The UserName, ScheduleMode, OpenMode, and UserEntryId parameters are required only for Microsoft Exchange Server accounts; otherwise, they are optional.

Note The ScheduleForUser method does not accept named arguments.

The ScheduleMode parameter specifies what level of functionality the schedule should support. It can have one of the following values.

Value | Description
1 | Supports basic user information.
2 | Supports free/busy information.
3 | Supports Schedule+ 1.0-level functionality (appointments, tasks, and events).
4 | Supports Schedule+ 7.0-level functionality (appointments, tasks, events, tasks, contacts, and so on).

The OpenMode parameter can have the following values.

Value | Description
1 | Never creates an object.
2 | Creates a new schedule file, even if it already exists.
3 | Creates a new schedule file only if the object does not exist.

See Also

ScheduleForFile


SetChangeIndex

The SetChangeIndex method positions the cursor in a table.

Applies To

All Table objects

Syntax

objContactsTable.SetChangeIndex ChangeIndex

Parameters

ChangeIndex
Specifies the change index value.

Remarks

The SetChangeIndex method is used for synchronizing schedule files. It is not necessary to use this method on normal tables. The cursor is positioned so that the rows following the cursor have change indexes greater than the specified value, in ascending order.

See Also

Tables


SetProperties

The SetProperties method sets the values of one or more specified properties.

Applies To

Schedule and all Item objects

Syntax

objContact.SetProperties Arg1:=Value1, Arg2:=Value2, ..., ArgN:=ValueN

Parameters

Arg1, …, ArgN
Specifies one or more strings containing the names of properties to set.
Value1, …, ValueN
Specifies the values to which you want to set the properties.

Remarks

You can include any number of properties defined for an object and specify them in any order. When setting multiple properties on an object, calling the SetProperties method is faster than calling the Properties method multiple times.

After calling this method, the specified values are set on the Item object, but the data is not written to the item until the object is released or until the Flush method is called.

For single properties, you can also use the following syntax:

object.property = value

Note This method does not work with Visual Basic version 3.0.

See Also

Flush
GetProperties
Properties


SetRange

The SetRange method restricts a table to a date range.

Applies To

All Table objects

Syntax

objAppointmentsTable.SetRange StartDate, EndDate

Parameters

StartDate
Specifies the date on which the restriction starts.
EndDate
Specifies the date on which the restriction ends.

Remarks

If no parameters are passed, previous restrictions are removed. A call to the SetRange method also resets the cursor to the top of the table. The following sample code shows how both dates require an opening and closing # character:

objTable.SetRange #11/16/95#, #11/18/95#

Note This method must be called before using a merged table.

See Also

SetRestriction


SetRestriction

The SetRestriction method sets a restriction on a table.

Applies To

All Table objects

Syntax

objAppointmentsTable.SetRestriction Property, BoundaryValue, Comparison

Parameters

Property
Specifies the name or identifier of the property to which the restriction applies.
BoundaryValue
Specifies the value of the restriction.
Comparison
Specifies one or more characters that indicate the comparison to be evaluated against the BoundaryValue parameter.

Remarks

The SetRestriction method can be used only on tables that do not contain a merged list of single and recurring items. For example, this method can be invoked on the SingleAppointments and RecurringAppointments tables, but not on the Appointments table.

This method restricts the rows of the table to those meeting the specified criteria. For example, if Property is CityBusiness, BoundaryValue is Boston, and Comparison is ==, the available rows of the table will be contacts based in Boston, as shown in the following sample code:

objContactsTable.SetRestriction "CityBusiness", "Boston", "=="

If no parameters are specified, all previous restrictions are removed.

The Comparison parameter can have the following values.

Value | Description
== | Equal to
!= | Not equal to
> | Greater than
< | Less than
>= | Greater than or equal to
<= | Less than or equal to

See Also

SetRange


Skip

The Skip method skips a number of rows forward or backward in a table.

Applies To

All Table objects

Syntax

objTasksTable.Skip RowsToSkip

Parameters

RowsToSkip
Optional. Specifies the number of rows to skip.

Remarks

If the RowsToSkip parameter is not specified, the cursor is moved to the next item in the table.

See Also

Tables


Synchronize

The Synchronize method synchronizes the logged-on user’s local and server schedules.

Applies To

Schedule object

Syntax

objSchedule.Synchronize

Parameters

None

Remarks

This method only works when Schedule+ is running in group-enabled mode.

See Also

Schedule


Undo

The Undo method undoes the last operation performed on a schedule.

Applies To

Schedule object

Syntax

objSchedule.Undo

Parameters

None

See Also

ClearUndo
RollbackTransaction


Value

The Value method gets or sets a specified value in a property.

Applies To

All Property objects

Syntax

objProperty.Value (Index)

Parameters

Index
Specifies the index of the value you want to get or set.

Remarks

To get a property value, use this method on the right side of the equal sign in an expression. To set a property value, use this method on the left side of the equal sign in an expression. For example:

objSched.Name.Value

See Also

Count


Schedule+ Printing Model

This section describes the Schedule+ printing model. This model allows you to design complex page layouts representing different views of the schedule data in a simple text file.


Overview

The Schedule+ printing model formats printed information using different page sizes and formats. The application contains a print engine that can find print layouts and page formats in a directory and parse them at run time. Both the layout and the format are described by text files that have an extension of .PRT for the layout and .FMT for the format.

The layout specifies how items such as appointments, tasks, and calendars are laid out on a page. The format defines the size of the physical page, the number of virtual pages on a physical page, and so on.

The user interface lets you use a list box to select a format and a layout. Examples of formats are Daily and Trifold; examples of layouts are Normal and Avery.


Layout Description

The print layout is based on the concept of a view, which can be thought of as a way of looking at the schedule data. When you create a view, you must first define some basics such as the name of the view, the name of the preferred page format, what each page of a view represents (a month, a day, a week, and so on), and the size of the metapage.


The Metapage

The metapage is the logical coordinate system you use to place objects on the page layout. The coordinate system of the metapage is automatically scaled to the actual page size. For example, if you use a metapage of 100x100 pixels, you can work in percentages of the page. Metapage coordinates are expressed in the format (left, top, right, bottom), where all values are absolute coordinates. In the example of 100x100 pixels, all objects must be in the rectangle (0,0,100,100). An object in this page that exists from (0,0,30,100) would take up the top 30% of the page. If the page were actually 1000 pixels by 500 pixels, then the object would exist on the physical page in the rectangle (0,0,300,500).

Note All text in the print file must be in uppercase because the parser does not accept lowercase characters. The only exception to this rule is the use of mixed-case text within quoted strings and in comment lines.

The first line of the print file must start with the word VIEW. The VIEW command allows the print engine to verify that the file is in the expected format. If the first line is not in the following format, an error message dialog box appears and the printing is stopped:

VIEW "{view name}", "{format name}", "{view type}",{meta-x}, {meta-y}

where

{view name}
Specifies the name of the view.
{format name}
Specifies the name of the preferred page format for the the view (less than 40 characters in length). The preferred page format does not have to be available — if it is not found, a default format is used.
{view type}
Specifies the range of dates the print objects are given, and can have the following values.
View type | Description
DAILY (default) This value can be omitted, but a comma must be inserted in its place unless you are entering no other values on the line. If you eliminate a parameter and use a default, you must enter a comma to indicate a missing value.

When this view is printed for n days, it is iterated n times with the date range being a single day and incremented a day at a time.

WEEKLY | When this view is printed for n weeks, it is iterated n times with the date range being a week and incremented a week at a time. The start day is always the start of the week.
WORKWEEKLY | This view is a special form of WEEKLY that considers a week to be the days Monday through Friday. The start day is always the start of the work week.
MONTHLY | When this view is printed for n months, it is iterated n times with the date range being a month and incremented a month at a time. The start day is always the start of the month.
ALL | This value iterates the print view only once for the entire range being printed. This is useful for appointment text views or task views, where all the information is printed at once rather than in terms of time intervals.

{meta-x}, {meta-y}
Integers that describe the size of the metapage. The default is 100.

The following lines all illustrate a valid first line, and are equivalent:

VIEW "My Own View","Letter",DAILY,100,100
VIEW "My Own View","Letter",DAILY
VIEW "My Own View","Letter",100,100
VIEW "My Own View","Letter"

You can enter any text after the VIEW line. All characters outside quoted strings are ignored and any line beginning with a semicolon (;) is treated as a comment, as is anything between a semicolon and a new line.


Multiple Pages

The print view can be defined as multiple pages. The PAGE command breaks to a new page, and all objects defined after the PAGE command refer to the new page. However, the date is not automatically incremented.

A page can also be defined as a repeating page. Repeating pages repeat themselves until they are empty. These are useful when combined with OVERFLOW objects, because they allow all the overflow information to be printed. The OVERFLOW command converts a page to a repeating page. In general, the OVERFLOW command should appear before the first object on a given page.

Note The OVERFLOW command should not be confused with the OVERFLOW object.

An important consideration is that a repeating page must not contain any objects that produce overflow buffer items. If it has such objects, the page can generate more overflow buffer items while it is printing the buffer contents, and thus enter an infinite printing loop.


Print Objects and Properties

After specifying the view and metapage, you must describe the printable areas by placing objects such as appointments and tasks on the metapage. Several built-in objects exist for this purpose and are described in this section.

Most objects that are placed on the metapage print schedule information. If an object cannot fit all of its information into the printing area, any unprinted information can be put into an overflow buffer.

Objects can also have properties. The following built-in objects have several shared properties such as fonts and date formats. All these properties are consistent within objects, and all objects that support them use them in a similar fashion.

Object | Description
APPTS | Puts appointments into the overflow buffer.
BITMAP | Draws a bitmap.
CALENDAR | Prints a month calendar.
CARDLIST | Puts contacts into the overflow buffer.
EVENTS | Puts events into the overflow buffer.
LINE | Draws a line.
MONTH | Prints a user's appointments for a month.
OVERFLOW | Prints the contents of the overflow buffer.
RECTANGLE | Draws a shaded or unshaded rectangle.
SCHEDULE | Prints a user’s appointments in a graphical frame.
TASKS | Puts tasks into the overflow buffer.
TASKLIST | Puts tasks in a form of a list into the overflow buffer.
TEXT | Prints the text.
TIMEFRAME | Prints a time frame.

A detailed description of how to specify the following properties appears later in this section.

Property | Description
DATEFMT | Specifies a format for printing dates.
DELTAYMD | Changes the default printing date for the object.
OPTIONS | Lists the object-specific options.
OVERFLOW | Specifies an overflow buffer for use by the object.
RANGE | Specifies a time range for the object.
STYLE | Lists the fonts used by the object.
TIMEFMT | Specifies a format for printing times.
VALUE | Specifies a value for a text or bitmap object.

The following table indicates which properties are available for each object. A check mark means that the property is required for the object, a bullet means that the property is optional, and a blank space means that the property is not valid for the object.

Object | DATEFMT | DELTAYMD | OPTIONS | OVERFLOW | RANGE | STYLE | TIMEFMT | VALUE
APPTS | · | · | Ö | · | · | Ö | · |
BITMAP |  |  |  |  |  |  |  | Ö
CALENDAR |  | · |  |  |  | Ö |  |
CARDLIST |  |  | · | · |  | Ö |  |
EVENTS | · | · | · | · | · | Ö |  |
LINE |  |  |  |  |  |  |  |
MONTH |  | · |  | · | · | Ö | · |
OVERFLOW |  |  | Ö | · |  | Ö |  |
RECTANGLE |  |  | · |  |  |  |  |
SCHEDULE |  | · | Ö | · | · | Ö | · |
TASKS |  |  | Ö | · |  | Ö |  |
TASKLIST |  |  | Ö | · |  | Ö |  |
TEXT | · | · | · |  |  | Ö | · | Ö
TIMEFRAME |  |  | Ö |  | · | Ö |  |

An object is defined in a print view by the following line:

OBJECT {reserved},{object name},{left},{top},{right},{bottom}

where

{reserved}
Is reserved for future versions of Schedule+ and should be left blank.
{object name}
Specifies the name of the object being defined.
{left}, {right}, {top}, and {bottom}
Specify the printable area for the object in metapage units.

Properties associated with the object follow the object line. Indenting the lines that specify properties makes the .PRT file more readable.


Objects

This section provides a detailed description of the objects. The supported properties are shown after each object. However, only those properties whose parameters are object-dependent are described.


APPTS

The APPTS object puts the appointments that are in the date and time range directly into the overflow buffer. This feature allows the .PRT file designer to create layouts in which the appointments flow through areas of the page. This is accomplished by printing the overflow buffer using the OVERFLOW object.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for the appointment text.
<style2> | Used for the time.
<style3> | Used for the header text.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
LOCATION | NONE | Shows the appointment location.
DAY | WEEK | NONE | Inserts page breaks into the overflow buffer after every day or after the end of a week. If the overflow buffer is printed, the page break is used if possible.
0 | 1 | When set to 1, the appointments put in the overflow buffer are for a single day rather than the entire range. A value of 0 specifies the entire range.
<integer> | Uses a number greater than zero to force a heading to be put in the overflow buffer before any overflow appointments. The heading text is Other Appointments. The value of this number specifies the thickness of the line preceding the text. If the overflow buffer already contains text, the heading is omitted. This option makes the Daily Dynamic view possible.
0 | 1 | When set to 1, inserts a date header for each day.


BITMAP

The BITMAP object inserts a graphical object on the page. This object is stretched to fit in the defining rectangle.

The only property is VALUE, which is a string that specifies the file (a device-independent bitmap) from which to load the bitmap.


CALENDAR

The CALENDAR object prints a small calendar for the print date. The calendar automatically scales to fit in the defining rectangle and produces an error if there is not enough room in the rectangle. The calendar does not have a monthly heading, but you can add one separately as a TEXT object.

This object requires a STYLE property with the following parameter.

Parameter | Description
<style> | Used for the calendar text.

The OPTIONS property, if present, requires the following parameters.

Parameter | Meaning
0 | Never highlight the current date.
1 | Highlight today’s date only.
2 | Highlight the current date.


CARDLIST

The CARDLIST object puts a list of contacts into the overflow buffer.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for the text.
<style2> | Used for the heading text.
<style3> | Used for the outline text.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
BREAK | NONE | Inserts a page break after each item.
NOHEADER | NONE | Suppresses the name of the column preceding each value, such as First Name, Last Name, and so on.


EVENTS

The EVENTS object puts a list of events into the overflow buffer.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for the event text.
<style2> | Used for the date.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
<integer> | Uses a number greater than zero to force a heading to be put in the overflow buffer before any overflow events. The heading text is Other Events. The value of this number specifies the thickness of the line preceding the text. If the overflow buffer already contains text, the heading is omitted. This option makes the Daily Dynamic view possible.
0 | 1 | When set to 1, the events put in the overflow buffer are for a single day rather than the entire range.


LINE

The LINE object places on the page a one-pixel-wide line that stretches along the diagonal of the rectangle.


MONTH

The MONTH object prints an entire monthly calendar in the rectangle, and fills in each day with its appointments. Each appointment occupies two lines: the first line has the start and end times, and the second line has as much appointment text as fits. No location information is printed.

This object always prints the month containing the current print date. For example, if the print date is 7/14/90, it prints all of July 1990.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for the appointment text.
<style2> | Used for the time.
<style3> | Used for the headers.
<style4> | Used for overflow items.


OVERFLOW

The OVERFLOW object prints all of the items in the overflow buffer created by objects on the current page. There may also be overflow from previous pages if it has not been explicitly deleted. If an overflow property is specified, this object prints the items in that overflow. You can also specify the space requirements for the overflow buffer objects.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
FULL | MINIMAL | When set to FULL, prints the full text of the items. This option should be used in conjunction with repeating pages because long items can overflow a single page. When set to MINIMAL, specifies that appointments and tasks occupy a minimal amount of space, usually two lines per appointment and one line per task. This option prints ellipses (…) at the end of the line.
<integer> | A number that specifies how much to shift the text. You can use this option to put both header text and task horizontal lines into the overflow buffer and then shift the text. The overflow object can distinguish between text and non-text items.
CLEAR | Specifies that the overflow buffer should throw away any previously collected objects when moving to a new page. If this option is not set, any unprinted items in the overflow buffer goes to the next page.
CONSUME | Specifies that the overflow buffer should discard any unprinted objects left after it prints all the objects that it can print. This option is useful when there are multiple unrelated overflow buffers on a single page. If this option is not set, any unprinted items in the overflow buffer go to the next page.

The STYLE property is optional for this object. If included, it is used to print the string “More Items...” in any case where the OVERFLOW object is unable to print all the overflow buffers within the given rectangle. The STYLE property should only be specified when the OPTIONS property is set to MINIMAL.


RECTANGLE

The RECTANGLE object draws a rectangle on the page that fills the specified coordinates.

The OPTIONS property, if present, requires the following parameter.

Parameter | Description
FRAME | GRAY | BLACK | FRAME draws a thin black line around the border of the rectangle, GRAY draws a shaded rectangle, and BLACK draws a black rectangle on the page.


SCHEDULE

The SCHEDULE object prints a graphical view of a day’s appointments, similar to what is shown in the appointment book. It does not place a list of times down the side — you can do that by using a TIMEFRAME object.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for the appointment text.
<style2> | Used for the time.
<style3> | Used for the header text.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
<integer> | Specifies how many appointments can overlap each other in the output. The visual appointment book has a limit of 6, but the printout can have up to 16. Appointments omitted because of insufficient overlap are placed in the overflow buffer.
<integer> | Specifies the number of time divisions per time slot, in minutes. For example, 30 specifies the default behavior.
LOCATION | NONE | Shows the location for the appointment. Appointments that are put in the overflow buffer also show the location.
OVERFLOW | NONE | Puts any unprinted entries into the overflow buffer.
<integer> | Uses a number greater than zero to force a heading to be output to the overflow buffer before any overflow appointments. The heading text is Other Appointments. The value of this number indicates the thickness of the line preceding the text. If the overflow buffer already contains text, the heading is omitted. This option makes the Daily Dynamic view possible.


TASKS

The TASKS object puts into the overflow buffer all the text required to show the task list. Filtering and outlining options are taken from the task grid, if one is available. Otherwise, it defaults to outline by priority and filter to show all tasks.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for task text.
<style2> | Used for tasks that are past due.
<style3> | Used for projects.
<style4> | Used for outline rows.
<style5> | Used for heading text.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
MINIMAL | NONE | Specifies that the minimum fields are visible. Otherwise, the standard set of fields is used.
<integer> | Specifies whether to have a line across the outline levels. This number indicates the level of outline at which we want the line to apprear — for example, 1 = the first outline level 0 = disables the line
<integer> | Uses a number greater than zero to force a heading to be put in the overflow buffer before any overflow tasks. The heading text is Other Tasks. The value of this number indicates the thickness of the line preceding the heading text. If the overflow buffer already contains text, the heading is omitted. This option makes the Daily Dynamic view possible.


TASKLIST

The TASKLIST object puts all the tasks into the overflow buffer as a list. Each task is in the form of a list, with each line specifying a separate column. The columns in the list are taken from the columns shown in the task grid, if available; otherwise a default is used.

This object requires a STYLE property that has the following parameters.

Parameter | Description
<style1> | Used for the task list text.
<style2> | Used for the header text.
<style3> | Used for the outline row.

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
BREAK | NONE | Inserts a page break after each item.
NOHEADER | NONE | Suppresses the name of the column preceding each value, such as Text, Priority, and so on.


TEXT

The TEXT object allows the user to put a line of text on the page in a specified area. This object must always specify a VALUE property with a string that can contain one or more of the following metavariables.

Metavariable | Description
&USERNAME | Prints the user’s name.
&CURDATE | Prints the current date.
&CURTIME | Prints the current time.
&PRINTDATE | Prints the date for which the object is printed.
&PAGENUM | Prints the page number.
&TIMEZONE | Prints the current time zone.
&& | Prints an ampersand (&).

The OPTIONS property, if present, requires the following parameters.

Parameter | Description
HCENTER | LEFT | RIGHT | Specifies the horizontal justification.
VCENTER | NONE | Specifies the vertical justification.
ELLIPSIS | NONE | Adds an ellipsis to the end of a string if the entire string does not fit within the described rectangle. Multiline text prints if there is room in the rectangle, but using VCENTER on a multiline text block can produce unpredictable results.


TIMEFRAME

The TIMEFRAME object is closely related to the SCHEDULE object. Its only purpose is to create views which have several schedule objects on the same time frame next to each other.

This object requires a STYLE property with the following parameter.

Parameter | Description
<style> | Used for the time frame text.

The OPTIONS property, if present, requires the following parameter.

Parameter | Description
<integer> | Specifies the number of time divisions per time slot, in minutes.


Properties

This section describes the Schedule+ printing properties. Most properties are used in a consistent manner and always take the same parameters. However, in some cases the parameters are dependent on the object for which the property is being specified. Be careful to specify the correct number and types of parameters. Otherwise, an error message appears when the user tries to print.


DATEFMT

The DATEFMT property specifies the date format for any object that outputs a date. This property has the following format:

DATE    {string}

The string specifies one of the following formats in which to print the date.

Specifier | Item | Values
M | Month | 1-12
MM | Month | 01-12
MMM | Month | Jan-Dec
MMMM | Month | January-December
d | Day | 1-31
dd | Day | 01-31
ddd | Day | Mon-Sun
dddd | Day | Monday-Sunday
yy | Year | 00-99
yyyy | Year | 1900-2040

The following examples illustrate the different formats.

Format | Translates to
d MMMM,yyyy | 14 July, 1990
dddd, MMMM d, yyyy | Thursday, July 14, 1990
dd-MM-yyyy | 14-07-1990


DELTAYMD

For each page there is a specific date called the print date. For the DAILY type view, the print date is the date the user enters in the Print dialog box, and is incremented by one day for each page printed.

Most objects use the print date to output information. Using this property, the print date can be modified on a per-object basis. This property has the following format:

DELTAYMD {count},DAY|WEEK|MONTH|YEAR

This format changes the print date by the specified count (positive or negative). For example, the following syntax prints information for the day after the print date:

DELTAYMD    1, DAY

The following syntax prints information for the same day two weeks ago:

DELTAYMD    -2, WEEK


OPTIONS

The OPTIONS property allows each object to specify additional options. The required parameters for this property on each object are different.

For more information on these required parameters, see the applicable object under Print Objects and Properties.


OVERFLOW

The OVERFLOW property allows you to specify a named overflow buffer. Normally, overflow buffers are unnamed — that is, the name is a null string (““). However, objects can put text into explicit overflow buffers by specifying this property. The only argument is a quoted string specifying the name of the buffer, which should be less than 32 characters.

OVERFLOW {string}


RANGE

You can use the RANGE property to specify a time range for some objects. For example, a SCHEDULE object must always have a time range that specifies the times between which appointments are printed. An APPTS object can also have a time range, but it might be one that specifies appointments before a certain time.

The range for which a set of a appointments prints can be changed by using the RANGE command, which has the following format:

RANGE    BEFORE,{time},AND|OR,AFTER,{time}

Times are specified in 24-hour format, with a colon (:) as the separator. The AND/OR specifier allows the range to be AFTER time x AND before time y for an inclusive range, or BEFORE time y OR AFTER time x for a fragmented range.

In addition to specifying a time, you can also use the STARTTIME or ENDTIME parameter to specify the user's preferred start-of-work-day and end-of-work-day. The following syntax prints all the appointments outside of the start or end time:

RANGE    BEFORE,STARTTIME,OR,AFTER,ENDTIME


STYLE

Most objects print some text and therefore require a font specification. The font specification is defined in terms of a style. Styles are defined in the page format files in terms of a font name, family, point size, and so on. This is because the physical page size changes depending on the page format selected by the user, and fonts also need to change.

The font specification has the following format:

STYLES    {style1}, {style2}, ... ,{styleN}

The objects for which fonts are specified use the style list in different ways. For example, the TEXT object requires only a single style that specifies the font in which to print the text. However, the TASK object requires three styles specified.

The required parameters for this property on each object are different. For more information on these required parameters, see the applicable object under Print Objects and Properties.


TIMEFMT

The TIMEFMT property specifies a format for printing the time. A separator string can also be defined to separate the time from any following text, such as appointment text. The format for this property is:

TIME {number}, {separator string}

The different time formats are specified by consecutive integers starting at 0. The integers specifying a time format are as follows.

Integer Value
0 (default) Standard (3:45 p.m. or 15:45 hrs)

This is the time format specified in the Windows Control Panel.
1 Standard No Trailer (3:45 or 15:45)

This format also uses the Windows Control Panel, but does not apply the trailers.
2 Modified Standard (Vanishing trailer)

In this format, the object keeps track of the times it has already printed. It prints a trailer only for the first a.m. and first P.M. appointments it prints in 12-hour mode, or for the first appointment only in 24-hour mode.

For example, in a list of appointments, if you have appointments at 8 A.M., 9 A.M., 10 A.M., 11 A.M., 12 P.M. and 1 P.M., the times are printed as: 8 A.M., 9, 10, 11, 12 P.M., and 1.
3 Hour Only (3 or 15)

This format always prints the number associated with the hour (3:45 appears as 3).
4 Hour only when minutes != 0 ( 3:45 or 15:45)

This format prints the hour only when the minutes are zero, and the full time otherwise (3:45 appears as 3:45, but 4:00 appears as 4).

Formats 3 and 4 are space savers. If necessary, you can limit the amount of space taken up by the time to leave more space for text.


VALUE

Some objects have a basic value that is specified using the VALUE property. For example, a text object has a string as its value. For the text object, the property is specified as:

VALUE    "This is a string to be printed."


Paper Format Description

This section describes the paper format description file format. Each paper format is described by a text file that is parsed during run time to handle features such as number of virtual pages on a physical page, their placement on the physical page, and so on. This is a flexible mechanism that allows you to describe any available paper format.


Comments

Comment lines are any lines that start with a semicolon (;). Tabs, spaces, and new lines are all considered to be white space.


Header

The header describes the basic page format. The following lines must be specified in the order shown, for example:

FORMAT "Avery 41-357", 750, 1000
MARGINS 1, 0, 5, 0, 5, 0, 5, 0, 5, MIRROR
FONTSIZE 0
HINTS 1
PAGESIZE 325, 675


FORMAT

The FORMAT line specifies the name of the page format in quotes, followed by the size in logical units of the physical page. The size of the physical page is the size within the margins. The logical units can be arbitrary integers. However, to avoid overflow, it is recommended that you not use large numbers.

An orientation is associated with the physical page size. This orientation describes the primitive page format orientation. The default is PORTRAIT. It can be changed to landscape by appending the keyword LANDSCAPE after the physical page size, separated by a comma. The primitive page format orientation should not be confused with the user-specified orientation, which is usually specified in the Print dialog box.


MARGINS

The MARGINS line specifies the default margins. The first number specifies the margin type, which is the same as the MTYP in the DEVMODE structure. The example in the Header section shows that 1 represents one inch. The next eight numbers are the actual margins in the following order: top, left, right, bottom.

Each margin is represented by a pair of numbers. The first number is the integer part and the second number is the fractional part. In the example above, all the margins are 0.5 inches.

You can specify the optional MIRROR keyword after the margins, separated by a comma. This keyword indicates that the page format must have mirrored margins. In this case, the user-specified mirror margins setting is ignored.


FONTSIZE

The FONTSIZE line consists of a single number that determines the preferred font size for the actual view. The FONTSIZE line can have one of the following values, which you can override in the Print dialog box.

Value | Description
0 | Small
1 | Medium
2 | Large

See the example in the Header section for the correct syntax.


HINTS

The HINTS line consists of a single number that determines the preferred duplex printing mode. The HINTS line can have one of the following values, which you cannot override in the Print dialog box.

Value | Description
0 | No preference
1 | Long side duplex
2 | Short side duplex

The HINTS line should be set to 0 for formats that have only a single virtual page, 2 for formats specified in LANDSCAPE mode, and 1 for all other formats.

See the example in the Header section for the correct syntax.


PAGESIZE¦

The PAGESIZE line specifies the size in logical units of the virtual page. The paper format might require multiple virtual pages on a single physical page, but they must all be the same size.

See the example in the Header section for the correct syntax.


Style Definitions

The style definitions follow the header. Style definitions are used by print layouts and are unique to page formats. The page format determines the required font size.

Note A page format must include all of the styles that a view requires; otherwise the view will not print onto that page format. Therefore, it is important to define a large set of styles. See the list of recommended formats later in this section.

The style definitions start with the keyword STYLE, and are followed by specifications for each style. They look like this:

STYLE
{style name}, ["{friendly name}"], "{font name}", SWISS | ROMAN | MODERN | DECORATIVE | DONTCARE, {point-size-small}, {point-size-medium}, {point-size-large} [, BOLD | ITALIC | STRIKEOUT]

Point sizes for small, medium, and large must be specified to support the user interface, which can prompt for either the small font set, medium font set, or large font set. As a guideline, only styles that are used by appointment or task text should have different sizes for small, medium, and large. Style names should not be the same as other keywords.

The friendly name is a name that describes the style. For Schedule+ this entry should be Null.

The style specifications are repeated as many times as necessary. The keyword STYLE does not need to be repeated.


Page Descriptions

Page descriptions, each of which describes a virtual page, follow the style definitions. A maximum of four virtual pages can be specified for a single side of the physical page. Most complex page formats must have virtual pages explicitly defined for duplex printing.

The page order, the page location, or the number of pages can change on the duplex side. If the duplex side needs to be described differently, a maximum of eight virtual pages can be described.

For page order, you can think of the physical pages as moving through the print engine in a given order depending on the print view, the print range, and the specified Include Blank Pages flag. For example, printing the daily view for four days normally moves four pages, ordered 1, 2, 3, and 4, through the print engine. For a given paper format, the page description is flexible enough to print pages 2 and 3 on the first side of the page, and 1 and 4 on the duplex side of the page.

Each page description has the following format:

PAGE 300, 500
PAGEINFO 1, 1, 0
INVERT 0, 0

The following example describes a number of different formats. For a normal page, it is only necessary to describe a single page, as follows:

PAGE 0, 0
PAGEINFO 1, 1, 0
INVERT 0, 0

Note It is not necessary to explicitly define the page in duplex mode.


PAGE

The PAGE line describes the location of the virtual page within the logical page. The examples in the Page Descriptions section show that the page is located at the x, y coordinate 300, 500.


PAGEINFO

The PAGEINFO line specifies information required to place the page on the correct side. The examples in the Page Descriptions section show that the first number (1) is the page order number for a simplex page, the second number (1) is the page order number for a duplex page, and the third number (0) indicates to which side (0 = first side, 1 = second side) this page description applies.

If a page is intended to be for the second side in duplex mode, then the first number must be zero.

See INVERT for more information on pages.


INVERT

The INVERT line determines whether to invert a given page and can have one of the following values.

Value | Description
0 | Normal
1 | Inverted

The examples in the Page Descriptions section show that the first number is for the page in simplex mode and the second number is for the page in duplex mode.


Schedule+ Error Codes

This section lists the Schedule+ error codes and their meanings.

Error Code | Description
0x80040820 | A problem occurred while accessing the disk.
0x80040824 | The specified directory name is not valid.
0x80040826 | The specified network path is not valid.
0x80040828 | The filename is too long.
0x8004082A | The session was cancelled.
0x8004082F | A problem occurred while writing to the disk.
0x80040831 | The drive cannot find the sector requested.
0x80040832 | Too many files opened for sharing.
0x80040834 | Insert a disk into the disk drive
0x80040837 | A problem occurred while connecting to the network. See your administrator.
0x80040843 | Invalid access code.
0x80040844 | Invalid data.
0x80040845 | Invalid drive.
0x80040847 | Not same device.
0x80040849 | Bad disk unit.
0x8004084A | Invalid disk command.
0x8004084B | Data error (cyclic redundancy check).
0x8004084D | A duplicate name exists on the network.
0x8004084F | Network request not supported.
0x80040850 | Network busy.
0x80040851 | Cannot make directory entry.
0x80040853 | Invalid password.
0x80040864 | Logon failure: account logon time restriction violation.
0x80040867 | Already logged on.
0x80040869 | Not logged on.
0x8004086C | The specified user does not exist.
0x8004086D | There are currently no logon servers available to service the logon request.
0x80040871 | The user's account has expired or the password for the account has expired.
0x80040872 | No account balance or no credit in user account.
0x80040876 | Unauthorized login station.
0x80040877 | Not enough quota is available to process this command.
0x800408E0 | The file could not be accessed.
0x800408E5 | The file version is not supported.
0x800408E6 | The file version is not supported.
0x800408EB | The schedule file has been damaged. See your administrator.
0x800408EC | The file is locked by a process or another user.
0x80040900 | The user information is not valid and could not be processed.
0x80040907 | No server schedule is available.
0x800409A7 | To create recurring appointments, you must clear the Disallow Recurring Appointments field.
0x800409A8 | To create or modify recurring unbounded appointments, you must clear the Disallow Overlapping Appointments fields.
0x80040A80 | End of table.
0x80040A82 | The transaction could not be completed.
0x80040A84 | The Undo action could not be completed.
0x80040A87 | File locking is not enabled. You must install SHARE.EXE.
0x80040A89 | The network could not be accessed. See your administrator.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Required and Optional Message Properties

Every object has a set of required properties and a set of optional properties. Depending on the object, the service provider supplying the implementation, and the property, a MAPI client can have read/write or read-only access to a property in either set. A required read/write property is a property that must exist on an object before it can be successfully saved with the IMAPIProp::SaveChanges method. A required read-only property is a property that always exists on an object and is therefore always available by calling either IMAPIProp::GetProps or IMAPIProp::OpenProperty. Read-only properties are typically computed by the service provider supplying the object implementation.

In contrast, MAPI clients cannot expect optional properties to be available or set to valid values. When a MAPI client or service provider calls GetProps, asking for an unavailable property, it succeeds with the warning MAPI_W_ERRORS_RETURNED. However, a call to the MAPI method IMAPIProp::OpenProperty fails with the error MAPI_E_NOT_FOUND. MAPI clients and service providers must verify that a requested property is returned before attempting to use it.

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 or not a valid value exists for a column depends on whether or not 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 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.

To determine exactly which properties are currently set for an object, MAPI clients and service providers can call IMAPIProp::GetPropList. GetPropList 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 guesswork.


Properties Set at Message Creation

A client application can create a message with IMAPIFolder::CreateMessage, set its properties with IMAPIProp::SetProps, and add attachments to it. It can then call IMAPIProp::SaveChanges to save the message to a folder, or send the message immediately by calling IMessage::SubmitMessage. (Calling the SubmitMessage method also saves changes.) This step is message submission, which requests that copies of the message be placed in the recipients’ mailboxes.

If you call the IMAPIFolder::CreateMessage method in a folder, the message properties in the following two tables will be set automatically. This occurs even if you have not called IMAPIProp::SetProps, IMAPIProps::DeleteProps, or IMessage::ModifyRecipients. Some of values for these properties (such as PR_CREATOR_ENTRYID) are assigned by the information store provider, some are default values (such as PR_ACCESS_LEVEL) inherited from the folder the message was created in, and some are derived from other values. In other words, values for these properties are assigned automatically, so you need not set them explicitly.

The properties in the following table are defined in the EDKMDB.H file.

Initial Message Properties Defined by Microsoft Exchange Server

Property Designation | Description
PR_CREATOR_ENTRYID | Contains the address book entry identifier of the user who created the message.
PR_CREATOR_NAME | Specifies the display name of the user who created the message.
PR_LAST_MODIFIER_ENTRYID | Specifies the entry identifier of the last person to modify the message.
PR_LAST_MODIFIER_NAME | Contains the display name of the last person to modify the message.

The following message properties are declared by MAPI in MAPITAGS.H. In their Microsoft Exchange Server implementation, most of these properties are read-only because they are derived or computed values.

Initial Message Properties Defined by MAPI

Property Designation | Description
PR_ACCESS | Contains a bitmask of flags indicating the operations the client application can perform on the open object.
PR_ACCESS_LEVEL | Contains a bitmask of flags indicating the level at which the client application can access the open object.
PR_CREATION_TIME | Contains the creation date and time for a message.
PR_DISPLAY_BCC | Contains an ASCII list of the display names of any blind copy (BCC) message recipients, each separated by a semicolon (;).
PR_DISPLAY_CC | Contains an ASCII list of the display names of any carbon copy (CC) message recipients, each separated by a semicolon (;).
PR_DISPLAY_TO | Contains an ASCII list of the display names of the primary (To) message recipients, each separated by a semicolon (;).
PR_HASATTACH | Contains TRUE if a message contains at least one attachment.
PR_IMPORTANCE | Contains a value indicating the message sender's opinion of the importance of a message.
PR_LAST_MODIFICATION_TIME | Contains the date and time the object was last modified.
PR_MAPPING_SIGNATURE | Contains the mapping signature for named properties of a particular MAPI object.
PR_MDB_PROVIDER | Contains a provider-defined identifier that indicates the type of information store.
PR_MESSAGE_CLASS | Contains a text string that identifies the sender-defined message class, such as IPM.
PR_MESSAGE_FLAGS | Contains a bitmask of flags indicating the current state of a message object.
PR_MESSAGE_SIZE | Contains the sum (in bytes) of the sizes of all properties on a message object.
PR_OBJECT_TYPE | Contains the type of an object.
PR_PARENT_ENTRYID | Contains the entry identifier of the folder containing a folder or message.
PR_SEARCH_KEY | Contains a binary-comparable key that identifies correlated objects for a search.
PR_SENSITIVITY | Contains a value indicating the message sender's opinion of the sensitivity of a message.
PR_STORE_ENTRYID | Contains the unique entry identifier of the information store in which an object resides.
PR_STORE_RECORD_KEY | Contains the unique binary-comparable identifier (record key) of the information store in which an object resides.

In addition to the properties listed in the preceding table, the following properties are present on a message if you call IMAPIFolder::CreateMessage in a public folder: PR_CONVERSATION_INDEX, and PR_REPLICA_SERVER, and PR_CONVERSATION_TOPIC.

If you immediately call IMAPIProp::SaveChanges after creating a message, two more read-only MAPI properties are added: PR_ENTRYID and PR_RECORD_KEY.


Object(OR-Name)

An O/R name consists of either a Directory Service Distinguished Name (DS-DN) or an O/R address. Thus if the DS-DN attribute has a value assigned, all values assigned to all other attributes (which compose an O/R address) are meaningless; but if the DS-DN attribute has no value assigned, then values should be assigned to at least some of the remaining attributes.

This OM object declaration is based on Table 57 of the X/Open X.400 API Specification, Version 2.0. Consult that specification for detailed descriptions of the meaning of each of the attributes in an O/R Address. For consistency with that specification we store domain-defined attributes in eight "small" multi-valued attributes of type String(Teletex) instead of in one "big" multi-valued attribute of type Domain-Defined-Attribute. But in a departure from X.400, instead of allowing Teletex or Printable strings as values for certain attributes, we allow only one of these two types per attribute.

Package

This OM object is defined in the MSMSG package. It cannot be used unless the MSMSG package is loaded.

OM object declaration (in tabular form): OR-Name Attributes


String(Teletex)

This syntax is used for string-valued attributes where lower-case and upper-case letters are considered equal for comparisons (e.g. "DUNDEE" and "Dundee" match). Strings stored with this syntax retain their upper- and lower-case letters; only the matching rule is different. It corresponds to X.500's Case-Ignore-String-Syntax.

Note that in a deviation from X.500 we also substitute this syntax for Telephone-Number-Syntax. Thus unlike X.500, our Directory Service will say that the telephone numbers "555-1212" and "5551212" are unequal, since they are seen only as strings. This was done only to reduce development effort, not because of any desire by Microsoft to deviate on this point.

Value checking

The DS will accept any contents for a Teletex string; it will not attempt to verify that they are indeed printable. Nor will it actually perform a case conversion: as specified by X.500, it will store values as supplied without upper-casing or lower casing them. Individual attribute types may associate a minimum and maximum size with any string, and those size limits are enforced; any value outside the legal size range will not be accepted.

OM SYNTAX: String (Teletex)

MATCHES FOR EQUALITY SUBSTRINGS APPROXIMATE

::= { ms-AttributeSyntax 4 }


OR-Name Attributes

 | Value | Value | Value
Attribute | Syntax | Length | Number
DS-DN | Object (DS-DN) | - | 0-1
Country-Name | String (Printable) | 2-3 | 0-1
ADMD | String (Printable) | 0-16 | 0-1
PRMD | String (Printable) | 1-16 | 0-1
Organization-Name | String (Teletex) | 1-64 | 0-2
Organizational-Unit Name-1 | String (Teletex) | 1-32 | 0-2
Organizational-Unit Name-2 | String (Teletex) | 1-32 | 0-2
Organizational-Unit Name-3 | String (Teletex) | 1-32 | 0-2
Organizational-Unit Name-4 | String (Teletex) | 1-32 | 0-2
MHS-Common-Name | String (Teletex) | 1-64 | 0-2
Surname | String (Teletex) | 1-40 | 0-2
Given-Name | String (Teletex) | 1-16 | 0-2
Initials | String (Teletex) | 1-5 | 0-2
Generation | String (Teletex) | 1-3 | 0-2
Domain-Type-1 | String (Teletex) | 1-8 | 0-2
Domain-Type-2 | String (Teletex) | 1-8 | 0-2
Domain-Type-3 | String (Teletex) | 1-8 | 0-2
Domain-Type-4 | String (Teletex) | 1-8 | 0-2
Domain-Value-1 | String (Teletex) | 1-128 | 0-2
Domain-Value-2 | String (Teletex) | 1-128 | 0-2
Domain-Value-3 | String (Teletex) | 1-128 | 0-2
Domain-Value-4 | String (Teletex) | 1-128 | 0-2

::= { ms-attributeSyntax 1 }


String(Numeric)

In this syntax strings match as in String(Printable), except that in a deviation from X.500, all space characters are ignored in comparisons. Corresponds to X.500 Numeric-String-Syntax. The Touchdown DS does not do value checking to ensure that only numerals and spaces appear in values of this syntax.

Value checking

The DS will accept any contents for a numeric string; it will not attempt to verify that they are indeed numeric. Individual attribute types may associate a minimum and maximum size with any string, and those size limits are enforced; any value outside the legal size range will not be accepted.

OM SYNTAX: String (Numeric)

MATCHES FOR EQUALITY SUBSTRINGS

::= { ms-AttributeSyntax 6 }


String(IA5)

This syntax is used for string-valued attributes where lower-case and upper-case letters are considered equal for comparisons (e.g. "DUNDEE" and "Dundee" match). Strings stored with this syntax retain their upper- and lower-case letters; only the matching rule is different. It corresponds to X.500's Case-Ignore-String-Syntax.

Value checking

The DS will accept any contents for an IA5 string; it will not attempt to verify that they are indeed printable. Nor will it actually perform a case conversion: as specified by X.500, it will store values as supplied without upper-casing or lower casing them. Individual attribute types may associate a minimum and maximum size with any string, and those size limits are enforced; any value outside the legal size range will not be accepted.

OM SYNTAX: String (IA5)

MATCHES FOR EQUALITY SUBSTRINGS APPROXIMATE

::= { ms-AttributeSyntax 4 }


String(Octet)

This consists of a size count (number of octets) followed by a series of octets. An octet is an 8-bit byte, so a series of octets is a string of binary data. Corresponds to X.500's Octet-String-Syntax.

Value checking

Any octet string is accepted. Any value which does not contain enough bytes to hold the count and data portions of an OM octet string will not be accepted.

OM SYNTAX: String (Octet)

MATCHES FOR EQUALITY SUBSTRINGS ORDERING

::= { attributeSyntax 10 }


Object(DS-DN)

This syntax is for a directory service distinguished name. In other words, an attribute with this syntax gives the name of an object in the directory service. X.500 calls it Distinguished-Name-Syntax. This syntax is defined in XDS as an OM class, the sole subclass of the Name OM class.

Value checking

The DS will not accept a value for this attribute which could not possibly be a distinguished name in some X.500 directory service.

XDS OM object declaration:

RDNs: Object(DS-RDN), 0-n values

MATCHES FOR EQUALITY

::= { attributeSyntax 1 }


String(Object Identifier)

This syntax is used for OID's.

Value checking

The DS will not accept a value for this attribute which could not possibly be a syntactically correct OID.

objectIdentifier

OM SYNTAX: String (Object Identifier)

MATCHES FOR EQUALITY

::= { attributeSyntax 2 }


String(UTC Time)

This syntax stores date and time in a single string. Corresponds to X.500's UTC-Time-Syntax.

The string format is defined in X.208 section 33.3. It consists of three concatenated parts: (1) YYMMDD; (2) hhmm or hhmmss (both are acceptable); and (3) "Z" to indicate that the time given is coordinated universal time, or "-HHMM" to indicate that the time given is local time which is HHMM slower than universal time, or "+HHMM" to indicate that the time given is local time which is HHMM faster than universal time. Note that the first two digits of the year are not stored in this string but can be easily deduced (at least until the year 2080 or so).

Some example legal values are "9101311455Z", "910131145503Z", "9101314455-0500", "910131145503+0130". This string is stored as single-byte ASCII characters, and no code page number is stored with it.

Although ordering is supported, in a deviation from X.500 it is done only as an ASCII case-ignore string sort (like String(Teletex)), not by properly interpreting the meaning of the strings.

Value checking

Any valid String(Teletex) value is accepted; no attempt is made to ensure that the string contains a valid time string.

OM SYNTAX: String (UTC Time)

MATCHES FOR EQUALITY ORDERING

::= { attributeSyntax 11 }


String(Printable)

This syntax is used for string-valued attributes where upper and lower case are considered unequal for comparisons (e.g. "DUNDEE" and "Dundee" do not match). It corresponds to the X.500 string syntaxes called Printable-String-Syntax and Case-Ignore-String-Syntax.

Value checking

The DS will accept any contents for a Printable-string; it will not attempt to verify that they are indeed printable. Individual attribute types may associate a minimum and maximum size with any string, and those size limits are enforced; any value outside the legal size range will not be accepted.

OM SYNTAX: String (Printable)

MATCHES FOR EQUALITY SUBSTRINGS

::= { ms-AttributeSyntax 3 }

Where a syntax is defined here as a PrintableString, it is implemented by the Touchdown Directory Service as an SBCS/DBCS text string (which may have a code page number associated with it). When a string is stored, the client's main code page number is stored with it.

Note that X.208 defines the PrintableString data type as using only the set of characters listed in Table 5/X.208:

A..Z

a..z

0..9

space

' ( ) + , - . / : = ?

Thus when the DS exchanges data with non-Touchdown DS's, some strings may not be translatable to the foreign DS. In another deviation from X.500, the Touchdown DS does not attempt to remove or compress multiple blanks supplied in string values. Thus "a b" and "a b" will be stored differently and will not match for equality.


Boolean

Value checking

As per the XDS specification, the DS will only accept a signed 32-bit value for this syntax, and on matching it will treat zero as false and all non zero values as true.

OM SYNTAX: Boolean // true if and only if non zero

MATCHES FOR EQUALITY

::= { attributeSyntax 8 }


Integer

Value checking

As per the XDS specification, the DS will only accept a signed 32-bit value for this syntax. (Of course unsigned 32-bit values can be stored as signed 32-bit values, but when matching for ordering, they will be treated as signed 32-bit values.)

OM SYNTAX: Integer // 32-bit signed int

MATCHES FOR EQUALITY ORDERING

::= { attributeSyntax 9 }

In ASN.1 the type INTEGER is a variable-length octet string interpreted right-to-left. But in the syntax definitions below, INTEGER is a four-byte signed binary integer as per the OM specification.


String(Unicode)

This object is undefined.


Enumeration

This object is undefined.


Object(Presentation-Address)

This object is undefined.


Object(Replica-Link)

This object is undefined.


Object(Access-Point)

This object is undefined.