home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / exchcli.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  9KB  |  232 lines
  1. /* Microsoft Exchange. Copyright 1986 - 1998, Microsoft Corporation -
  2.    All Rights Reserved */
  3.  
  4. /*
  5.  * E X C H C L I . H
  6.  * Client-side Exchange programmability interfaces
  7.  *
  8.  * This file contains interfaces to the following Exchange features:
  9.  *    Enterprise-wide forms registry
  10.  *    Conflict resolution interfaces for forms
  11.  *    Custom actions on inbox management rules
  12.  *
  13.  * Information in this document is subject to change without notice and does
  14.  * not represent a commitment on the part of Microsoft Corporation.
  15.  */
  16.  
  17. #ifndef _EXCHCLI_H_
  18. #define _EXCHCLI_H_
  19.  
  20.  
  21. /* Parameter to IMAPIFormMgr::OpenFormContainer
  22.    denoting the Exchange Enterprise Forms Registry */
  23.  
  24. #if defined(HFRMREG_DEFAULT)
  25. #define HFRMREG_ENTERPRISE 4
  26. #endif
  27.  
  28.  
  29. /* The GUID for Exchange's form extension properties. */
  30.  
  31. #if !defined(INITGUID) || defined(USES_GUID_ExchangeFormExts)
  32. DEFINE_GUID (
  33.     GUID_ExchangeFormExts,
  34.     0x77f69534, 0x6b7d, 0x101b, 0x9f, 0x0d, 0x00, 0xaa, 0x00, 0x3b, 0xa9, 0x05);
  35. #endif
  36. #define IDFEXT_ExchangeResolvesConflict 0
  37.  
  38.  
  39. /*
  40.     Interfaces for "custom actions," the client rule extensions.
  41.  
  42.     Exchange rules are evaluated against each message on the server,
  43.     where matches result in the server executing one or more actions
  44.     against the message.  For purposes of performance and robustness
  45.     the server offers a fixed set of actions.
  46.     However, some actions must necessarily execute on a client machine.
  47.     To allow this, the server encodes the desired action in a message
  48.     (known as a DAM, or Deferred Action Message), then waits for a client
  49.     to open the mailbox and process these client-side action requests.
  50.     Client side actions include popup alerts, cross-store moves and copies,
  51.     and CUSTOM ACTIONS.
  52.  
  53.     Custom actions are the sole rule extensibility mechanism available
  54.     to clients.  A user installs a DLL containing a custom action on
  55.     his workstation, then writes a rule naming this DLL as its action.
  56.     When the server finds a match for the rule, it generates a DAM
  57.     specifying the action named.  Subsequently the client reads the DAM
  58.     and executes the action by invoking the proper DLL.
  59.  
  60.     A custom action DLL very much resembles a Capone super-extension in
  61.     its gross structure.  One installs it on 16 bit platforms by creating
  62.     a section [Custom Actions] in exchng.ini, there adding a key
  63.     "tag=4.0;DLL;ordinal" just as for a superextension.  On 32 bit platforms
  64.     the custom action is specified in the Registry as a name/value pair
  65.     under the registry key:
  66.  
  67.     \\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Exchange\Client\Custom Actions
  68.  
  69.     The name/value pair is identical to that used on the 16 bit platform,
  70.     where the 'name' is the 'tag' mentioned above, and the value is the
  71.     DLL entry point information in the form: "4.0;DLL;ordinal".
  72.  
  73.     The tag should be suitable for display, as the Inbox Assistant will
  74.     use it to represent the custom action for selection in its UI.  DLL
  75.     should contain a fully qualified path to the DLL.  Ordinal is an
  76.     integer denoting the ordinal of the extension entry point; it defaults
  77.     to 1.
  78.  
  79.     That entry point is of type LPFNEXCHANGERULEEXTENTRY: it must allocate
  80.     and return an instance of an IUnknown, off of which the Exchange
  81.     client will QueryInterface the IExchangeRulesExt interface.  All
  82.     subsequent calls will take place through this returned interface.
  83.     Hence a custom action may easily reside in the same DLL as a super
  84.     extension.
  85.  
  86.     Some methods of IExchangeRuleExt are passed an instance of the
  87.     interface IExchangeRuleExtCallback.  This will return the extension
  88.     information about the running Exchange client, including its MAPI
  89.     session (off of which the extension may make calls) and a window
  90.     handle (off of which to parent UI of its own).
  91.  
  92.     After the initial sequence of IUnknown methods, Exchange will
  93.     invoke IExchangeRuleExt::Install.  This informs the extension into which
  94.     context it is being invoked: either ERCONTEXT_INFO, that of the
  95.     Inbox Assistant dialog, in which case it will be called upon to
  96.     get new commands and translate existing commands; or else ERCONTEXT_EXEC,
  97.     that of the client rule execution engine, in which case it will be
  98.     called upon to execute the actual extension commands on a message.
  99.     Return S_FALSE to abort installation or further processing.
  100.  
  101.         HRESULT IExchangeRuleExt::Install(
  102.             LPEXCHANGERULEEXTCALLBACK percb,
  103.                 - an instance of IExchangeRuleExtCallback
  104.             ULONG ulContext
  105.                 - one of ERCONTEXT_INFO or ERCONTEXT_EXEC
  106.             )
  107.  
  108.     The QueryRelease() method is reserved for future use.  For now all rule
  109.     extensions should return S_OK in response to a call on this method.
  110.  
  111.         HRESULT IExchangeRuleExt::QueryRelease()
  112.  
  113.     When a user selects the extension's tag from the Inbox Assistant,
  114.     that extension is queried via IExchangeRuleExt::GetCommand for the
  115.     command encoding it wishes to use.  This is an opportunity for it
  116.     to present further UI refining the user's selection or specifying
  117.     options if necessary.  The extension should return both an
  118.     encoding of the command and a display string suitably representing
  119.     the command to the user.  Return S_OK or S_FALSE as per the user's
  120.     Ok or Cancel to any secondary UI.
  121.  
  122.         HRESULT IExchangeRuleExt::GetCommand(
  123.             LPEXCHANGERULEEXTCALLBACK percb,
  124.                 - an instance of IExchangeRuleExtCallback
  125.             TCHAR FAR* pszCommand, ULONG cchCommand,
  126.                 - an IN/OUT buffer in which to return the encoded command,
  127.                   the buffer may be pre-initialized with a previously
  128.                   existing command for this provider.
  129.                   together with the length of the buffer given
  130.             TCHAR FAR* pszDisplayName, ULONG cchDisplayName
  131.                 - IN/OUT, as the previous buffer, but for the display string
  132.             )
  133.  
  134.     When the Inbox Assistant is invoked to edit an existing rule which
  135.     specifies a custom action, it queries the appropriate extension
  136.     via IExchangeRuleExt::QueryCommandDisplayName for the display string
  137.     corresponding to the encoded command.  This should match the
  138.     display string originally returned from GetCommand.  (Note that
  139.     Exchange does not save the display string when saving the rule.)
  140.  
  141.         HRESULT IExchangeRuleExt::QueryCommandDisplayName(
  142.             LPEXCHANGERULEEXTCALLBACK percb,
  143.                 - an instance of IExchangeRuleExtCallback
  144.             LPCTSTR pszCommand,
  145.                 - the encoded command for which we want the display string
  146.             TCHAR FAR* pszDisplayName, ULONG cchDisplayName
  147.                 - a buffer in which to return the display string,
  148.                   together with the length of the buffer given
  149.             )
  150.  
  151.     At the time that Exchange processes client-side rule actions, any
  152.     custom actions invoked will result in their extensions receiving
  153.     IExchangeRuleExt::Command calls.
  154.  
  155.         HRESULT IExchangeRuleExt::Command(
  156.             LPEXCHANGERULEEXTCALLBACK percb,
  157.                 - an instance of IExchangeRuleExtCallback
  158.             LPCTSTR pszCommand,
  159.                 - the encoded command to execute
  160.             ULONG cb, LPENTRYID peid
  161.                 - the entryid of the message on which to execute
  162.             )
  163.  
  164. */
  165.  
  166. /* Extensibility contexts used with IExchangeRuleExt::Install */
  167.  
  168. #define ERCONTEXT_INFO (0x00000001)
  169. #define ERCONTEXT_EXEC (0x00000002)
  170.  
  171.  
  172. #undef INTERFACE
  173. #define INTERFACE   IExchangeRuleExtCallback
  174.  
  175. DECLARE_INTERFACE_(IExchangeRuleExtCallback, IUnknown)
  176. {
  177.     BEGIN_INTERFACE
  178.     /* IUnknown methods */
  179.     STDMETHOD(QueryInterface) (THIS_ REFIID riid, LPVOID FAR* lppvObj) PURE;
  180.     STDMETHOD_(ULONG,AddRef) (THIS)  PURE;
  181.     STDMETHOD_(ULONG,Release) (THIS) PURE;
  182.  
  183.     /* IExchangeRuleExtCallback methods */
  184.     STDMETHOD(GetVersion) (THIS_ ULONG FAR* pulVersion, ULONG ulFlags) PURE;
  185.     STDMETHOD(GetWindow) (THIS_ HWND FAR* phwnd) PURE;
  186.     STDMETHOD(GetSession) (THIS_ LPMAPISESSION FAR* ppses) PURE;
  187. };
  188. typedef IExchangeRuleExtCallback FAR * LPEXCHANGERULEEXTCALLBACK;
  189.  
  190. #undef INTERFACE
  191. #define INTERFACE   IExchangeRuleExt
  192.  
  193. DECLARE_INTERFACE_(IExchangeRuleExt, IUnknown)
  194. {
  195.     /* IUnknown methods */
  196.     STDMETHOD(QueryInterface) (THIS_ REFIID riid, LPVOID FAR * lppvObj) PURE;
  197.     STDMETHOD_(ULONG,AddRef) (THIS) PURE;
  198.     STDMETHOD_(ULONG,Release) (THIS) PURE;
  199.  
  200.     /* IExchangeRuleExt methods */
  201.     STDMETHOD(Install) (THIS_
  202.         LPEXCHANGERULEEXTCALLBACK percb, ULONG ulContext) PURE;
  203.     STDMETHOD(QueryRelease) (THIS) PURE;
  204.  
  205.     STDMETHOD(GetCommand)(THIS_
  206.         LPEXCHANGERULEEXTCALLBACK percb,
  207.         TCHAR FAR* pszCommand, ULONG cchCommand,
  208.         TCHAR FAR* pszDisplayName, ULONG cchDisplayName) PURE;
  209.     STDMETHOD(QueryCommandDisplayName) (THIS_
  210.         LPEXCHANGERULEEXTCALLBACK percb,
  211.         LPCTSTR pszCommand,
  212.         TCHAR FAR* pszDisplayName, ULONG cchDisplayName) PURE;
  213.  
  214.     STDMETHOD(Command) (THIS_
  215.         LPEXCHANGERULEEXTCALLBACK percb,
  216.         LPCTSTR pszCommand,
  217.         ULONG cb, LPENTRYID peid ) PURE;
  218. };
  219. typedef IExchangeRuleExt FAR* LPEXCHANGERULEEXT;
  220.  
  221.  
  222. /* Type of function called by rules to load a provider */
  223. typedef LPUNKNOWN (CALLBACK * LPFNEXCHANGERULEEXTENTRY)(VOID);
  224.  
  225. #define DEFINE_RULEEXTGUID(name, b) \
  226.     DEFINE_GUID(name, 0x00020E00 | (b), 0, 0, 0xC0,0,0,0,0,0,0,0x46)
  227.  
  228. DEFINE_RULEEXTGUID(IID_IExchangeRuleExtCallback,            0x10);
  229. DEFINE_RULEEXTGUID(IID_IExchangeRuleExt,                    0x11);
  230.  
  231. #endif /* end of file exchcli.h */
  232.