## MS BackOffice Unleashed

- Extending Exchange
  - Exchange Software Developers Kit
  - Gateway Developers Kit
- Introduction to MAPI
- Exchange Application Types
  - Client Messaging Applications
  - Client Programming Interfaces
- Mail Client MAPI Extensions
- Programming Environment
  - Visual Basic
  - Electronic Forms Designer
    - Simple MAPI
    - Extended MAPI
    - OLE Messaging Library
- Schedule+
  - Multiple Operating Systems
- Server-Side Extensions
  - Running as a Service
- Sample Excel and Word Macro Programs
  - Address Book Macro in Excel
    - Spreadsheet Layout
    - Examining the Program Logic
    - Word, Project, and Other Applications
  - OLE Automation Schedule+ to Create Tasks
    - Program Review
- Sample Custom Forms Applications
  - Performance of Exchange Forms
  - Samples Included with Visual Basic 4.0
- Internet Explorer to Exchange
- Additional Information
  - Internet Resources
    - MAPI-L Mailing List
    - Microsoft's World Wide Web Site
- Summary

#
— 42 —

##
Interfacing Applications to Exchange Server

This chapter covers application integration with Exchange Server. Sample programs demonstrate how to link Microsoft Office to the Exchange Server client, and there is a Visual Basic 4.0 example of how to interface with Schedule+. General information is provided about the Exchange SDK and the MAPI programming architecture.

###
Extending Exchange

Exchange Server can be extended at the server to provide additional gateways or to assist with administrative tasks. The programming is not easy, but the potential exists to write programs that automate or extend the functionality of the management tools for the directory and message stores.

Users can be assisted by automating applications. An Exchange developer or administrator may be asked to extend or optimize a form application developed by a user. The Forms Designer is included with Exchange Server, allowing users to create simple front-ends to the mail. Visual Basic OLE Automation library for Exchange allows relatively uncomplicated interfacing from Excel, Word, or other tools based on Visual Basic interfaces.

####
Exchange Software Developers Kit

Microsoft uses the term Software Developers Kit, often abbreviated as SDK, to describe the samples and documentation for a particular product. In some cases, special tools such as debug builds of the programs are included in the kit.

The Exchange SDK is part of the Backoffice SDK. This is available on Microsoft Developers Network (MSDN) Level II or higher. MSDN is a subscription service of CD-ROM programming tools for all of Microsoft's products.

####
Gateway Developers Kit

As part of the Exchange SDK, Microsoft includes the Gateway Developers Kit. The Gateway Developers Kit allows developers to interface Exchange with other mail systems. Gateway services have special abilities that allow them to transparently interface with systems that may not be so transparent.

Because of these abilities, security is an important consideration. As a mail message is converted from a gateway, the message recipients may be mapped to Exchange directory entries. Ultimately, the user may not want to know that a message came from a foreign system, but the gateway designer needs to consider the power of this capability. An example how this can be done is the properties page of the message; with Exchange Server 4.0, a message received from the Internet Mail Connector will have a property page showing the SMTP message header.

Consideration should also be given to the interface for controlling the gateway. Ideally, a gateway service would read configuration data from the Directory. An Exchange Administration extension could be created to allow the administrator to update and view these settings.

Considerations must be made to account for the various system processor platforms that Windows NT and Exchange Server support. Microsoft has defined a structure to allow the Administration program to detect updated extension files; these add-on modules are registered in the Directory, and the Exchange Administrator program uses this information to locate the server with the most current DLL.

###
Introduction to MAPI

For programmers who wish to link custom or off-the-shelf applications to Exchange Server, MAPI is the solution. MAPI, Messaging Application Programmers Interface, is the programming interface that Microsoft has defined for electronic mail systems.

Exchange Server Public Folders can be used as a database. Although not relational like a SQL Server database, there are some properties in common. Multiple users can read the same data at the same time, plus the data can be searched (or queried). However, a Public Folder would not be suitable for situations where many small transactions take place or records are frequently updated.

Where Public Folders may have their most potential is with multi-user documents. In many cases, a document may be maintained for record purposes or future updates. Consider the case of a law firm where boilerplate documents covering various legal situations may be used with archived for long periods of time.

Lotus Notes has been successfully used for many such applications. Replication technology, the ability to maintain updates to a number of servers inexpensively, has also been leveraged for such applications. At least in current release, Notes has more capability to automate the entry and processing of these documents. Notes applications are typically written using Lotus 1-2-3 like @ commands, not a traditional language like BASIC. Microsoft is working to bring such automation tools to Exchange.

Many customers are anxious to see Microsoft link ActiveX, Visual Basic Script, and possibly Java Script (Visual J++) added to Exchange. None of these have been committed, but these technologies are clearly part of Microsoft's total BackOffice and (Desktop) Office product strategies.

