windows-nt/Source/XPSP1/NT/public/sdk/inc/autodiscovery.idl

391 lines
21 KiB
Plaintext
Raw Normal View History

2020-09-26 03:20:57 -05:00
/**************************************************************************\
FILE: AutoDiscovery.idl
DATE: 1/19/2000
DESCRIPTION:
AutoDiscovery API (Object Model).
Copyright 1999-2000 Microsoft Corporation. All Rights Reserved.
\**************************************************************************/
cpp_quote("#ifndef _AUTODISCOVERY_IDL_H_")
cpp_quote("#define _AUTODISCOVERY_IDL_H_")
cpp_quote("// This API started shipping in IE 6")
cpp_quote("#if (_WIN32_IE >= 0x0600)")
midl_pragma warning( disable: 2400 )
//--------------------------------------------------------------------------
//
//--------------------------------------------------------------------------
import "oaidl.idl";
import "ocidl.idl";
import "objidl.idl";
#include <olectl.h>
//--------------------------------------------------------------------------
// Includes
//--------------------------------------------------------------------------
#include "AutoDiscoveryID.h"
//--------------------------------------------------------------------------
// Dependencies
//--------------------------------------------------------------------------
//--------------------------------------------------------------------------
// Interfaces
//--------------------------------------------------------------------------
//--------------------------------------------------------------------------
// Script Interfaces
//--------------------------------------------------------------------------
//--------------------------------------------------------------------------
// Apps Type Library
//--------------------------------------------------------------------------
[
uuid(4EAFB888-81CB-4eba-BAC9-DA254E5721F1), // LIBID_AutoDiscovery
helpstring("Microsoft AutoDiscovery Type Library"),
version(1.0)
]
library AutoDiscovery
{
//----------------------------------------------------------------------
// Standard Type Library Stuff
//----------------------------------------------------------------------
importlib("stdole2.tlb");
interface IAutoDiscoveryProvider;
cpp_quote("#ifndef __LPAUTODISCOVERYPROVIDER_DEFINED")
cpp_quote("#define __LPAUTODISCOVERYPROVIDER_DEFINED")
cpp_quote("//===================================================================")
cpp_quote("//DESCRIPTION:")
cpp_quote("// This object will list the servers that will be tried when attempting")
cpp_quote("//to download results.")
cpp_quote("//")
cpp_quote("//METHODS:")
cpp_quote("//length: The number of servers.")
cpp_quote("//item: Fetch the host name of the server that will be contacted.")
cpp_quote("//===================================================================")
[
object,
oleautomation,
dual,
nonextensible,
uuid(9DCF4A37-01DE-4549-A9CB-3AC31EC23C4F), // IID_IAutoDiscoveryProvider
]
interface IAutoDiscoveryProvider : IDispatch
{
//------------------------------------------------------------------
// Pointer to an interface of this type
//------------------------------------------------------------------
typedef [unique] IAutoDiscoveryProvider *LPAUTODISCOVERYPROVIDER; // For C callers
//------------------------------------------------------------------
// Properties
//------------------------------------------------------------------
[id(DISPIDADMP_PROTOCOL), propget, SZ_DISPIDAD_PROTOCOL, displaybind, bindable] HRESULT length([retval, out] long * pnLength);
[id(DISPIDADMP_SERVERNAME), propget, SZ_DISPIDAD_SERVERNAME, displaybind, bindable] HRESULT item([in] VARIANT varIndex,[retval, out] BSTR * pbstr);
//------------------------------------------------------------------
// Methods
//------------------------------------------------------------------
}
//----------------------------------------------------------------------
// AutoDiscovery Provider Class
//----------------------------------------------------------------------
[
uuid(C4F3D5BF-4809-44e3-84A4-368B6B33B0B4), // CLSID_AutoDiscoveryProvider
helpstring("Mail AutoDiscovery Provider Class"),
]
coclass AutoDiscoveryProvider
{
[default] interface IAutoDiscoveryProvider;
};
cpp_quote("#endif // __LPAUTODISCOVERYPROVIDER_DEFINED")
//======================================================================
// AutoDiscovery features
//======================================================================
interface IMailAutoDiscovery;
cpp_quote("#ifndef __LPACCOUNTDISCOVERY_DEFINED")
cpp_quote("#define __LPACCOUNTDISCOVERY_DEFINED")
cpp_quote("//===================================================================")
cpp_quote("//DESCRIPTION:")
cpp_quote("// This interface can be used by simply calling ::DiscoverNow(). It")
cpp_quote("//will synchronously:")
cpp_quote("//1. use bstrEmailAddress to find the domain name to contact. For example")
cpp_quote("// for JoeUser@yahoo.com, it will contact http://_AutoDiscovery.yahoo.com/_AutoDiscovery/default.asp")
cpp_quote("// and that fails, it will contact then http://yahoo.com/_AutoDiscovery/default.asp.")
cpp_quote("//2. The bstrXMLRequest XML will be put into the HTTP headers so it can")
cpp_quote("// be parsed by the server.")
cpp_quote("//3. The response from the server will be returned in ppXMLResponse")
cpp_quote("//")
cpp_quote("//METHODS:")
cpp_quote("//If you want the operation to happen asynchronously, first call")
cpp_quote("//::WorkAsync(). A subsequent call to ::DiscoverNow() will start the operation and return")
cpp_quote("// immediately and ppXMLResponse will be NULL. The wMsg passed to WorkAsync() will allow")
cpp_quote("// the async thread to send status to the forground window/thread. AutoDiscovery is allowed")
cpp_quote("// to send messages with ID wMsg through wMsg+10. Callers normally will want to pass")
cpp_quote("// (WM_USER + n) for this message ID. These are the messages that the async thread will send:")
cpp_quote("// [wMsg+0]: Means AutoDiscovery ended. The LPARAM will contain the XML normally returned in ppXMLResponse,")
cpp_quote("// except it will be in a BSTR. The wndproc needs to free the LPARAM with SysFreeString()")
cpp_quote("// if it isn't NULL. The WPARAM will contain the HRESULT error value.")
cpp_quote("// [wMsg+1]: Status String. The WPARAM will contain a UNICODE string containing status that can be displayed")
cpp_quote("// to the user. The wndproc needs to call LocalFree() on the WPARAM when done using it. The LPARAM will be NULL.")
cpp_quote("// Calling ::WorkAsync() with a NULL hwnd will indicate that the call should be synchronous,")
cpp_quote("// which is also the default behavior.")
cpp_quote("//===================================================================")
[
object,
oleautomation,
dual,
nonextensible,
uuid(FA202BBC-6ABE-4c17-B184-570B6CF256A6), // IID_IAccountDiscovery
]
interface IAccountDiscovery : IDispatch
{
//------------------------------------------------------------------
// Pointer to an interface of this type
//------------------------------------------------------------------
typedef [unique] IAccountDiscovery *LPACCOUNTDISCOVERY; // For C callers
cpp_quote("// IAccountDiscovery::DiscoverNow() flags")
cpp_quote("#define ADDN_DEFAULT 0x00000000")
cpp_quote("#define ADDN_CONFIGURE_EMAIL_FALLBACK 0x00000001 // We are attempting to configure an email account so contact public servers offering email settings.")
cpp_quote(" // For Example, Microsoft may provide _AutoDiscovery.microsoft.com that can provide email configuration settings for common servers.")
cpp_quote("#define ADDN_SKIP_CACHEDRESULTS 0x00000002 // Download the settings, even if they are already cached.")
cpp_quote("#define ADDN_FILTER_EMAIL 0x00000100 // Some users may want the username part of the email address removed if we need to fall")
cpp_quote(" // back to a public service to get the settings to protect their privacy.")
//------------------------------------------------------------------
// Properties
//------------------------------------------------------------------
//------------------------------------------------------------------
// Methods
//------------------------------------------------------------------
[id(DISPIDAD_DISCOVERNOW), SZ_DISPIDAD_DISCOVERNOW, displaybind] HRESULT DiscoverNow([in] BSTR bstrEmailAddress, [in] DWORD dwFlags, [in] BSTR bstrXMLRequest, [retval, out] IXMLDOMDocument ** ppXMLResponse);
[id(DISPIDAD_WORKASYNC), SZ_DISPIDAD_WORKASYNC, displaybind] HRESULT WorkAsync([in] HWND hwnd, [in] UINT wMsg);
}
cpp_quote("#endif // __LPACCOUNTDISCOVERY_DEFINED")
//----------------------------------------------------------------------
// AutoDiscover Accounts Class
//----------------------------------------------------------------------
[
uuid(3DAB30ED-8132-40bf-A8BA-7B5057F0CD10), // CLSID_AccountDiscovery
helpstring("AutoDiscover Accounts Class"),
]
coclass AccountDiscovery
{
[default] interface IAccountDiscovery;
};
interface IMailProtocolADEntry;
cpp_quote("#ifndef __LPMAILPROTOCOLADENTRY_DEFINED")
cpp_quote("#define __LPMAILPROTOCOLADENTRY_DEFINED")
cpp_quote("//===================================================================")
cpp_quote("//DESCRIPTION:")
cpp_quote("// Methods will return HRESULT_FROM_WIN32(ERROR_NOT_FOUND) if the")
cpp_quote("//information could not be found in the XML results. This will")
cpp_quote("//very often happen with LoginName() and ServerPort().")
cpp_quote("//")
cpp_quote("//METHODS:")
cpp_quote("//Protocol: The name of this protocol. See STR_PT_*.")
cpp_quote("//ServerName: This will be the name of the server to contact.")
cpp_quote("// For DAVMail and WEB, this will be an URL.")
cpp_quote("// For most other protocols, this will be an IP address")
cpp_quote("// or the hostname of the server.")
cpp_quote("//ServerPort: This is the port number on the server to use.")
cpp_quote("//LoginName: The username to log into the email server if a username")
cpp_quote("// other than the username in the email address (<username>@<domainname>)")
cpp_quote("// is needed.")
cpp_quote("//PostHTML: Reserved for future use.")
cpp_quote("//UseSSL: If TRUE, use SSL when connecting to ServerName.")
cpp_quote("//UseSPA: If TRUE, SPA (Secure Password Authenication) should")
cpp_quote("// be used when contacting the server.")
cpp_quote("//IsAuthRequired: This is only applicable to the SMTP protocol.")
cpp_quote("// If TRUE, the SMTP server requires the client to authenticate")
cpp_quote("// when logging in.")
cpp_quote("//SMTPUsesPOP3Auth: This is only applicable to the SMTP protocol.")
cpp_quote("// If TRUE, the login name and password for the POP3 or IMAP")
cpp_quote("// server can be used to log into the SMTP server.")
cpp_quote("//===================================================================")
[
object,
oleautomation,
dual,
nonextensible,
uuid(40EF8C68-D554-47ed-AA37-E5FB6BC91075), // IID_IMailProtocolADEntry
]
interface IMailProtocolADEntry : IDispatch
{
//------------------------------------------------------------------
// Pointer to an interface of this type
//------------------------------------------------------------------
typedef [unique] IMailProtocolADEntry *LPMAILPROTOCOLADENTRY; // For C callers
//------------------------------------------------------------------
// Properties
//------------------------------------------------------------------
[id(DISPIDADMP_PROTOCOL), propget, SZ_DISPIDAD_PROTOCOL, displaybind, bindable] HRESULT Protocol([retval, out] BSTR * pbstr);
[id(DISPIDADMP_SERVERNAME), propget, SZ_DISPIDAD_SERVERNAME, displaybind, bindable] HRESULT ServerName([retval, out] BSTR * pbstr);
[id(DISPIDADMP_SERVERPORTNUM), propget, SZ_DISPIDAD_SERVERPORTNUM, displaybind, bindable] HRESULT ServerPort([retval, out] BSTR * pbstr);
[id(DISPIDADMP_LOGIN_NAME), propget, SZ_DISPIDAD_LOGIN_NAME, displaybind, bindable] HRESULT LoginName([retval, out] BSTR * pbstr);
[id(DISPIDADMP_POST_HTML), propget, SZ_DISPIDAD_POST_HTML, displaybind, bindable] HRESULT PostHTML([retval, out] BSTR * pbstr);
[id(DISPIDADMP_USE_SSL), propget, SZ_DISPIDAD_USE_SSL, displaybind, bindable] HRESULT UseSSL([retval, out] VARIANT_BOOL * pfUseSSL);
[id(DISPIDADMP_ISAUTHREQ), propget, SZ_DISPIDAD_ISAUTHREQ, displaybind, bindable] HRESULT IsAuthRequired([retval, out] VARIANT_BOOL * pfIsAuthRequired);
[id(DISPIDADMP_USESPA), propget, SZ_DISPIDAD_USESPA, displaybind, bindable] HRESULT UseSPA([retval, out] VARIANT_BOOL * pfUseSPA);
[id(DISPIDADMP_SMTPUSESPOP3AUTH), propget, SZ_DISPIDAD_SMTPUSESPOP3AUTH, displaybind, bindable] HRESULT SMTPUsesPOP3Auth([retval, out] VARIANT_BOOL * pfUsePOP3Auth);
//------------------------------------------------------------------
// Methods
//------------------------------------------------------------------
}
cpp_quote("#endif // __LPMAILPROTOCOLADENTRY_DEFINED")
//----------------------------------------------------------------------
// AutoDiscover Accounts Class
//----------------------------------------------------------------------
[
uuid(61A5D6F3-C131-4c35-BF40-90A50F214122), // CLSID_MailProtocolADEntry
helpstring("Mail AutoDiscovery Class"),
]
coclass MailProtocolADEntry
{
[default] interface IMailProtocolADEntry;
};
interface IMailAutoDiscovery;
cpp_quote("#ifndef __LPMAILAUTODISCOVERY_DEFINED")
cpp_quote("#define __LPMAILAUTODISCOVERY_DEFINED")
cpp_quote("//===================================================================")
cpp_quote("//DESCRIPTION:")
cpp_quote("// Methods will return HRESULT_FROM_WIN32(ERROR_NOT_FOUND) if the")
cpp_quote("//information could not be found in the XML results. This will")
cpp_quote("//very often happen with DisplayName() and ServerPort().")
cpp_quote("//")
cpp_quote("//METHODS:")
cpp_quote("//DisplayName: This is the display name or the user's full name that")
cpp_quote("// may or may not be specified by the server.")
cpp_quote("//InfoURL: This is an URL that the server or service can provide")
cpp_quote("// for the user to learn more about the email service")
cpp_quote("// or how to access their email. Email clients that don't")
cpp_quote("// support any of the protocols offered by the server can")
cpp_quote("// launch this URL. The URL can then tell users which")
cpp_quote("// email clients to use or how to configure the email client.")
cpp_quote("// email clients to use or how to configure the email client.")
cpp_quote("//PreferedProtocolType: This will return the server's prefered protocol.")
cpp_quote("// The string will be one of STR_PT_* and can be passed to.")
cpp_quote("// item() to get more information.")
cpp_quote("//length: The number of protocols the server supports.")
cpp_quote("//item: The caller can pass the index of the protocol to access or")
cpp_quote("// ask for a particular protocol (by STR_PT_*).")
cpp_quote("//xml: The caller can get the AutoDiscovery XML from the server.")
cpp_quote("// This will allow email clients to get properties not currently")
cpp_quote("// exposed throught this interface.")
cpp_quote("//PrimaryProviders: Get the list of primary servers that will be")
cpp_quote("// contacted in order to download the results. This will")
cpp_quote("// allow the application to display this list to the user.")
cpp_quote("// The full email password will be uploaded to these servers")
cpp_quote("// in some cases.")
cpp_quote("//SecondaryProviders: This will also list servers that will be contacted")
cpp_quote("// except, as secondary servers, only the user's email hostname")
cpp_quote("// will be uploaded (not the username part of the email address.")
cpp_quote("//")
cpp_quote("//DiscoverMail: Use the email address provided to download the ")
cpp_quote("// AutoDiscovery XML file. This object can then be used to")
cpp_quote("// get information from that XML file.")
cpp_quote("//PurgeCache: If the downloaded settings are cached, purge the")
cpp_quote("// cache so the next call to DiscoverMail() is guaranteed")
cpp_quote("// to get the most current settings from the server.")
cpp_quote("//WorkAsync: See WorkAsync's documentation in IAutoDiscovery.")
cpp_quote("//===================================================================")
[
object,
oleautomation,
dual,
nonextensible,
uuid(80402DEE-B114-4d32-B44E-82FD8234C92A), // IID_IMailAutoDiscovery
]
interface IMailAutoDiscovery : IDispatch
{
//------------------------------------------------------------------
// Pointer to an interface of this type
//------------------------------------------------------------------
typedef [unique] IMailAutoDiscovery *LPMAILAUTODISCOVERY; // For C callers
cpp_quote("// Protocol Types for ServerName(bstrServerType))")
cpp_quote("#define STR_PT_POP L\"POP3\"")
cpp_quote("#define STR_PT_SMTP L\"SMTP\"")
cpp_quote("#define STR_PT_IMAP L\"IMAP\"")
cpp_quote("#define STR_PT_MAPI L\"MAPI\"")
cpp_quote("#define STR_PT_DAVMAIL L\"DAVMail\"")
cpp_quote("#define STR_PT_SMTP L\"SMTP\"")
cpp_quote("#define STR_PT_WEBBASED L\"WEB\" // Web pages are used to receive and send mail.")
//------------------------------------------------------------------
// Properties
//------------------------------------------------------------------
[id(DISPIDAD_DISPLAYNAME), propget, SZ_DISPIDAD_DISPLAYNAME, displaybind, bindable] HRESULT DisplayName([retval, out] BSTR * pbstr);
[id(DISPIDAD_INFOURL), propget, SZ_DISPIDAD_INFOURL, displaybind, bindable] HRESULT InfoURL([retval, out] BSTR * pbstrURL);
[id(DISPIDAD_PREFEREDPROTOCOL), propget, SZ_DISPIDAD_PREFEREDPROTOCOL, displaybind, bindable] HRESULT PreferedProtocolType([retval, out] BSTR * pbstrProtocolType);
[id(DISPIDAD_LENGTH), propget, SZ_DISPIDAD_GETLENGTH, displaybind, bindable] HRESULT length([retval, out] long * pnLength);
[id(DISPIDAD_ITEM), propget, SZ_DISPIDAD_GETITEM, displaybind, bindable] HRESULT item([in] VARIANT varIndex,[retval, out] IMailProtocolADEntry ** ppMailProtocol);
[id(DISPIDAD_XML), propget, SZ_DISPIDAD_GETXML, displaybind, bindable] HRESULT XML([retval, out] IXMLDOMDocument ** ppXMLDoc);
[id(DISPIDAD_XML), propput, SZ_DISPIDAD_PUTXML, displaybind, bindable] HRESULT XML([in] IXMLDOMDocument * pXMLDoc);
//------------------------------------------------------------------
// Methods
//------------------------------------------------------------------
[id(DISPIDADMP_PRIMARYPROVIDERS), SZ_DISPIDAD_PRIMARYPROVIDERS, displaybind] HRESULT getPrimaryProviders([in] BSTR bstrEmailAddress, [retval, out] IAutoDiscoveryProvider ** ppProviders);
[id(DISPIDADMP_SECONDARYPROVIDERS), SZ_DISPIDAD_SECONDARYPROVIDERS, displaybind] HRESULT getSecondaryProviders([in] BSTR bstrEmailAddress, [retval, out] IAutoDiscoveryProvider ** ppProviders);
[id(DISPIDAD_DISCOVERMAIL), SZ_DISPIDAD_DISCOVERMAIL, displaybind] HRESULT DiscoverMail([in] BSTR bstrEmailAddress);
[id(DISPIDAD_PURGE), SZ_DISPIDAD_PURGE, displaybind] HRESULT PurgeCache(void);
[id(DISPIDMAD_WORKASYNC), SZ_DISPIDAD_WORKASYNC, displaybind] HRESULT WorkAsync([in] HWND hwnd, [in] UINT wMsg);
}
cpp_quote("#endif // __LPMAILAUTODISCOVERY_DEFINED")
//----------------------------------------------------------------------
// AutoDiscover Accounts Class
//----------------------------------------------------------------------
[
uuid(008FD5DD-6DBB-48e3-991B-2D3ED658516A), // CLSID_MailAutoDiscovery
helpstring("Mail AutoDiscovery Class"),
]
coclass MailAutoDiscovery
{
[default] interface IMailAutoDiscovery;
};
} // AutoDiscovery Library Object Definition
cpp_quote("#endif // (_WIN32_IE >= 0x0600)")
cpp_quote("#endif // _AUTODISCOVERY_IDL_H_")