SUGGEST.EXE is Microsoft Exchange Server Custom Agent
ID: Q192339
|
The information in this article applies to:
-
Exchange Development Kit (EDK), version 5.5
-
Microsoft Exchange Server, version 5.5
on the following platforms: x86
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 INFORMATIONThe following file is available for download from the Microsoft
Download Center. Click the file name below to download the file:
Suggest.exe Release Date: Sep-09-1998
For more information about how to download files from the Microsoft Download
Center, please visit the Download Center at the following Web address
http://www.microsoft.com/downloads/search.asp
and then click How to use the Microsoft Download Center.
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.)
- Download the attached self-extracting executable file.
- Unzip the files into a project directory.
- Open the Suggest.dsw workspace from Microsoft Visual
Studio/ Visual C/C++.
- Exit and Log off Outlook.
- Stop the Microsoft Exchange Event Service using the Services Control
Panel.
- Use the Rebuild All command to build the sample.
- From the Tools menu, select Register Control.
- Start the Microsoft Exchange Event Service using the Services Control
Panel.
- Start Microsoft Outlook.
- Select the folder in which you wish to install Suggest.
- Right-click the folder and then select Properties.
- 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.
- Click the New button.
- Input a name for this instance of Suggest.
- Select the "A new item is posted in this folder" check box.
- Select the Other option button.
- Open the combo box and select "Microsoft Exchange 5.5 SDK Custom Agent
Class".
- Click the Properties button.
- Input text for the body of the message that is returned to users.
- Click the OK button in the dialog box.
- Click the OK button in the New Agent dialog box.
- 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.)
- Download the attached self-extracting executable file.
- Unzip the files into a project directory.
- Open the Suggest.dsw workspace from the Microsoft Visual Studio/ Visual
C/C++ directory.
- 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.
- Locate the instantiation of CSuggestEvents, and replace it with your
class (Line 54).
- Include the header for your class in the ExEvHandler.cpp file.
- 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);
- 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.)
- Exit and Log off Microsoft Outlook.
- Stop the Microsoft Exchange Event Service using the Services Control
Panel.
- Use the Rebuild All command to build the sample.
- From the Tools menu, choose Register Control.
- Start the Microsoft Exchange Event Service using the Services Control
Panel.
- Start Microsoft Outlook.
- Select the folder in which you wish to install your agent.
- Right-click the folder and select Properties.
- Select the Agents tab. (If you do not see an Agents tab, please see the
"When Agents Tab Is Not Shown" section.)
- Click the New button.
- Input a name for this instance of your Agent.
- Select the appropriate check boxes. (Please see the Agent Events
section.)
- Click the Other option button.
- Open the combo box and select your agent.
- Click the Properties button.
- Configure the Property Page as desired.
- Click the OK button.
- 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
- 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.
- 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.
Additional query words:
Keywords : kbfile kbCDO120 kbCDO121 kbXchge550 kbMAPI kbMsg kbVC kbEDK550 kbMAPI100 kbfaq kbGrpMsg
Version : WINDOWS:5.5; winnt:5.5
Platform : WINDOWS winnt
Issue type : kbinfo
|