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