SUGGEST.EXE is Microsoft Exchange Server Custom Agent (192339)


The information in this article applies to:

  • Microsoft Exchange Development Kit (EDK) 5.5
  • Microsoft Exchange Server 5.5, when used with:
    • the hardware: Intel x86
This article was previously published under Q192339

SUMMARY

The purpose of this article is to describe one method of developing a Microsoft Exchange Server Custom Agent. This article does not give an overview of the Microsoft Exchange Event Service, nor does it provide information on the Microsoft Exchange Server Scripting Agent. However, one of the files included with this sample is Agents.hlp (also available on the Microsoft Exchange Server CD). This file provides information that supplements this article.

IMPORTANT: This article presumes that you will read and use the information provided in the Agents.hlp file.

MORE INFORMATION

The following file is available for download from the Microsoft Download Center:

DownloadDownload Suggest.exe now

Release Date: Sep-09-1998

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:

119591 How to Obtain Microsoft Support Files from Online Services

Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file.

Although Agents have been also called Handlers and Bindings, this article refers to them as Agents. If you need to write a Custom Event Hander, this is the same as writing a Custom Agent.

This sample (referred to as Suggest from this point forward) was written to be simple and yet provide a skeleton for further Custom Agent development.

The Suggest.exe file monitors a folder. Whenever a message is placed into the folder, Suggest sends a message back to the user that placed the message into the folder. The message sent to the user contains the same subject as the message placed into the folder. The message also contains a body that is configurable through a property sheet.

Files in Suggest.exe

  • Suggest.cpp / .h - Application file
  • Exevhandler.cpp / .h - Implements the IExchangeEventHandler
  • Suggest.rc - Contains the property page dialog
  • Suggestevents.cpp / .h - Application-specific class (modify this class to customize your own agent)
  • Suggest.idl - Interface definition file
  • Saprops.cpp / .h - Property Page Dialog Code
  • Esconf_i.c [ASCII 150] Pre-generated _i.c for Event Interfaces
  • Esconf.h [ASCII 150] Pre-generated .h for for Event Interfaces
  • Exchhndl.idl - .Idl for IExchangeEventHandler
  • Exchhndl_i.c - Generated _i.c
  • Exchhndl.h - Generated .h file
  • Propid.h - Some property tags
  • Suggest.def - Defines exports
  • Saprops.rgs - Registry entry for property page
  • Exevhandler.rgs - Registry entry for Custom Agent
  • Agents.hlp - Help file for the Microsoft Exchange Server Scripting Agent and other agent-oriented help
  • Regs.cpp / .h - Registry Key manipulation functions

Using Suggest As-Is

(For simplicity, these steps are written to be performed from your Microsoft Exchange Server computer.)
  1. Download the attached self-extracting executable file.
  2. Unzip the files into a project directory.
  3. Open the Suggest.dsw workspace from Microsoft Visual Studio/ Visual C/C++.
  4. Exit and Log off Outlook.
  5. Stop the Microsoft Exchange Event Service using the Services Control Panel.
  6. Use the Rebuild All command to build the sample.
  7. From the Tools menu, select Register Control.
  8. Start the Microsoft Exchange Event Service using the Services Control Panel.
  9. Start Microsoft Outlook.
  10. Select the folder in which you wish to install Suggest.
  11. Right-click the folder and then select Properties.
  12. Select the Agents tab.

    NOTE: If you do not see an Agents tab please refer to the "When Agents Tab Is Not Shown" section that appears later in the article.
  13. Click the New button.
  14. Input a name for this instance of Suggest.
  15. Select the "A new item is posted in this folder" check box.
  16. Select the Other option button.
  17. Open the combo box and select "Microsoft Exchange 5.5 SDK Custom Agent Class".
  18. Click the Properties button.
  19. Input text for the body of the message that is returned to users.
  20. Click the OK button in the dialog box.
  21. Click the OK button in the New Agent dialog box.
  22. Click the OK button in the Folder Property Sheet.
At this point the agent is installed and begins operating. (Please see Incremental Change Synchronization [ICS].)

Customizing Suggest.exe to Create Your Own Custom Agent

