Microsoft KB Archive/177210

= How To Creating an Action for a Rule =

Article ID: 177210

Article Last Modified on 7/1/2004

-

APPLIES TO


 * Microsoft Exchange Development Kit 5.5

-



This article was previously published under Q177210



SUMMARY
Understanding the ACTIONS and ACTION structures make creating actions for rules much easier. This article describes both of these structures and provides a code example of a properly created ACTIONS and ACTION structure. The code provided is not complete. It assumes that you already have a handle to a MAPI session, a pointer to the message store, a pointer to the folder the rule is to be applied to, and that you will release the appropriate structures before exiting the function.



MORE INFORMATION
The ACTIONS structure is a collection of ACTION structures. The ACTIONS structure also contains version information and the number of ACTION structures it contains.

The ACTION structure contains the action type. The following is a list of some of the valid action types:
 * OP_FORWARD: Forwards a message to another mailuser.
 * OP_MOVE: Moves a message to another folder.
 * OP_REPLY: Reply to a message with specific text or using a specific form.

The action structure also stores information about what to do with the message. It stores the action flavor when the action is OP_FORWARD. The following is a list of the valid values for action flavor:
 * FWD_PRESERVE_SENDER: Preserves the sender information and indicates the message was autoforwarded.
 * FWD_DO_NOT_MUNGE_MSG: Forwards the message without making any changes to the message.
 * FWD_AS_ATTACHMENT: Makes the message an attachment to the forwarded message.

Steps to Create an Action for a Rule
The following steps and code show how to create an action for a rule.


 * 1) Allocate memory for the ACTIONS structure.
 * 2) Reset the memory to NULL.
 * 3) Set the version, and the number of actions.
 * 4) Set the pointer to the ACTION structure to zero.
 * 5) Allocate memory for the ACTION structure.
 * 6) Reset the ACTION to zero.
 * 7) Allocate the memory for the action to be created and check success.
 * 8) Copy the action string to variable.

Sample Code
// lpActs should defined before the main function. static LPACTIONS    lpActs =       NULL; HRESULT             hr     =       NULL; hr = CreateAction

HRESULT CreateAction(void) {   HRESULT       hr         =   NULL; LPSTR        lpszAction =   NULL;

hr = MAPIAllocateBuffer(sizeof(ACTIONS), (void**)&lpActs); if (FAILED(hr) || lpActs == 0) {      MessageBox(NULL,           "MAPIAllocateBuffer for lpActs failed.",NULL,MB_OK); return 1; }

memset(lpActs, 0, sizeof(ACTIONS));

lpActs->ulVersion = EDK_RULES_VERSION; lpActs->cActions = 1;

lpActs->lpAction = 0;

hr = MAPIAllocateMore(sizeof(ACTION), lpActs,               (LPVOID*)&lpActs->lpAction); if (FAILED(hr) || lpActs->lpAction == 0) {     MessageBox(NULL,          "MAPIAllocateBuffer for lpAct failed.",NULL,MB_OK); return 1; }   memset(lpActs->lpAction, 0, sizeof(ACTION));

/*   // Example of Reply string. hr = MAPIAllocateBuffer(sizeof("Reply \"Reply Text\""),                 (void**) &lpszAction);

// Example of Forward string. hr = MAPIAllocateBuffer(sizeof("Forward \"\""),                 (void**) &lpszAction); */

// Example of Move String. hr = MAPIAllocateBuffer(sizeof("Move Mailbox -           \\Top of Information Store\\Deleted Items"),           (void**) &lpszAction);

if (FAILED(hr)) {      MessageBox(NULL,"Memory Allocation Failed",NULL,MB_OK); return 1; }   // Reply: //wsprintf(lpszAction,"Reply \"Reply Text\"");

// Forward: //wsprintf(lpszAction,"Forward \"\"");

// Move: wsprintf(lpszAction,"Move Mailbox -        \\Top of Information Store\\Deleted Items");

hr = HrStringToAction(lpSession, lpFolder, lpszAction, lpActs,                &lpActs->lpAction[lpActs->cActions-1]);

if (FAILED(hr)) {       MessageBox(NULL,"Action Failed",NULL,MB_OK); return 1; }   return 0; } In order to use this code, the following libraries and headers are required:
 * Mapi32.lib
 * Uuid.lib
 * Version.lib
 * Edkmapi.lib
 * Edkutils.lib
 * Addrlkup.lib
 * Edkguid.lib
 * Rulecls.lib
 * Edk.h

NOTE: This is only one piece of the puzzle for creating rules for folders programmatically. Restrictions are the other piece. This article will be updated with the title and Knowledge Base Article ID discussing restrictions, when it is available.