###
Exchange Application Types

Terminology exists to describe the various roles that a application will serve. In the Exchange Software Development Kit, Microsoft defines three categories of Exchange Server applications:

- Client Application uses the services of a server running Exchange Server, but executes on the user's workstation. This workstation could be running any of the available client operating systems.
- Server Application interacts with the Exchange Server services such as the Information Stores or the Directory. A Server Application can be used to provide tools for administrators or users, but they are not associated with any user.
- Combined Client and Server Application is a true customer client-server application that uses back-end server services to support one or more users. Components are installed on both the server and user workstations.

Understanding the unique requirements of each type of application can assist in understanding the technical development needs. For example, a Client Application would interface with the user on a daily basis, clear screen design and ease of use are high priorities. The Server Application must concern itself with scale, multiple users accessing it at once. Consider also the message traffic; a search engine that searches the Information Store at the server is going to produce less traffic than one that pulls from a client workstation.

####
Client Messaging Applications

The case could be made that almost any client Windows program could interface with Exchange Server. In place of saving or printing a data file, it could be mailed directly to another user. In other cases, a custom work environment may want to have a complete interface for reading and sending mail. In most documentation, Microsoft organizes client applications into one of the following three categories:

- Messaging-aware applications
- Messaging-enabled applications
- Messaging-based applications (workflow)

A messaging-aware application does not require the services of a messaging system, but includes messaging options as an additional feature. For example, a word processing application that includes a Send command in its File menu to enable documents to be sent is considered messaging-aware. Components of Microsoft Office, such as Word and Excel, support this feature.

> > Office 95 for Windows 95 and NT has been updated. Make sure users have Office 95A or Office 95B, especially for Exchange messaging-enabled features for public folders. Microsoft offers these as updates to corporate customers on Select CD-ROM sets.

A messaging-enabled application requires the services of a messaging system and typically runs on a network or an online service. An example of a messaging-enabled application is Microsoft Mail.

A more advanced client application is the messaging-based workgroup application. The workgroup application requires full access to a wide range of messaging system services, including storage, addressing, and transport services. These applications are designed to operate over a network without users having to manage the applications' network interaction. Examples of such applications include work flow automation programs and bulletin board services.

####
Client Programming Interfaces

Client application developers can choose to use one or more of the MAPI client interfaces: simple MAPI, CMC, MAPI, and the OLE Messaging Library. Consider the following factors before making a decision:

- Programming languages supported
- Time and skill level required to develop the application
- System Resource constraints
- Type of client application

The language in which your client application will be written or is written is an important issue. If you are modifying an existing application, you must use a client interface that supports your application's language. If you are writing a new client application, the choice of language depends on your experience with the supported languages and any requirements for interoperability that might exist with other components. All the client interfaces work with C and C++, whereas Visual Basic developers are limited to using the OLE Messaging Library and Simple MAPI.

The amount of time you need to create or modify your client application is also a consideration. A simple API such as Simple MAPI or CMC is more appropriate if you have limited time. Resource constraints might also be an issue. To successfully develop a client application, you should have experience with messaging and the appropriate programming language.

Messaging-enabled and messaging-aware client applications have different requirements than messaging-based applications. Messaging-enabled and messaging-aware applications have fewer and simpler messaging features to implement. Messaging-based applications have more complex messaging requirements because they have more direct contact with and control over the underlying messaging system services like address books, message stores, and transports. These applications often implement a wide variety of messaging features, such as rules processing, automatic forwarding, and supporting Rich Text Format. Shared group applications like schedulers and calendars, work flow and message management applications, electronic mail clients, and rules-based inbox managers are examples of messaging-based applications. Complex messaging-based applications like these require the MAPI client interface.

The OLE Messaging Library is a good choice for applications that require a moderate amount of messaging support. The OLE Messaging Library is an object-oriented API used primarily by Visual Basic and Visual C/C++ client application developers. It provides programmable objects that publish properties and methods which can then be managed by Visual Basic and Visual Basic for Applications programs or other OLE Automation controllers. The OLE Messaging Library is based on the capabilities provided by OLE Automation. In terms of messaging functionality, it offers more than CMC and Simple MAPI offer, but less than MAPI offers.

Simple MAPI or CMC is the best choice for messaging-enabled and messaging-aware applications. These interfaces provide a fast and easy way to build basic applications from scratch or add messaging functionality to existing applications.

###
Mail Client MAPI Extensions

Microsoft offers the Client Extensions Programmer's Reference, a section of the MAPI SDK documentation. The purpose of such extensions is to allow new functions to be added to the Exchange Client. Microsoft defines four types of Microsoft Exchange client extensions:

- Command Extensions. Examples include custom Spelling, Thesaurus, and Grammar commands to assist the user. Other, more Exchange-centric examples include Public Folder commands that provide folder-sensitive menu items or toolbar buttons. Finally, Message Class commands can override the default behavior of Microsoft Exchange commands.
- Event Extensions. These enable a programmer to extend or override behavior on events such as the arrival of new messages, reading and composing messages, opening of attachments to a message, and interaction with the folders and messages. Cited examples include an Attachment virus detection program that intercepts the opening of attachments.
- Property Sheet Extension. Custom property tabs can be added to the Microsoft Exchange configuration screens or specific message form classes. An example of custom form classes could be a workflow application with a property page that identifies specific information about the task start time and person who initiated the task. For configuration tabs, one might be added to configure system file paths and other settings required to interface with an outside program.
- Advanced Criteria Extensions. A programmer can add additional search criteria for custom properties of a public folder.

The MAPI SDK includes examples of these extensions. Fundamentally, as these ware written to MAPI, they can work with mail products other than Exchange. Also consider that the Exchange Client could be used to drive other information services such as the Internet (POP3 client), MSN, CompuServe, and Microsoft Mail 3.x servers.

###
Programming Environment

Microsoft offers several methods of encapsulating MAPI programming. The MAPI Software Development Kit, MAPISDK, documents and details these methods. Raw MAPI programming is the lowest level of access, the OLE Messaging interfaces are easiest to use. Selecting the correct programming interface will be a key to success when extending Exchange functionality.

####
Visual Basic

Visual Basic 4.0 includes a MAPI sample in the VB directory \SAMPLE\MAPI\VBMAIL.VBP project file. The sample is a minimal client for composing and reading email. It works with either the Microsoft Mail 3.x or Exchange client.

MSMAPI16.OCX are MSMAPI32.OCX are the two Visual Basic library files—the first for 16-bit environments, the second for 32-bit environments.

Visual Basic encapsulates MAPI into two main objects. The first of these objects is named MAPISession; it has properties and several action codes. This object encapsulates the underlying MAPI connection.

The second object is MAPIMessages. This is the primary interface for manipulating, creating, and sending messages.

####
Electronic Forms Designer

Exchange includes an Electronic Forms Designer, a tool that Microsoft promises end users can access without programming experience. The Forms Designer installs with a separate SETUP program. The program code is on the Clients CD-ROM, included with Exchange Server.

The Forms Designer works in two stages, a program is used to draw the forums using a drag-and-drop interface. This creates an EFP file that is used to store the design of the form. Once ready, the user selects Install from the File menu of the Forms Designer. This initiates a process that generates source code and a project for Visual Basic 4.0. Visual Basic is then automatically launched to compile the source code. Once the program is compiled into an executable program (EXE), the Forms Designer will prompt which Library to install the forms.

Typically a library will be an Exchange Server public folder specific to the application being developed. Exchange maintains a hidden folder for system-wide registered forms. In addition, forms can be installed to local Personal Folders or to a private mailbox folder.

> > The Visual Basic included with Exchange Server is licensed only for use with Exchange Server. It identifies itself as "Visual Basic for Exchange Server." For programmers wanting to develop MAPI or OLE Messaging applications, it is recommended that the full Visual Basic 4.0 Professional system is acquired.

It is important to understand the implications of Exchange Server's use of executable programs, EXE files, for Electronic Forms. When a user activates a form, Exchange checks if the EXE is already present on the local system. If this is a new or updated form program, Exchange will download the program to the local system. The client will then invoke the program.

> > The Visual Basic included with Exchange Server is 16-bit. It is not a feature of the current product to create 32-bit source code.

FIGURE 42.1. Forms designer shown with sample Help Desk application.

#####
Simple MAPI

In simplified terms, Simple MAPI is the least-common denominator of Message Application Programming Interfaces. Most third-party messaging products (not from Microsoft) have implemented Simple MAPI in their client programs.

In general, when working with Exchange, Simple MAPI is best passed up in favor of Extended MAPI. However, there are some reasons that a programmer may consider working with Extended MAPI:

- It is the older, more established environment. There are existing Simple MAPI code libraries, books, and expertise.
- There is a need to develop an application that is targeting a messaging system that does not support Extended MAPI 1.0.
- The application will be used during a migration from MS Mail 3.x to Exchange Server where both clients need similar custom programs.

#####
Extended MAPI

Sometimes known as MAPI 1.0, Extended MAPI is the full iteration of the API. The Windows Messaging System and Exchange Server clients are examples of products that fully support Extended MAPI.

