HOWTO: Creating an Action for a Rule

• 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.

• 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;
   }

• Mapi32.lib
• Uuid.lib
• Version.lib
• Edkmapi.lib
• Edkutils.lib
• Addrlkup.lib
• Edkguid.lib
• Rulecls.lib
• Edk.h

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