/// <summary>
/// Resolves a recipient name using the Simple MAPI address book.</summary>
/// <param name="name">
/// Recipient name to be resolved. This name may be incomplete, misspelled, or otherwise
/// ambiguous.</param>
/// <returns>
/// A <see cref="MapiAddress"/> holding the unambiguous address book name that is the
/// closest match for the specified <paramref name="name"/>, and the corresponding default
/// e-mail address.</returns>
/// <exception cref="ArgumentNullOrEmptyException">
/// <paramref name="name"/> is a null reference or an empty string.</exception>
/// <exception cref="MapiException">
/// <see cref="Mapi.MAPIResolveName"/> indicated an error.</exception>
/// <remarks><para>
/// <b>ResolveName</b> determines the unambiguous address book entry of the specified
/// recipient, using the Win32 API call <see cref="Mapi.MAPIResolveName"/> which is part of
/// the Simple MAPI protocol.
/// </para><para>
/// If no match is found or the specified <paramref name="name"/> resolves to more than one
/// address book entry, the user is presented with an address book dialog and asked to
/// select an entry. User cancellation generates a <see cref="MapiException"/> whose <see
/// cref="MapiException.Code"/> may be <see cref="MapiException.Abort"/> but also any other
/// <see cref="MapiError"/> code, depending on the MAPI server.
/// </para><note type="caution">
/// Non-Microsoft e-mail clients rarely support <b>MAPIResolveName</b>. Some might report an
/// error while others might return empty strings or invalid data. There is no workaround
/// other than using a Microsoft program as the default e-mail client.</note></remarks>
public static MapiAddress ResolveName(string name)
{
if (String.IsNullOrEmpty(name))
{
ThrowHelper.ThrowArgumentNullOrEmptyException("name");
}
// remember current working directory
string currentDir = Directory.GetCurrentDirectory();
// prepare recipient structure
SafeMapiHandle lpRecip = null;
try {
// invoke MAPIResolveName to resolve this name
MapiFlags flags = MapiFlags.MAPI_DIALOG | MapiFlags.MAPI_LOGON_UI;
MapiError code = Mapi.MAPIResolveName(UIntPtr.Zero,
UIntPtr.Zero, name, flags, 0, out lpRecip);
// check for null recipient (buggy MAPI server)
if (code == MapiError.SUCCESS_SUCCESS && (lpRecip == null || lpRecip.IsInvalid))
{
code = MapiError.MAPI_E_FAILURE;
}
// throw exception if MAPI reports failure
if (code != MapiError.SUCCESS_SUCCESS)
{
ThrowMapiException(code);
}
// retrieve unmanaged memory block on success
MapiRecipDesc recip = (MapiRecipDesc)lpRecip.GetMemory(0, typeof(MapiRecipDesc));
// return recipient name and address
return(new MapiAddress(recip.lpszName, recip.lpszAddress));
}
finally {
// release unmanaged memory block
if (lpRecip != null)
{
lpRecip.Dispose();
}
// restore original working directory
Directory.SetCurrentDirectory(currentDir);
}
}