Extended MAPI differs from Simple MAPI in that it is built around the Common Object Model (COM). COM is what Microsoft has evolved to from Object Linking and Embedding (OLE).

#####
OLE Messaging Library

The Microsoft OLE Messaging Library is an alternate programming interface for Extended MAPI. Microsoft's emphasis on the COM design encourages this more generic encapsulation of the underlying Extended MAPI programming routines. ActiveX, most typically associated with Microsoft's Internet/Intranet initiative, is also fundamentally based on COM.

The file OLEMSG.HLP, installed along with the Exchange Electronic Forms Designer, documents the programming interfaces to OLE Message Automation. The MAPI SDK Documentation also includes this information.

The Microsoft OLE Messaging Library is designed to handle the most common tasks for client developers using Visual Basic and Visual C++. To use the library, MAPI must be installed and accessed via a tool that supports OLE Automation. The following Microsoft applications support OLE Automation:

- Microsoft Visual Basic version 4.0
- Microsoft Visual Basic for Applications
- Microsoft Access version 2.0 or later
- Microsoft Excel version 5.0 or later
- Microsoft Word version 6.0 or later
- Microsoft Project version 4.0 or Later
- Microsoft Visual C++ version 1.5 or later

###
Schedule+

Exchange Server includes Schedule+, a tool for tracking personal schedules, coordinating appointments, and controlling access to resources such as meeting tools. From a programming perspective, Schedule+ is another Extended MAPI application. In fact, Schedule+ has a OLE Automation interface for similar purposes.

Microsoft's Schedule+ Programmer's Reference is designed for use with the Microsoft Schedule+ OLE Automation. This allows the customization of menus and extension with programming tools such as Visual Basic or Visual C++.

> > A help file, OLEMSG.hlp, is included with the Exchange Server 4.0 Electronic Forms Designer. This help file covers both Exchange and Schedule+ OLE Automation programming interfaces.

#####
Multiple Operating Systems

> > Before rolling out a MAPI application, consider that Extended MAPI is delivered in various flavors. Windows 95 originally came with what was called the Exchange 4.0 client, now renamed to the Windows Messaging System. Updates are available for this; it is recommended that all MAPI application clients have a consistent (and the most recent) environment. Consider also that Windows 3.x, Windows 95, and Windows NT versions of MAPI may have different patch levels.

###
Server-Side Extensions

Exchange can be extended at the server side. The Exchange Administrator program is an example of an application that access the Directory, Public, and Private information stores.

Mailbox monitors, what Microsoft calls Mailbox Agents, can be created to provide an interface between a program and Exchange. A special system mailbox could be created, for example, to manage Distribution Lists. A program could be written that monitors this mailbox, enabling mail messages to manipulate the directory. A message could be sent with the name of the Distribution List and the members to add and remove members. Although this specific example is not included, see the Microsoft Exchange SDK Sample Mailbox Agent (SMBA) for details of the programming logic.

####
Running as a Service

The most desirable way of running a server-side client may be as a Windows NT service. This allows the program to start without user intervention when the system is started. The program can also be managed (stop/start) remotely using standard Windows NT tools such as Server Manager.

There are some considerations about the use of MAPI programs as a service. In particular, care must be taken to ensure that the program does not require access to the screen or a response from the user. Because it must run as a background program, error messages should be written to a file or the standard Windows NT Event Viewer.

MAPI programs also have special requirements for profiles. Depending on which Windows NT user-account is used to execute the service, efforts must be made to dynamically create the profile. If the MAPI program does not interact with other installed services, the service can be installed to run with a defied user account. The user then needs to log in as that account to create the profile, which could then be used by the background program.

If the program needs to interact with other services, however, it may need to run with the System service account. An example of such a program is one that links Microsoft's Internet Information Server (IIS) to MAPI routines. The System service account has special considerations; it can not be logged into interactively, so a profile can not be created by the user before the MAPI program is started. To work around this, the profile should be created by the program as it starts. The MAPI function HrCreateMailboxAgentProfile can be used for this purpose. This issue is covered in more detail, with examples, in Microsoft's Exchange SDK.

###
Sample Excel and Word Macro Programs

This section combines BackOffice with the "Front" Office. Microsoft Word, Excel, and Project all have applications that may require linkage to Exchange electronic forms or mail messages.

To run any of the samples presented, it is assumed that the Exchange Client is the MAPI provider. A working profile should also be configured and working. For best operations, it is suggested that a profile be used that contains only the Exchange Server information service. Other services may introduce unanticipated problems.

> > The samples presented in this chapter have only been tested with Exchange Client 4.0 Service Pack 2 on Windows 95 Service Pack 1 and Windows NT 4.0. They may not function correctly with Information Services other than Exchange Server.

