Notice: This website is an unofficial Microsoft Knowledge Base (hereinafter KB) archive and is intended to provide a reliable access to deleted content from Microsoft KB. All KB articles are owned by Microsoft Corporation. Read full disclaimer for more details.

How to create an Out-Of-Office rule with Extended MAPI


View products that this article applies to.

Summary

This step-by-step article describes how to create an out-of-office rule with Extended MAPI.

Collaboration Data Objects (CDO) 1.21 provides a simple mechanism for setting out-of-office (OOF) text and turning the OOF state on and off. Because CDO 1.21 uses Extended MAPI, it is possible to achieve the same results by using Extended MAPI code. This may be useful if you are already using Extended MAPI and do not want to mix MAPI and CDO.

Creating an OOF rule consists of two steps: creating the OOF reply message and adding a rule to the rules table for the Inbox.

Creating the OOF Reply Message

  1. Create a new MAPI message in the Inbox's associated contents table.
  2. Set the message class (PR_MESSAGE_CLASS) to "IPM.Note.Rules.OofTemplate.Microsoft".
  3. Set the body (PR_BODY) of the message to your desired OOF reply.

Adding an OOF Rule to the Rules Table

  1. Open the PR_RULES_TABLE property on the Inbox with the IExchangeModifyTable interface.
  2. Add a new row to the table with the following MAPI properties set:
    • PR_RULE_SEQUENCE
    • PR_RULE_PROVIDER
    • PR_RULE_STATE
    • PR_RULE_USER_FLAGS
    • PR_RULE_CONDITION
    • PR_RULE_ACTIONS

    See the sample code below for the required values.

Turning the OOF State On and Off

The OOF state is held in one boolean property on the information store, PR_OOF_STATE. Setting the OOF state is as simple as setting this property.

Sample Code

/*********************************************************************************

  CreateOOF.cpp

  This file contains code that demonstrates how to create an OOF rule and enable
  OOF using Extended MAPI.

  The relevant functions are CreateOOF, which creates the OOF rule, and 
  SetOOFState, which toggles the OOF state.

  To build this code, you need to add the following files to your link settings:
  - msvcrt.lib 
  - edkguid.lib 
  - edkmapi.lib 
  - edkdebug.lib 
  - edkutils.lib 
  - mapi32.lib

  This code is provided as a sample only.  Microsoft offers no warranty or
  support for it.  Use at your own risk.

*********************************************************************************/ 

#include <mapix.h>
#include <mapidefs.h>
#include <edk.h>
#include <stdio.h>

// Text used in OOF reply.
#define OOF_TEXT "I'm currently out of the office."

// Macro to get the number of bytes needed for MAPIAllocateBuffer for a ROWLIST.
#define CbNewROWLIST(_centries) (offsetof(ROWLIST,aEntries) + (_centries)*sizeof(ROWENTRY))

// Forward function declarations.
HRESULT CreateOOF(LPMAPIFOLDER lpFolder, LPSTR lpszOOFText);
HRESULT SetOOFState(LPMDB lpMDB, bool bState);

// main
void main()
{
    HRESULT         hRes = S_OK;            // MAPI return code.
    LPMAPISESSION   lpSession = NULL;       // Session pointer.
    LPMDB           lpMDB = NULL;           // Information store pointer.
    LPMAPIFOLDER    lpInbox = NULL;         // Folder pointer.
    LPENTRYID       lpStoreEID = NULL;      // Pointer to entry ID of message store.
    ULONG           cbStoreEID = 0;         // Count of bytes in message store entry ID.
    LPENTRYID       lpInboxEID = NULL;      // Pointer to entry ID of Inbox.
    ULONG           cbInboxEID = 0;         // Count of bytes in Inbox entry ID.
    ULONG           ulObjType = 0;          // Object Type indicator.
    
    // Initialize MAPI.
    if (FAILED(hRes = MAPIInitialize(NULL))) 
    {
        printf("MAPIInitialize failed in main.\n");
        goto error;
    }

    // Log on.
    printf("Choose the profile that you want to create a new OOF rule in.\n");

    if (FAILED(hRes = MAPILogonEx(NULL,
                                  NULL,
                                  NULL,
                                  MAPI_LOGON_UI | 
                                  MAPI_NEW_SESSION |
                                  MAPI_NO_MAIL,
                                  &lpSession)))
    {
        printf("MAPILogonEx failed in main.\n");
        goto error;
    }

    // Get the default message store.
    if (FAILED(hRes = HrMAPIFindDefaultMsgStore(lpSession, 
                                                &cbStoreEID, 
                                                &lpStoreEID)))
    {
        printf("HrMAPIFindDefaultMsgStore failed in main.\n");
        goto error;
    }

    // Open the default message store.
    if (FAILED(hRes = lpSession->OpenMsgStore(NULL,
                                              cbStoreEID,
                                              lpStoreEID,
                                              NULL,
                                              MAPI_BEST_ACCESS,
                                              &lpMDB)))
    {
        printf("OpenMsgStore failed in main.\n");
        goto error;
    }

    // Get the Inbox.
    if (FAILED(hRes = lpMDB->GetReceiveFolder(NULL,
                                              NULL,
                                              &cbInboxEID,
                                              &lpInboxEID,
                                              NULL)))
    {
        printf("GetReceiveFolder failed in main.\n");
        goto error;
    }

    // Open the Inbox.
    if (FAILED(hRes = lpMDB->OpenEntry(cbInboxEID,
                                       lpInboxEID,
                                       NULL,
                                       MAPI_BEST_ACCESS,
                                       &ulObjType,
                                       (LPUNKNOWN *)&lpInbox)))
    {
        printf("OpenEntry failed in main.\n");
        goto error;
    }

    // Create the OOF rule.
    if (FAILED(hRes = CreateOOF(lpInbox, OOF_TEXT)))
    {
        printf("CreateOOF failed in main.\n");
        goto error;
    }

    // Set OOF state to true.
    if (FAILED(hRes = SetOOFState(lpMDB, TRUE)))
    {
        printf("EnableOOF failed in main.\n");
        goto error;
    }

    // Log off.
    if (FAILED(hRes = lpSession->Logoff(0,0,0)))
    {
        printf("Logoff failed in main.\n");
        goto error;
    }

    goto cleanup;

    // Report error number.
error:
    printf("ERROR: hRes = 0%x\n", hRes);

    // Clean up memory and uninitialize MAPI.
cleanup:
    if (lpInbox) lpInbox->Release();
    if (lpMDB) lpMDB->Release();
    if (lpSession) lpSession->Release();

    MAPIUninitialize();
}

