Managing The Outlook Account Management Dialogs


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

We’ve decided to document another function in the Account Management API, DisplayAccountList. This function allows you to display the Account Settings dialog:

Account Settings

and Add New E-Mail Account property sheet:

Add New E-mail Account

DisplayAccountList hangs off of IOlkAccountManager interface, occupying the second slot in the v-table, like so:

interface IOlkAccountManager : IOlkErrorUnknown
{
public:
	//Init Initializes the account manager for use. 
	virtual STDMETHODIMP Init(IOlkAccountHelper* pAcctHelper, DWORD dwFlags);
	
	//DisplayAccountList Displays the account list wizard
	virtual STDMETHODIMP DisplayAccountList(
		HWND hwnd,
		DWORD dwFlags,
		LPCWSTR lpwszReserved, // Not used
		DWORD dwReserved, // Not used
		const CLSID * pclsidReserved1, // Not used
		const CLSID * pclsidReserved2); // Not used

I’m working on a little sample to demonstrate the Account Manager API that I hope to post soon. It’ll have an updated header. In the meantime, here’s my attempt at MSDN style documentation for the function:

IOlkAccountManager::DisplayAccountList

Initializes the account manager for use.

Quick Info

See IOlkAccountManager.

HRESULT IOlkAccountManager::DisplayAccountList ( 
	HWND hwnd,
	DWORD dwFlags,
	LPCWSTR lpwszReserved,
	DWORD dwReserved,
	const CLSID * pclsidReserved1,
	const CLSID * pclsidReserved2
);

Parameters

hwnd

[in] Handle to the window to which the displayed dialog box is modal. This parameter can be zero.

dwFlags

[in] Flags to modify behavior.
ACCTUI_NO_WARNING
Do not display the warning that changes will not take effect until Outlook is restarted. Only applies if running in process with Outlook.exe.
ACCTUI_SHOW_DATA_TAB
Show the Account Settings dialog with the Data tab selected. Only valid if ACCTUI_SHOW_ACCTWIZARD is not set.
ACCTUI_SHOW_ACCTWIZARD
Display the Add New E-Mail Account wizard.

lpwszReserved,

[in] Not used. Should be NULL.

dwReserved

[in] Not used. Must be NULL.

pclsidReserved1

[in] Not used. Must be NULL.

pclsidReserved2

[in] Not used. Must be NULL.

Return Values

S_OK

The call was successful.

E_OLK_NOT_INITIALIZED

The account manager has not been initialized for use.

MAPI_E_INVALID_PARAMETER

dwReserved, pclsidReserved1 or pclsidReserved2 were non-NULL.

E_ACCT_UI_BUSY

The account dialog class could not be created.

MAPI_E_USER_CANCEL

The Account Settings dialog box returned an error.

MAPI_E_CALL_FAILED

The Add New E-Mail property sheet returned an error.

Remarks

The client calls IOlkAccountManager::DisplayAccountList to display either the Account Settings dialog or the Add New E-mail property sheet. The parameters dwReserved, pclsidReserved1 and pclsidReserved2 are not used at this time and MUST be NULL. The parameter lpwszReserved is not used and SHOULD be NULL.

Constants

#define E_ACCT_UI_BUSY 0x800C8102
#define ACCTUI_NO_WARNING      0x0100
#define ACCTUI_SHOW_DATA_TAB   0x0200
#define ACCTUI_SHOW_ACCTWIZARD 0x0400

BTW – Hey look! Pictures! Woo hoo!

7/3/08 – Update: Added ACCTUI_SHOW_DATA_TAB flag.
Comments (12)

  1. Steve,

    Wouldn’t it be nice if there were a method to add an account without displaying any UI? Am I pushing it? 🙂

    Looking at the values of the documented flags (dwFlags), I have a feeling there are at least a dozen other flags.

    Do you really want people to try to figure them out and then blame MS when things start failing? 🙂

  2. There are around 8 other flags in the headers. Not a single one of them, as best as I could tell, is used. The two I documented are the only ones I see our code looking for. Same with the unused parameters. Three of them are explicitely checked to ensure they’re null, and the fourth is completely ignored. For now anyway. 🙂

  3. <sigh> I was hoping that the lpwszReserved parameter would let me pass an account stamp and see a particular account properties dialog…

  4. I think it may have been so you could pass a title for the dialog – but it was never used.

  5. But I bet there is something to display the Accounts dialog with a particular tab selected.

    This is used in a few places in Outlook, is it not?

  6. You’re right – there’s a flag to set the Data tab. I made a mistake in my test code and thought it wasn’t honored, so I didn’t include it. I’ve added it in. I also went through the whole code path – I don’t think there’s any other flags you can pass. The flags documented are the only ones Outlook ever uses.

    When Outlook displays account setting dialogs with a different tab selected, it’s not using this function.

  7. I was hoping I could pass a GUID (e.g. CSLID_OlkStore) in the pclsidReserved1 parameter, but I’ll take whatever I can 🙂

    Thanks Steve!

  8. Any non-null value there will get you MAPI_E_INVALID_PARAMETER. I know you’re capable of loading this in the debugger and confirming. 🙂

  9. That’s what I did and all values gave me that error 🙂

    Just a sidenote: these flags apply only to Outlook 2007.

    2002/2003 always display the same dialog no matter what the flags are.

  10. No flags work in 2002. ACCTUI_NO_WARNING works in 2003. The documentation (and support) only targets 2007.

  11. Lev says:

    Are we any closer to docs on how to set passwords for SMTP/POP servers programmatically ( for an Internet-mail account )?  ( This is related to Dmitry’s question about configuring an account without UI ).

    Thanks!

  12. Don’t think so – I’ve not been looking at that.