OLE Automation is the preferred programming interface for Visual Basic for Applications. Using the OLE Messaging interface, applications can quickly be constructed that transfer data to or from Exchange.

####
Address Book Macro in Excel

This section presents a sample program written in Visual Basic for Applications. The sample program uses an Excel spreadsheet as a database of message recipients.

The scenario used in the example is a tax office sending out a brief reminder of taxes owed. Suppose that a small sweepstakes recently took place with cash prizes. To facilitate reporting, the tax office is provided a list of prize amounts and contact information for the prize winners.

In an effort to be proactive, the tax office wants to send out mail messages to the prize winners. Using last year's tax rate as an example, the tax office wants to remind the prize winner that they should save some of their money for the purposes of paying at tax time.

#####
Spreadsheet Layout

The spreadsheet itself is rather simple. The sheet with the data is named MailList1. The first row is a description of the fields, and the second is a colored (empty) separator row. The data starts on the third row.

The first column of data is a record number; this is not used by the program—it helps to troubleshoot the process. The second and third columns are the first and last name of the recipient, respectively. The fourth column is the e-mail address. The example uses SMTP address types. Others could be used, but the program as written uses SMTP.

The sixth column contains the prize amount in dollars. The seventh is the tax rate, represented as a percentage, the data presumed to be based on the tax office's own records. The eleventh column contains a simple formula that multiples the prize amount (sixth column) by the tax rate (seventh column).

FIGURE 42.2. Sample dataset for the Excel-to-OLE messaging example.

Three additional columns are unused in the sample. The fifth column contains the number of copies of the message to be sent, but the program does not incorporate this logic. The ninth and tenth columns could be used to report the progress of the sending of messages. The logic for this is also not included in the sample program.

######
Cell Formatting

The Cell columns are formatted for the appropriate values. For example, column six is formatted with a currency property to display the dollar sign ($) and proper decimal places. This is significant, because the Visual Basic for Applications program logic uses this formatting for the message content.

######
Linking to Other Tables

Obviously, this example is a simple one. A more realistic one would be that the social security number of the prize winner is used to look up a second table that shows the individual's last year earnings and associated tax rate. It would also be sensible to include those figures in the message as a method of documenting to the prize winner how the numbers were calculated.

#####
Examining the Program Logic

The program is implemented as a single function for simplicity. A subroutine called MAPI_Ole_Sample1 invokes the function named Mail_TaxNotice1.

The first line of code sets the spreadsheet to the MailList1 sheet. The variable CurrentRow is initiated to two, skipping over the two header lines of the sample spreadsheet. The active cell is set to the first in the spreadsheet, and the CurrentRow variable will be used as an offset to access data for the remainder of the program:

    Sheets("MailList1").Select

    CurrentRow = 2

    Range("A1").Select

######
Starting the Session and Message

OLE Message treats session handles as objects. A mail message consists of a MAPI Session, a logon instance, and an address instance. Here is an overview of a session:

    Open MAPI Session

    Logon

    Create Address Object

    Create Message Object

    Send message with connected address

    Logoff

The next line of program code initiates an OLE Automation connection to the OLE Messaging interface:

    Set MAPISession = CreateObject("MAPI.Session")

The variable MAPISession will serve as a handle to the session. The session is then logged on:

    MAPISession.Logon

Because no parameters are passed, the user is prompted for required information. Assuming the Exchange Client is the MAPI provider, the logon will prompt for the profile to use. Assuming the logon is successful, the program initiates the main data processing loop.

The loop itself is a while/wend loop that cycles until an empty cell in the A column is found. Assuming a row is to be processed, a new message object is started. The Message object variable will contain a handle to the message:

    Set Message = MAPISession.Outbox.Messages.Add

The message subject starts with the recipient's first name. This is accessed from the first column in the row and appended with the string ", you are a prize winner!". At this point, it is stored in a local string, not yet associated to the mail message being generated:

    MessageSubject = ActiveCell.Offset(CurrentRow, 1).Value & ", you are a prize winner!"

In the example, the body of the message is stored in a single string variable, named MessageBody. The first line addresses the person by first name in the format "Dear FirstName,". Chr$(13) is added to indicate that a carriage return (the Enter key) needs to be placed; two are added to provide one blank line:

    MessageBody = "Dear " & ActiveCell.Offset(CurrentRow, 1).Value & ":" & Chr$(13) & Chr$(13)

The message content starts with a simple introduction:

    MessageBody = MessageBody &

     [ccc]"Congratulations! We have been informed that you have recently received a prize!"

     [ccc]& Chr$(13)

    MessageBody = MessageBody & "This is a reminder that taxes are due on your "