// CreateOOF.
HRESULT CreateOOF(LPMAPIFOLDER lpFolder, LPSTR lpszOOFText)
{
    HRESULT                 hRes = S_OK;            // MAPI return code.
    LPMESSAGE               lpOOFMsg = NULL;        // OOF Message pointer.
    LPEXCHANGEMODIFYTABLE   lpExchModTable = NULL;  // Rule Table pointer.
    ACTION                  *lpAction = NULL;       // ACTION pointer.
    ACTIONS                 *lpActions = NULL;      // ACTIONS pointer.
    SPropValue              OOFProps[2];            // Properties to set on OOF message.
    SPropValue              RuleProps[6];           // Properties to set on OOF rule.
    LPSPropValue            lpOOFEID = NULL;        // PR_ENTRYID for the OOF message.
    ULONG                   ulCount = 0;            // Count of props returned by GetProps.
    LPROWLIST               lpRowList = NULL;       // Row List pointer.

    SPropTagArray   taga = {1, {PR_ENTRYID}};       // Props to return from GetProps.

    // Open the rules table with an IExchangeModifyTable interface.
    if (FAILED(hRes = lpFolder->OpenProperty(PR_RULES_TABLE,
                                             (LPGUID)&IID_IExchangeModifyTable,
                                             0,
                                             MAPI_DEFERRED_ERRORS,
                                             (LPUNKNOWN *)&lpExchModTable)))
    {
        printf("OpenProperty failed in CreateOOF.\n");
        goto error;
    }

    // Create a new message in the associated contents table.
    if (FAILED(hRes = lpFolder->CreateMessage(NULL,
                                              MAPI_DEFERRED_ERRORS |
                                              MAPI_ASSOCIATED,
                                              &lpOOFMsg)))
    {
        printf("CreateMessage failed in CreateOOF.\n");
        goto error;
    }

    // Set up the property structure for the OOF message properties.
    // First the body.
    OOFProps[0].ulPropTag = PR_BODY;
    OOFProps[0].Value.lpszA = lpszOOFText;

    // Then the message class.
    OOFProps[1].ulPropTag = PR_MESSAGE_CLASS;
    OOFProps[1].Value.lpszA = "IPM.Note.Rules.OofTemplate.Microsoft";

    // Set the properties on the message.
    if (FAILED(hRes = lpOOFMsg->SetProps(2, OOFProps, NULL)))
    {
        printf("SetProps failed in CreateOOF.\n");
        goto error;
    }

    // Commit our changes to the message.
    if (FAILED(hRes = lpOOFMsg->SaveChanges(KEEP_OPEN_READWRITE | FORCE_SAVE)))
    {
        printf("SaveChanges failed in CreateOOF.\n");
        goto error;
    }

    // Get the entry ID of the message.
    if (FAILED(hRes = lpOOFMsg->GetProps(&taga, NULL, &ulCount, &lpOOFEID)))
    {
        printf("GetProps failed in CreateOOF.\n");
        goto error;
    }

    // Allocate space for an ACTION structure.
    if (FAILED(hRes = MAPIAllocateBuffer(sizeof(ACTION), (LPVOID *) &lpAction)))
    {
        printf("MAPIAllocateBuffer for ACTION failed in CreateOOF.\n");
        goto error;
    }

    // Allocate space for an ACTIONS structure.
    if (FAILED(hRes = MAPIAllocateBuffer(sizeof(ACTIONS), (LPVOID *) &lpActions)))
    {
        printf("MAPIAllocateBuffer for ACTIONS failed in CreateOOF.\n");
        goto error;
    }

    // Clear the memory.
    memset(lpAction, 0, sizeof(ACTION));
    memset(lpActions, 0, sizeof(ACTIONS));

    // Set up the ACTIONS structure.

    // Set the rule version
    lpActions->ulVersion = EDK_RULES_VERSION;
    // Set the number of actions
    lpActions->cActions = 1;
    // Set the pointer to the action
    lpActions->lpAction = lpAction;

    // Set up the ACTION structure.

    // Set up the type of action.
    lpAction->acttype = OP_OOF_REPLY;
    // Because it is an OOF reply, associate the action with our OOF message.
    lpAction->actReply.cbEntryId = lpOOFEID->Value.bin.cb;
    lpAction->actReply.lpEntryId = (LPENTRYID)lpOOFEID->Value.bin.lpb;

    // Clear the ReplyTemplate GUID.
    memset(&lpAction->actReply.guidReplyTemplate, 0, sizeof(GUID));

    // Set up the rule properties.

    // Set rule sequence to 0.
    RuleProps[0].ulPropTag = PR_RULE_SEQUENCE;
    RuleProps[0].Value.ul = 0;

    // Set the rule provider.
    RuleProps[1].ulPropTag = PR_RULE_PROVIDER;
    RuleProps[1].Value.lpszA = "MSFT:TDX OOF Rules";

    // Set the rule state for OOF.
    RuleProps[2].ulPropTag = PR_RULE_STATE;
    RuleProps[2].Value.ul = ST_ENABLED | ST_KEEP_OOF_HIST | ST_ONLY_WHEN_OOF;

    // Set the user flags to 2.
    RuleProps[3].ulPropTag = PR_RULE_USER_FLAGS;
    RuleProps[3].Value.ul = 2;

    // Set the condition to NULL (fires on all messages).
    RuleProps[4].ulPropTag = PR_RULE_CONDITION;
    RuleProps[4].Value.ul = NULL;

    // Set the actions for the rule to our ACTIONS structure.
    RuleProps[5].ulPropTag = PR_RULE_ACTIONS;
    RuleProps[5].Value.ul = (ULONG) lpActions;

    // Allocate space for the rowlist for ModifyTable.
    if (FAILED(hRes = MAPIAllocateBuffer(CbNewROWLIST(1), (LPVOID *)&lpRowList)))
    {
        printf("MAPIAllocateBuffer for ROWLIST failed in CreateOOF.\n");
        goto error;
    }

    // Set up the row list.

    // Number of entries.
    lpRowList->cEntries = 1;
    // Type of operation.
    lpRowList->aEntries->ulRowFlags = ROW_ADD;
    // Number of properties being set.
    lpRowList->aEntries->cValues = 6;
    // Pointer to properties.
    lpRowList->aEntries->rgPropVals = RuleProps;

    // Call ModifyTable on rule table to add our OOF rule.
    if (FAILED(hRes = lpExchModTable->ModifyTable(0, lpRowList)))
    {
        printf("ModifyTable failed in CreateOOF.\n");
        goto error;
    }

    goto cleanup;

    // Report error.
error:
    printf("ERROR: hRes = 0%x\n", hRes);

    // Clean up memory.
cleanup:
    if (lpRowList) MAPIFreeBuffer(lpRowList);
    if (lpAction) MAPIFreeBuffer(lpAction);
    if (lpActions) MAPIFreeBuffer(lpActions);
    if (lpOOFMsg) lpOOFMsg->Release();

    return hRes;

}

// SetOOFState
HRESULT SetOOFState(LPMDB lpMDB, bool bState)
{
    HRESULT     hRes = S_OK;    // MAPI Return code
    SPropValue  OOFProp;        // OOF property

    // Set up the OOF property.
    OOFProp.ulPropTag = PR_OOF_STATE;
    OOFProp.Value.b = bState;

    // Set the property on the information store.
    if (FAILED(hRes = lpMDB->SetProps(1, &OOFProp, NULL)))
        goto error;

    return hRes;

    // Report error.
error:
    printf("Error in EnableOOF.  OOF State couldn't be set.\n");
    printf("hRes = 0%x\n", hRes);
    return hRes;
}
				

↑ Back to the top


Keywords: KB308281, kbmsg, kbhowtomaster

↑ Back to the top

Article Info
Article ID : 308281
Revision : 8
Created on : 10/25/2007
Published on : 10/25/2007
Exists online : False
Views : 500