You Dirty Rat


[This is now documented here: http://msdn.microsoft.com/en-us/library/gg262878.aspx ]

Another in the series of APIs Development asked me to document. This time, it’s a property you can request via IDispatch to ask if an item is dirty or not. Same as last time, I didn’t test this code, so I’d appreciate feedback.

dispidFDirty

This property is used to tell if an Outlook item (such as a MailItem or ContactItem) is in the Dirty state. An item is considered Dirty when it has unsaved changes.

Syntax

Given an item pointer, use QueryInterface to obtain an IDispatch interface pointer. Then call IDispatch::Invoke with dispidFDirty and the flags DISPATCH_METHOD | DISPATCH_PROPERTYGET.

Sample Code

#define dispidFDirty 0xF024

bool FIsItemDirty(IDispatch *pdisp)
{
    DISPPARAMS dispparams;
    UINT uArgErr;
    HRESULT hr = S_OK;
    CComVariant varDirty;
    dispparams.rgvarg = 0;
    dispparams.cArgs = 0;
    dispparams.cNamedArgs = 0;
    dispparams.rgdispidNamedArgs = NULL;

    hr = pdisp->Invoke(dispidFDirty,
        IID_NULL,
        LOCALE_SYSTEM_DEFAULT,
        DISPATCH_METHOD | DISPATCH_PROPERTYGET,
        &dispparams,
        &varDirty,
        NULL,
        &uArgErr);
    return SUCCEEDED(hr) && varDirty.bVal;
}
Comments (9)

  1. Murray says:

    Can you force Outlook to think an item is not dirty using the same method (DISPATCH_PROPERTYSET)?

  2. Stephen Griffin says:

    Good question! Let us know what you find. 🙂

  3. Murray says:

    Is this different from the existing MailItem Saved property?

  4. Dmitry Streblechenko says:

    Nope. Raises DISP_E_EXCEPTION – "Property is read-only".

    Bummer…

  5. Murray says:

    Setting the property doesn't work, Outlook throws an error.

  6. Stephen Griffin says:

    RE: MailItem Saved – I would assume it's different. Note that this dispid can be invoked against any item type.

  7. Dmitry Streblechenko says:

    It looks like Saved and dispidFDirty return the same value in all cases.

    Also, Saved property is exposed by all the Item objects (MaiulItem, ContactItem, etc), not just MailItem.

    What makes dispidFDirty different from Saved?

  8. Stephen Griffin says:

    I think you mean it returns the *opposite* value in all cases, correct? 🙂 As far as I can tell, one is the inverse of the other.

  9. Dmitry Streblechenko says:

    Yes, I meant that they are consistently the opposite of each other.