The amount of the prize is taken from column five of the spreadsheet. The ActiveCell.Offset.Text method returns the cell as formatted by Excel onscreen; this is significant, because it will include the dollar sign ($) and so forth in proper format. If ActiveCell.Offset.Value or ActiveCell.Offset.Formula had been used, it would have lost the formatting properties:

    MessageBody = MessageBody & ActiveCell.Offset(CurrentRow, 5).Text

     & " prize amount. As your current tax rate is "

In similar fashion, the formatted percentage rate in column six of the spreadsheet is added to the growing message:

    MessageBody = MessageBody & ActiveCell.Offset(CurrentRow, 6).Text

     & ", it is estimated that you will owe "

The formula in column ten is used to derive the calculated estimate of owed taxes:

    MessageBody = MessageBody & ActiveCell.Offset(CurrentRow, 10).Text & "." + Chr$(13) + Chr$(13)

    MessageBody = MessageBody & "Thank you!" & Chr$(13)

######
Addressing the Message

The string variable MessageTo is used to hold the working address for the recipient of the message. A one-off address is formatted so that the display name of the user will match the First and Last name fields in the data, but the address will be formatted with SMTP. Other address types could be used, including those that require Ambiguous Name Resolution, but that requires modification to these lines of code:

    MessageTo = ActiveCell.Offset(CurrentRow, 1).Text & " " & ActiveCell.Offset(CurrentRow, 2).Text

    MessageTo = MessageTo & "[smtp:" & ActiveCell.Offset(CurrentRow, 3).Text & "]"

> > Ambiguous Name Resolution is the term used to describe the process of matching the TO: of a message to the Global Address List or Personal Address List.

> > A one-off address is the term used to describe an address used in a message that is not selected from the Global Address Book or Personal Address book. This is the same as when a user free-form types an address.

A new Address Recipient Object is created to tie the message to the recipient. The type used in the program is called a "One-off recipient," a dynamically created address. This is similar to the user free-form typing on the TO: line instead of selecting from the Global Address List (GAL). The MessageTo variable is put in the .Name field of the object:

    Set OneOffRecip = Message.Recipients.Add

    OneOffRecip.Name = MessageTo

    OneOffRecip.Type = mapiTo

    OneOffRecip.Resolve

The message object is provided with the previously generated strings for the body and subject of the message:

    Message.Subject = MessageSubject

    Message.Text = MessageBody

The Update and Send methods of the message are called to initiate the actual sending of the message. The showDialog:=False property on Message.Send instructs MAPI to not pop up the actual screen showing the message:

    Message.Update

    Message.Send showDialog:=False

FIGURE 42.3. Exchange Client message queue shown in the outbox.

FIGURE 42.4. Capture of the message.

Next, the CurrentRow is incremented to move to the next row of spreadsheet data. The whole process of composing and addressing the message starts on the next line.

#####
Word, Project, and Other Applications

Project and Word are two other applications that benefit from linkage to Exchange electronic mail—for example, a Word document that sends personalized letters to employees in a distribution list, addressing them by first and last name. The Exchange Address Book contains a wealth of fields that could be exploited for such purposes.

> > Microsoft's Knowledge Base (KB) Technote Q121424 has information on linking Visual Basic for Applications to MAPI. This can be accessed on Microsoft TechNet CD-ROM or the Internet at http://www.microsoft.com/kb URL.

> > Microsoft offers a Microsoft Word Developer's Kit that includes a wrapper for MAPI. Complete C source code is included for the wrapper. If direct access is required to MAPI, without using OLE Automation, this could serve as an example. This is distributed in the form of a book with disk by Microsoft Press.

####
OLE Automation Schedule+ to Create Tasks

As mentioned earlier, Schedule+ has MAPI and OLE Automation interfaces. As with the Exchange Server client, OLE Automation is the easiest method for developing with Visual Basic. Figure 42.5 shows a Visual Basic form that was custom-developed to drive Schedule+.

FIGURE 42.5. Main screen of the Schedule+ example application.

Although this example does not use Exchange directly, it does show how programming logic could be applied to link Schedule+ to other applications. A practical application could be to link tasks and appointments to a project plan in Microsoft Project, Excel, or a custom Visual Basic program.

> > Schedule+ 7.0 is actually available in two flavors. One is included with Office 95 and is identified as Schedule+ 7.0 in the Help About. The second one is included with Exchange Server client and is identified as Schedule+ 7.0a in the Help About. Make sure the client has the appropriate Exchange-aware version to ensure proper compatibility with the programs.

#####
Program Review