(For simplicity, these steps are written to be performed from your Microsoft Exchange Server computer.)
  1. Download the attached self-extracting executable file.
  2. Unzip the files into a project directory.
  3. Open the Suggest.dsw workspace from the Microsoft Visual Studio/ Visual C/C++ directory.
  4. Modify or replace the CSuggestEvents Class to accommodate your needs.

    NOTE: ExEvHandler is designed to instantiate a class and call one of four methods in this class. If you replace CSuggestEvents with a class of your own you should perform the following steps. If you are simply modifying CSuggestEvents you may skip to step 10.
  5. Locate the instantiation of CSuggestEvents, and replace it with your class (Line 54).
  6. Include the header for your class in the ExEvHandler.cpp file.
  7. Ensure that you implement the following four methods in your class:

    HRESULT OnChange(CExEvHandler* phndlr);
    HRESULT OnMessageDeleted(CExEvHandler* phndlr);
    HRESULT OnTimer(CExEvHandler* phndlr);
    HRESULT OnMessageCreated(CExEvHandler* phndlr);

  8. Customize the SAProps.cpp, SAProps.h, and Suggest.rc files to add features to the Property Page Dialog. (Please refer to the "Properties on Custom Agents" section.)
  9. Exit and Log off Microsoft Outlook.
  10. Stop the Microsoft Exchange Event Service using the Services Control Panel.
  11. Use the Rebuild All command to build the sample.
  12. From the Tools menu, choose Register Control.
  13. Start the Microsoft Exchange Event Service using the Services Control Panel.
  14. Start Microsoft Outlook.
  15. Select the folder in which you wish to install your agent.
  16. Right-click the folder and select Properties.
  17. Select the Agents tab. (If you do not see an Agents tab, please see the "When Agents Tab Is Not Shown" section.)
  18. Click the New button.
  19. Input a name for this instance of your Agent.
  20. Select the appropriate check boxes. (Please see the Agent Events section.)
  21. Click the Other option button.
  22. Open the combo box and select your agent.
  23. Click the Properties button.
  24. Configure the Property Page as desired.
  25. Click the OK button.
  26. Click the OK button on the Folder Property Sheet.

When Agents Tab Is Not Shown

There are a variety of reasons why your Agents tab is not be displayed in the properties of a folder. The main two reasons follow:
  • Inadequate permissions

    -and-
  • Outlook Configuration
  1. You need to have client permissions to install agents on a folder. This is done in the Microsoft Exchange Server Administrator program. Under your Site, select Folders, System Folders, Events Root, and EventConfig_servername. From the File menu, select Properties, then click Client Permissions and make sure you are in the list.
  2. With Outlook 98 and Outlook 2000, the Agents tab is disabled by default. From the Tools menu, choose Options. Click the Other tab and then select Advanced Options and then Add-In Manager. Make sure that the check box next to Server Scripting is selected.

Incremental Change Synchronization (ICS)

The Microsoft Exchange Event Service utilizes ICS in order to track changes to the directory. ICS, by default, triggers every 60 seconds. Therefore, you may have to wait up to one minute after placing a message into a folder with an agent bound to it before you see the activation of your agent.

Properties on Custom Agents

Typically you would retrieve the EventBinding Object from within the Property Page when the user clicks the Properties button on the Agents tab. This allows you to obtain all information about the Handler that you require. This in turn, allows you to set per instance properties on the handler. However, this is being researched because it does not appear to be working at this time.

Suggest simply stores the information gathered on the property page in the registry under the Class id for Suggest. However, this is not very effective as it causes all instances of Suggest to be modified any time the user modifies the properties on suggest. Also, since the registry is local, the information gathered from the property pages while at a client computer will not affect the operation of the agent on the server. Only when properties are set at a server do the changes take effect.

A better short-term solution would be to save the property information on the Agent message which resides in the following folder path: 
\Public Folders\NON-IPM Subtree\Events Root\EventConfig_servername
In this folder there will be a message with a subject (PR_SUBJECT) matching the name of the Agent. You could set properties on this message. Although this technique still changes the properties for all instances of the custom agent, it allows for client changes to take effect on the server.

Agent Events

There are four agent events:
  • MessageChanged - An item is changed in this folder.
  • MessageDeleted - An item is deleted in this folder.
  • Timer - A scheduled event occurs.
  • MessageCreated - A new item is posted in this folder.
Modification Type:MinorLast Reviewed:8/9/2004
Keywords:kbdownload kbFAQ kbfile kbinfo kbMsg KB192339 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.