HOWTO: Creating an Action for a Rule

ID: Q177210

The information in this article applies to:

Exchange Development Kit (EDK), version 5.0

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 \"<User Name>\""),
                  (void**) &lpszAction);
    */ 

    // Example of Move String.
    hr = MAPIAllocateBuffer(sizeof("Move Mailbox - <User Name>
           \\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 \"<User Name>\"");

    // Move:
    wsprintf(lpszAction,"Move Mailbox - <User Name>
        \\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.

REFERENCES

For more information, please see the following topics in the Microsoft Developer Network Library (MSDN). These topics can be found in the Win32 Messaging Application Program Interface (MAPI) section of the Platform SDK.

Starting a MAPI Session
Opening a Message Store
Opening the Default Message Store
Opening a Folder

Keywords          : kbcode XGEN 
Version           : WINDOWS:5.0
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: January 8, 1998