The program main form, titled MainVBSP.frm, contains four buttons. The first of these buttons, labeled Logon S+ initiates the MAPI session. The second button, labeled Create Task initiates the creation of Schedule+ to-do entry. The third button, Create Appointment initiates the creation of a sample appointment. The final button, Logoff S+, closes the MAPI session.

######
Initial Button State

The properties of the buttons are set in such a way that only the Logon S+ button is enabled when the form is first started. This ensures that a logoff is always proceeded by a logon, and that the test routines are not executed without being logged on to the MAPI provider (Exchange).

######
Logging On

When the Logon S+ button is pressed, the following code is activated (tied to the button event). LogonSchedule is a call to a subroutine that will initiate the MAPI logon. The Logon S+ button is then disabled, the Logoff S+ button is enabled, and the two sample activity buttons are enabled:

    LogonSchedule

    ButtonLogon.Enabled = 0

    ButtonLogoff.Enabled = 1

    ButtonCreateTask.Enabled = 1

    ButtonCreateAppointment.Enabled = 1

The LogonSchedule subroutine actually performs the MAPI logon. A global variable GLB_MAPISession will point to the MAPI logon. The following code establishes that session and sets the global variable:

    Set GLB_MAPISession = CreateObject("MAPI.Session")

    GLB_MAPISession.Logon

The following code actually links to the schedule itself, GLB_AppSchedulePlus global variable will be set to the schedule:

    Set GLB_AppSchedulePlus = CreateObject("SchedulePlus.Application")

    Set GLB_UserSchedule = GLB_AppSchedulePlus.ScheduleLogged

######
Sample Task on To Do List

The button labeled Create Task will use the active MAPI and Schedule+ sessions to create an appointment on the To Do list of Schedule+. The button calls the routine VBSampleTask that performs the procedure.

A new Table object is created of type SingleTasks to define the structure. Next, a task item is created from this structure. The task will be tracked by the variable TaskItem:

    Set objTable = GLB_UserSchedule.SingleTasks

    Set TaskItem = objTable.New

The variables DateToday and DateEnd are created to define the end date of the task. Schedule+ typically tracks tasks by their end date. The routine LConvertTo32bitDate is described in the OLE Messaging help file; it is required due to the unique way that Schedule+ encodes dates (different from the Visual Basic data type):

    DateToday = DateAdd("d", 1, Now)

    DateEnd = LConvertTo32bitDate(DateAdd("d", 1, DateToday))

The TaskItem is then populated with the sample data:

    TaskItem.SetProperties _

     Text:=MainVBSP.TextSample1.Text & ": " & Now(), _

     Notes:="Sample task from _BackOffice Unleashed_", _

     EndDate:=DateEnd

The object is released to initiate the actual transaction:

    Set TaskItem = Nothing

    Set objTable = Nothing

Looking at the Schedule+ application main view, a new to-do event should now appear. Figure 42.6 shows the details of this event.

FIGURE 42.6. Details of the Task created by the sample Visual Basic program.

######
Sample Appointment

Pressing the Create Appointment button initiates the subroutine VBSampleAppointment. Using the already-open MAPI and Schedule+ sessions, a new appointment will be created.

> > The appointment created is flagged as "tentative". This allows the users who receive the appointment a chance to confirm that they are actually accepting the appointment.

The subroutine first creates a table object of the new SingleAppointments object:

    Set objTable = GLB_UserSchedule.SingleAppointments

The start and end appointment dates are set. The date will be set to start in one minute (from execution time) and end in two hours:

    AppointmentStart = DateAdd("n", 1, Now)

    AppointmentEnd = DateAdd("h", 2, AppointmentStart)

A new instance of the SingleAppointments object is created. The properties of the appointment are set to sample entries:

    Set AppointmentItem = objTable.New

    AppointmentItem.SetProperties _

     Text:="Work with BackOffice Unleashed", _

     Notes:="Spend Two Hours working with OLE/MAPI samples to construct super app!", _

     Start:=AppointmentStart, _

     End:=AppointmentEnd, _

     CreatorName:="VB Sample Program"

The object is released to initiate the actual creation of the object:

    Set AppointmentItem = Nothing

    Set objTable = Nothing

Figure 42.7 shows the appointment in the Schedule+ main screen, figure 42.8 shows the details of the appointment.

FIGURE 42.7. Main Schedule+ screen showing new appointment.

FIGURE 42.8. Details of new appointment.

######
Logoff of Session

The Logoff S+ button will close the links to Schedule+ and MAPI. The buttons are restored to their previous states, as they were when the program first started. The MAPI session is closed, closing the link to the Schedule+ program.

###
Sample Custom Forms Applications

Microsoft has included several excellent form samples. Using the Electronic Forms Designer, these can quickly be compiled and installed.

As mentioned previously, the forms are saved as Visual Basic projects. These can be manually edited with the 16-bit version of Visual Basic.

####
Performance of Exchange Forms

As mentioned earlier, the Exchange Forms designer generates 16-bit Visual Basic EXE program files.

> > Windows NT on Alpha, MIPS, Power PC, and other RISC platforms do not have a compiler to generate forms. Because the forms are 16-bit EXE programs, they can run in x86 emulation mode of Windows NT. However, the forms themselves need to be authored and/or compiled on an Intel i386-compatible machine.

Many users have complained about the time it takes to open and process even simple forms using Exchange. If there is an opportunity to assist these users, one of the easiest tips is to hide and unhide the form instead of closing and opening between processing. Exchange and Visual Basic, especially on Windows NT or Windows 95 where they run with Win16 emulation, can take time to load and start. By keeping the form process and associated resources in memory, almost all of the performance bottlenecks are eliminated.

####
Samples Included with Visual Basic 4.0

Microsoft's Visual Basic 4.0, when installed, includes a MAPI sample in the \SAMPLE\MAPI\VBMAIL.VBP project file. The sample is a minimal client for composing and reading e-mail. It works with either the Microsoft Mail 3.x or Exchange client.

MSMAPI16.OCX, MSMAPI32.OCX are the two Visual Basic library files—one for 16-bit environments, the second for 32-bit environments.

Visual Basic encapsulates MAPI into two main objects. The first of these objects is named MAPISession; it has properties and several action codes. The second object is MAPIMessages.

###
Internet Explorer to Exchange

Microsoft's ActiveX architecture can be linked to OLE Automation interfaces, such as the OLE Messaging architecture used in the earlier Visual Basic and Visual Basic for Applications samples.

There also seems to be considerable interest in linking the Internet Information Server (IIS) to Exchange Public Folders or Exchange mail. Microsoft is working on integrating such features into the next update of Exchange.

> > See Chapter 20, "Exchange Server and Mail Overview," for information on Exchange Server and the forthcoming Internet Web Connector.

###
Additional Information

Programming in any environment benefits from good sample programs and documentation. Exchange Server is no exception.

C++ is the dominant tool Microsoft and third-party vendors use to develop the Exchange Client.

Visual Basic seems best suited for "glue logic" when combining Exchange Server with other applications. Especially when working with Microsoft Office and Microsoft Project, OLE Automation programming interfaces and Visual Basic for Applications is an effective solution.

As mentioned earlier in the chapter, the Win32 and BackOffice SDK can be acquired by subscribing to Microsoft's Developer Network (MSD). Here are some of the resources of interest to an Exchange developer:

- Microsoft Win32 SDK; MAPI SDK
- Microsoft BackOffice SDK; Exchange SDK
- Microsoft Visual Basic Programming System for Windows
- Microsoft OLE Messaging Library Programmer's Reference
- Microsoft Exchange Application Designer's Guide
- MAPI Programmer's Reference

####
Internet Resources

The Internet is obviously a valuable resource for program samples, API documentation, and advice from other developers.

#####
MAPI-L Mailing List

A mailing list for discussion of MAPI programming can be accessed using Internet electronic mail. Send a message to "LISTSERV@PEACH.EASE.LSOFT.COM" with the message text "SUBSCRIBE MAPI-L". The mail list server at LSOFT.COM will automatically respond to the request with a mail message providing further instructions.

> > When sending a subscribe command for an Internet Mailing list, make sure automatic signature feature are turned off. The automated list processor programs parse all the incoming lines of a message, the only entry should be the "SUBSCRIBE MAPI-L" command.

#####
Microsoft's World Wide Web Site

With the fast pace of Exchange and Internet development, electronic communications is often the fastest and most efficient means of communicating information. Microsoft has several Web pages of interest to developers of Exchange.

Microsoft has a series of pages devoted to Exchange Server, including sample applications and product announcements. The site can be found at

     http://www.microsoft.com/Exchange

In addition, a MAPI home page has been establishes. This is the source for the most recent MAPI SDK and other valuable documentation. The site can be found at

     http://www.microsoft.com/win32dev/mapi/

Look also at Microsoft Developer Network resources at

     http://www.microsoft.com/msdn

Information on these pages enable a developer to get the programming tools described in this chapter.

###
Summary

This chapter introduces the interfaces, tools, and possibilities of Exchange and MAPI programming. However, this is just a starting point. The samples shown can get a programmer started, but much more can be done.

Although this chapter concentrated on client-side OLE Automation, Extended MAPI programming opens a wider range of possibilities. To exploit these more advanced routines, expect to spend more time learning the programming. C++ is by far the preferred language.