home *** CD-ROM | disk | FTP | other *** search
/ PC Format (South-Africa) 2001 June / PCFJune.iso / Xenon / C++ / FreeCommandLineTools.exe / Include / mapiutil.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-01-31  |  29.9 KB  |  885 lines
  1. /*
  2.  *  M A P I U T I L . H
  3.  *
  4.  *  Definitions and prototypes for utility functions provided by MAPI
  5.  *  in MAPI[xx].DLL.
  6.  *
  7.  *  Copyright 1986-1996 Microsoft Corporation. All Rights Reserved.
  8.  */
  9.  
  10. #ifndef _MAPIUTIL_H_
  11. #pragma option push -b -a8 -pc -A- /*P_O_Push*/
  12. #define _MAPIUTIL_H_
  13.  
  14. #if defined (WIN32) && !defined (_WIN32)
  15. #define _WIN32
  16. #endif
  17.  
  18. #ifdef __cplusplus
  19. extern "C" {
  20. #endif
  21.  
  22. #ifndef MAPIX_H
  23. #include <mapix.h>
  24. #endif
  25.  
  26. #ifdef WIN16
  27. #include <storage.h>
  28. #endif
  29.  
  30. #ifndef BEGIN_INTERFACE
  31. #define BEGIN_INTERFACE
  32. #endif
  33.  
  34.  
  35. /* IMAPITable in memory */
  36.  
  37. /* ITableData Interface ---------------------------------------------------- */
  38.  
  39. DECLARE_MAPI_INTERFACE_PTR(ITableData, LPTABLEDATA);
  40.  
  41. typedef void (STDAPICALLTYPE CALLERRELEASE)(
  42.     ULONG       ulCallerData,
  43.     LPTABLEDATA lpTblData,
  44.     LPMAPITABLE lpVue
  45. );
  46.  
  47. #define MAPI_ITABLEDATA_METHODS(IPURE)                                  \
  48.     MAPIMETHOD(HrGetView)                                               \
  49.         (THIS_  LPSSortOrderSet             lpSSortOrderSet,            \
  50.                 CALLERRELEASE FAR *         lpfCallerRelease,           \
  51.                 ULONG                       ulCallerData,               \
  52.                 LPMAPITABLE FAR *           lppMAPITable) IPURE;        \
  53.     MAPIMETHOD(HrModifyRow)                                             \
  54.         (THIS_  LPSRow) IPURE;                                          \
  55.     MAPIMETHOD(HrDeleteRow)                                             \
  56.         (THIS_  LPSPropValue                lpSPropValue) IPURE;        \
  57.     MAPIMETHOD(HrQueryRow)                                              \
  58.         (THIS_  LPSPropValue                lpsPropValue,               \
  59.                 LPSRow FAR *                lppSRow,                    \
  60.                 ULONG FAR *                 lpuliRow) IPURE;            \
  61.     MAPIMETHOD(HrEnumRow)                                               \
  62.         (THIS_  ULONG                       ulRowNumber,                \
  63.                 LPSRow FAR *                lppSRow) IPURE;             \
  64.     MAPIMETHOD(HrNotify)                                                \
  65.         (THIS_  ULONG                       ulFlags,                    \
  66.                 ULONG                       cValues,                    \
  67.                 LPSPropValue                lpSPropValue) IPURE;        \
  68.     MAPIMETHOD(HrInsertRow)                                             \
  69.         (THIS_  ULONG                       uliRow,                     \
  70.                 LPSRow                      lpSRow) IPURE;              \
  71.     MAPIMETHOD(HrModifyRows)                                            \
  72.         (THIS_  ULONG                       ulFlags,                    \
  73.                 LPSRowSet                   lpSRowSet) IPURE;           \
  74.     MAPIMETHOD(HrDeleteRows)                                            \
  75.         (THIS_  ULONG                       ulFlags,                    \
  76.                 LPSRowSet                   lprowsetToDelete,           \
  77.                 ULONG FAR *                 cRowsDeleted) IPURE;        \
  78.  
  79. #undef       INTERFACE
  80. #define      INTERFACE  ITableData
  81. DECLARE_MAPI_INTERFACE_(ITableData, IUnknown)
  82. {
  83.     BEGIN_INTERFACE
  84.     MAPI_IUNKNOWN_METHODS(PURE)
  85.     MAPI_ITABLEDATA_METHODS(PURE)
  86. };
  87.  
  88.  
  89. /* Entry Point for in memory ITable */
  90.  
  91.  
  92. /*  CreateTable()
  93.  *      Creates the internal memory structures and object handle
  94.  *      to bring a new table into existence.
  95.  *
  96.  *  lpInterface
  97.  *      Interface ID of the TableData object (IID_IMAPITableData)
  98.  *
  99.  *  lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer
  100.  *      Function addresses are provided by the caller so that
  101.  *      this DLL allocates/frees memory appropriately.
  102.  *  lpvReserved
  103.  *      Reserved.  Should be NULL.
  104.  *  ulTableType
  105.  *      TBLTYPE_DYNAMIC, etc.  Visible to the calling application
  106.  *      as part of the GetStatus return data on its views
  107.  *  ulPropTagIndexColumn
  108.  *      Index column for use when changing the data
  109.  *  lpSPropTagArrayColumns
  110.  *      Column proptags for the minimum set of columns in the table
  111.  *  lppTableData
  112.  *      Address of the pointer which will receive the TableData object
  113.  */
  114.  
  115. STDAPI_(SCODE)
  116. CreateTable( LPCIID                 lpInterface,
  117.              ALLOCATEBUFFER FAR *   lpAllocateBuffer,
  118.              ALLOCATEMORE FAR *     lpAllocateMore,
  119.              FREEBUFFER FAR *       lpFreeBuffer,
  120.              LPVOID                 lpvReserved,
  121.              ULONG                  ulTableType,
  122.              ULONG                  ulPropTagIndexColumn,
  123.              LPSPropTagArray        lpSPropTagArrayColumns,
  124.              LPTABLEDATA FAR *      lppTableData );
  125.  
  126. /*  HrGetView()
  127.  *      This function obtains a new view on the underlying data
  128.  *      which supports the IMAPITable interface.  All rows and columns
  129.  *      of the underlying table data are initially visible
  130.  *  lpSSortOrderSet
  131.  *      if specified, results in the view being sorted
  132.  *  lpfCallerRelease
  133.  *      pointer to a routine to be called when the view is released, or
  134.  *      NULL.
  135.  *  ulCallerData
  136.  *      arbitrary data the caller wants saved with this view and returned in
  137.  *      the Release callback.
  138.  */
  139.  
  140. /*  HrModifyRows()
  141.  *      Add or modify a set of rows in the table data
  142.  *  ulFlags
  143.  *      Must be zero
  144.  *  lpSRowSet
  145.  *      Each row in the row set contains all the properties for one row
  146.  *      in the table.  One of the properties must be the index column.  Any
  147.  *      row in the table with the same value for its index column is
  148.  *      replaced, or if there is no current row with that value the
  149.  *      row is added.
  150.  *      Each row in LPSRowSet MUST have a unique Index column!
  151.  *      If any views are open, the view is updated as well.
  152.  *      The properties do not have to be in the same order as the
  153.  *      columns in the current table
  154.  */
  155.  
  156. /*  HrModifyRow()
  157.  *      Add or modify one row in the table
  158.  *  lpSRow
  159.  *      This row contains all the properties for one row in the table.
  160.  *      One of the properties must be the index column.  Any row in
  161.  *      the table with the same value for its index column is
  162.  *      replaced, or if there is no current row with that value the
  163.  *      row is added
  164.  *      If any views are open, the view is updated as well.
  165.  *      The properties do not have to be in the same order as the
  166.  *      columns in the current table
  167.  */
  168.  
  169. /*  HrDeleteRows()
  170.  *      Delete a row in the table.
  171.  *  ulFlags
  172.  *      TAD_ALL_ROWS - Causes all rows in the table to be deleted
  173.  *                     lpSRowSet is ignored in this case.
  174.  *  lpSRowSet
  175.  *      Each row in the row set contains all the properties for one row
  176.  *      in the table.  One of the properties must be the index column.  Any
  177.  *      row in the table with the same value for its index column is
  178.  *      deleted.
  179.  *      Each row in LPSRowSet MUST have a unique Index column!
  180.  *      If any views are open, the view is updated as well.
  181.  *      The properties do not have to be in the same order as the
  182.  *      columns in the current table
  183.  */
  184. #define TAD_ALL_ROWS    1
  185.  
  186. /*  HrDeleteRow()
  187.  *      Delete a row in the table.
  188.  *  lpSPropValue
  189.  *      This property value specifies the row which has this value
  190.  *      for its index column
  191.  */
  192.  
  193. /*  HrQueryRow()
  194.  *      Returns the values of a specified row in the table
  195.  *  lpSPropValue
  196.  *      This property value specifies the row which has this value
  197.  *      for its index column
  198.  *  lppSRow
  199.  *      Address of where to return a pointer to an SRow
  200.  *  lpuliRow
  201.  *    Address of where to return the row number. This can be NULL
  202.  *    if the row number is not required.
  203.  *
  204.  */
  205.  
  206. /*  HrEnumRow()
  207.  *      Returns the values of a specific (numbered) row in the table
  208.  *  ulRowNumber
  209.  *      Indicates row number 0 to n-1
  210.  *  lppSRow
  211.  *      Address of where to return a pointer to a SRow
  212.  */
  213.  
  214. /*  HrInsertRow()
  215.  *      Inserts a row into the table.
  216.  *  uliRow
  217.  *      The row number before which this row will be inserted into the table.
  218.  *      Row numbers can be from 0 to n where o to n-1 result in row insertion
  219.  *    a row number of n results in the row being appended to the table.
  220.  *  lpSRow
  221.  *      This row contains all the properties for one row in the table.
  222.  *      One of the properties must be the index column.  Any row in
  223.  *      the table with the same value for its index column is
  224.  *      replaced, or if there is no current row with that value the
  225.  *      row is added
  226.  *      If any views are open, the view is updated as well.
  227.  *      The properties do not have to be in the same order as the
  228.  *      columns in the current table
  229.  */
  230.  
  231.  
  232. /* IMAPIProp in memory */
  233.  
  234. /* IPropData Interface ---------------------------------------------------- */
  235.  
  236.  
  237. #define MAPI_IPROPDATA_METHODS(IPURE)                                   \
  238.     MAPIMETHOD(HrSetObjAccess)                                          \
  239.         (THIS_  ULONG                       ulAccess) IPURE;            \
  240.     MAPIMETHOD(HrSetPropAccess)                                         \
  241.         (THIS_  LPSPropTagArray             lpPropTagArray,             \
  242.                 ULONG FAR *                 rgulAccess) IPURE;          \
  243.     MAPIMETHOD(HrGetPropAccess)                                         \
  244.         (THIS_  LPSPropTagArray FAR *       lppPropTagArray,            \
  245.                 ULONG FAR * FAR *           lprgulAccess) IPURE;        \
  246.     MAPIMETHOD(HrAddObjProps)                                           \
  247.         (THIS_  LPSPropTagArray             lppPropTagArray,            \
  248.                 LPSPropProblemArray FAR *   lprgulAccess) IPURE;
  249.  
  250.  
  251. #undef       INTERFACE
  252. #define      INTERFACE  IPropData
  253. DECLARE_MAPI_INTERFACE_(IPropData, IMAPIProp)
  254. {
  255.     BEGIN_INTERFACE
  256.     MAPI_IUNKNOWN_METHODS(PURE)
  257.     MAPI_IMAPIPROP_METHODS(PURE)
  258.     MAPI_IPROPDATA_METHODS(PURE)
  259. };
  260.  
  261. DECLARE_MAPI_INTERFACE_PTR(IPropData, LPPROPDATA);
  262.  
  263.  
  264. /* Entry Point for in memory IMAPIProp */
  265.  
  266.  
  267. /*  CreateIProp()
  268.  *      Creates the internal memory structures and object handle
  269.  *      to bring a new property interface into existance.
  270.  *
  271.  *  lpInterface
  272.  *      Interface ID of the TableData object (IID_IMAPIPropData)
  273.  *
  274.  *  lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer
  275.  *      Function addresses are provided by the caller so that
  276.  *      this DLL allocates/frees memory appropriately.
  277.  *  lppPropData
  278.  *      Address of the pointer which will receive the IPropData object
  279.  *  lpvReserved
  280.  *      Reserved.  Should be NULL.
  281.  */
  282.  
  283. STDAPI_(SCODE)
  284. CreateIProp( LPCIID                 lpInterface,
  285.              ALLOCATEBUFFER FAR *   lpAllocateBuffer,
  286.              ALLOCATEMORE FAR *     lpAllocateMore,
  287.              FREEBUFFER FAR *       lpFreeBuffer,
  288.              LPVOID                 lpvReserved,
  289.              LPPROPDATA FAR *       lppPropData );
  290.  
  291. /*
  292.  *  Defines for prop/obj access
  293.  */
  294. #define IPROP_READONLY      ((ULONG) 0x00000001)
  295. #define IPROP_READWRITE     ((ULONG) 0x00000002)
  296. #define IPROP_CLEAN         ((ULONG) 0x00010000)
  297. #define IPROP_DIRTY         ((ULONG) 0x00020000)
  298.  
  299. /*
  300.  -  HrSetPropAccess
  301.  -
  302.  *  Sets access right attributes on a per-property basis.  By default,
  303.  *  all properties are read/write.
  304.  *
  305.  */
  306.  
  307. /*
  308.  -  HrSetObjAccess
  309.  -
  310.  *  Sets access rights for the object itself.  By default, the object has
  311.  *  read/write access.
  312.  *
  313.  */
  314.  
  315. #ifndef NOIDLEENGINE
  316.  
  317. /* Idle time scheduler */
  318.  
  319. /*
  320.  *  PRI
  321.  *
  322.  *  Priority of an idle task.
  323.  *  The idle engine sorts tasks by priority, and the one with the higher
  324.  *  value runs first. Within a priority level, the functions are called
  325.  *  round-robin.
  326.  */
  327.  
  328. #define PRILOWEST   -32768
  329. #define PRIHIGHEST  32767
  330. #define PRIUSER     0
  331.  
  332. /*
  333.  *  IRO
  334.  *
  335.  *  Idle routine options.  This is a combined bit mask consisting of
  336.  *  individual firo's.  Listed below are the possible bit flags.
  337.  *
  338.  *      FIROWAIT and FIROINTERVAL are mutually exclusive.
  339.  *      If neither of the flags are specified, the default action
  340.  *      is to ignore the time parameter of the idle function and
  341.  *      call it as often as possible if firoPerBlock is not set;
  342.  *      otherwise call it one time only during the idle block
  343.  *      once the time constraint has been set. FIROINTERVAL
  344.  *      is also incompatible with FIROPERBLOCK.
  345.  *
  346.  *      FIROWAIT        - time given is minimum idle time before calling
  347.  *                        for the first time in the block of idle time,
  348.  *                        afterwhich call as often as possible.
  349.  *      FIROINTERVAL    - time given is minimum interval between each
  350.  *                        successive call
  351.  *      FIROPERBLOCK    - called only once per contiguous block of idle
  352.  *                        time
  353.  *      FIRODISABLED    - initially disabled when registered, the
  354.  *                        default is to enable the function when registered.
  355.  *      FIROONCEONLY    - called only one time by the scheduler and then
  356.  *                        deregistered automatically.
  357.  */
  358.  
  359. #define IRONULL         ((USHORT) 0x0000)
  360. #define FIROWAIT        ((USHORT) 0x0001)
  361. #define FIROINTERVAL    ((USHORT) 0x0002)
  362. #define FIROPERBLOCK    ((USHORT) 0x0004)
  363. #define FIRODISABLED    ((USHORT) 0x0020)
  364. #define FIROONCEONLY    ((USHORT) 0x0040)
  365.  
  366. /*
  367.  *  IRC
  368.  *
  369.  *  Idle routine change options. This is a combined bit mask consisting
  370.  *  of individual firc's; each one identifies an aspect of the idle task
  371.  *  that can be changed.
  372.  *
  373.  */
  374.  
  375. #define IRCNULL         ((USHORT) 0x0000)
  376. #define FIRCPFN         ((USHORT) 0x0001)   /* change function pointer */
  377. #define FIRCPV          ((USHORT) 0x0002)   /* change parameter block  */
  378. #define FIRCPRI         ((USHORT) 0x0004)   /* change priority         */
  379. #define FIRCCSEC        ((USHORT) 0x0008)   /* change time             */
  380. #define FIRCIRO         ((USHORT) 0x0010)   /* change routine options  */
  381.  
  382. /*
  383.  *  Type definition for idle functions.  An idle function takes one
  384.  *  parameter, an PV, and returns a BOOL value.
  385.  */
  386.  
  387. typedef BOOL (STDAPICALLTYPE FNIDLE) (LPVOID);
  388. typedef FNIDLE FAR *PFNIDLE;
  389.  
  390. /*
  391.  *  FTG
  392.  *
  393.  *  Function Tag.  Used to identify a registered idle function.
  394.  *
  395.  */
  396.  
  397. typedef void FAR *FTG;
  398. typedef FTG  FAR *PFTG;
  399. #define FTGNULL         ((FTG) NULL)
  400.  
  401. /*
  402.  -  MAPIInitIdle/MAPIDeinitIdle
  403.  -
  404.  *  Purpose:
  405.  *      Initialises the idle engine
  406.  *      If the initialisation succeded, returns 0, else returns -1
  407.  *
  408.  *  Arguments:
  409.  *      lpvReserved     Reserved, must be NULL.
  410.  */
  411.  
  412. STDAPI_(LONG)
  413. MAPIInitIdle (LPVOID lpvReserved);
  414.  
  415. STDAPI_(VOID)
  416. MAPIDeinitIdle (VOID);
  417.  
  418.  
  419. /*
  420.  *  FtgRegisterIdleRoutine
  421.  *
  422.  *      Registers the function pfn of type PFNIDLE, i.e., (BOOL (*)(LPVOID))
  423.  *      as an idle function.
  424.  *
  425.  *      The idle function will be called with the parameter pv by the
  426.  *      idle engine. The function has initial priority priIdle,
  427.  *      associated time csecIdle, and options iroIdle.
  428.  */
  429.  
  430. STDAPI_(FTG)
  431. FtgRegisterIdleRoutine (PFNIDLE lpfnIdle, LPVOID lpvIdleParam,
  432.     short priIdle, ULONG csecIdle, USHORT iroIdle);
  433.  
  434. /*
  435.  *  DeregisterIdleRoutine
  436.  *
  437.  *      Removes the given routine from the list of idle routines.
  438.  *      The routine will not be called again.  It is the responsibility
  439.  *      of the caller to clean up any data structures pointed to by the
  440.  *      pvIdleParam parameter; this routine does not free the block.
  441.  */
  442.  
  443. STDAPI_(void)
  444. DeregisterIdleRoutine (FTG ftg);
  445.  
  446. /*
  447.  *  EnableIdleRoutine
  448.  *
  449.  *      Enables or disables an idle routine.
  450.  */
  451.  
  452. STDAPI_(void)
  453. EnableIdleRoutine (FTG ftg, BOOL fEnable);
  454.  
  455. /*
  456.  *  ChangeIdleRoutine
  457.  *
  458.  *      Changes some or all of the characteristics of the given idle
  459.  *      function. The changes to make are indicated with flags in the
  460.  *      ircIdle parameter.
  461.  */
  462.  
  463. STDAPI_(void)
  464. ChangeIdleRoutine (FTG ftg, PFNIDLE lpfnIdle, LPVOID lpvIdleParam,
  465.     short priIdle, ULONG csecIdle, USHORT iroIdle, USHORT ircIdle);
  466.  
  467.  
  468. #endif  /* ! NOIDLEENGINE */
  469.  
  470.  
  471. /* IMalloc Utilities */
  472.  
  473. STDAPI_(LPMALLOC) MAPIGetDefaultMalloc(VOID);
  474.  
  475.  
  476. /* StreamOnFile (SOF) */
  477.  
  478. /*
  479.  *  Methods and #define's for implementing an OLE 2.0 storage stream
  480.  *  (as defined in the OLE 2.0 specs) on top of a system file.
  481.  */
  482.  
  483. #define SOF_UNIQUEFILENAME  ((ULONG) 0x80000000)
  484.  
  485. STDMETHODIMP OpenStreamOnFile(
  486.     LPALLOCATEBUFFER    lpAllocateBuffer,
  487.     LPFREEBUFFER        lpFreeBuffer,
  488.     ULONG               ulFlags,
  489.     LPTSTR              lpszFileName,
  490.     LPTSTR              lpszPrefix,
  491.     LPSTREAM FAR *      lppStream);
  492.  
  493. typedef HRESULT (STDMETHODCALLTYPE FAR * LPOPENSTREAMONFILE) (
  494.     LPALLOCATEBUFFER    lpAllocateBuffer,
  495.     LPFREEBUFFER        lpFreeBuffer,
  496.     ULONG               ulFlags,
  497.     LPTSTR              lpszFileName,
  498.     LPTSTR              lpszPrefix,
  499.     LPSTREAM FAR *      lppStream);
  500.  
  501. #ifdef  _WIN32
  502. #define OPENSTREAMONFILE "OpenStreamOnFile"
  503. #endif
  504. #ifdef  WIN16
  505. #define OPENSTREAMONFILE "_OPENSTREAMONFILE"
  506. #endif
  507.  
  508.  
  509. /* Property interface utilities */
  510.  
  511. /*
  512.  *  Copies a single SPropValue from Src to Dest.  Handles all the various
  513.  *  types of properties and will link its allocations given the master
  514.  *  allocation object and an allocate more function.
  515.  */
  516. STDAPI_(SCODE)
  517. PropCopyMore( LPSPropValue      lpSPropValueDest,
  518.               LPSPropValue      lpSPropValueSrc,
  519.               ALLOCATEMORE *    lpfAllocMore,
  520.               LPVOID            lpvObject );
  521.  
  522. /*
  523.  *  Returns the size in bytes of structure at lpSPropValue, including the
  524.  *  Value.
  525.  */
  526. STDAPI_(ULONG)
  527. UlPropSize( LPSPropValue    lpSPropValue );
  528.  
  529.  
  530. STDAPI_(BOOL)
  531. FEqualNames( LPMAPINAMEID lpName1, LPMAPINAMEID lpName2 );
  532.  
  533. #if defined(_WIN32) && !defined(_WINNT) && !defined(_WIN95) && !defined(_MAC)
  534. #define _WINNT
  535. #endif
  536.  
  537. STDAPI_(void)
  538. GetInstance(LPSPropValue lpPropMv, LPSPropValue lpPropSv, ULONG uliInst);
  539.  
  540. extern char rgchCsds[];
  541. extern char rgchCids[];
  542. extern char rgchCsdi[];
  543. extern char rgchCidi[];
  544.  
  545. STDAPI_(BOOL)
  546. FPropContainsProp( LPSPropValue lpSPropValueDst,
  547.                    LPSPropValue lpSPropValueSrc,
  548.                    ULONG        ulFuzzyLevel );
  549.  
  550. STDAPI_(BOOL)
  551. FPropCompareProp( LPSPropValue  lpSPropValue1,
  552.                   ULONG         ulRelOp,
  553.                   LPSPropValue  lpSPropValue2 );
  554.  
  555. STDAPI_(LONG)
  556. LPropCompareProp( LPSPropValue  lpSPropValueA,
  557.                   LPSPropValue  lpSPropValueB );
  558.  
  559. STDAPI_(HRESULT)
  560. HrAddColumns(   LPMAPITABLE         lptbl,
  561.                 LPSPropTagArray     lpproptagColumnsNew,
  562.                 LPALLOCATEBUFFER    lpAllocateBuffer,
  563.                 LPFREEBUFFER        lpFreeBuffer);
  564.  
  565. STDAPI_(HRESULT)
  566. HrAddColumnsEx( LPMAPITABLE         lptbl,
  567.                 LPSPropTagArray     lpproptagColumnsNew,
  568.                 LPALLOCATEBUFFER    lpAllocateBuffer,
  569.                 LPFREEBUFFER        lpFreeBuffer,
  570.                 void                (FAR *lpfnFilterColumns)(LPSPropTagArray ptaga));
  571.  
  572.  
  573. /* Notification utilities */
  574.  
  575. /*
  576.  *  Function that creates an advise sink object given a notification
  577.  *  callback function and context.
  578.  */
  579.  
  580. STDAPI
  581. HrAllocAdviseSink( LPNOTIFCALLBACK lpfnCallback,
  582.                    LPVOID lpvContext,
  583.                    LPMAPIADVISESINK FAR *lppAdviseSink );
  584.  
  585.  
  586. /*
  587.  *  Wraps an existing advise sink with another one which guarantees
  588.  *  that the original advise sink will be called in the thread on
  589.  *  which it was created.
  590.  */
  591.  
  592. STDAPI
  593. HrThisThreadAdviseSink( LPMAPIADVISESINK lpAdviseSink,
  594.                         LPMAPIADVISESINK FAR *lppAdviseSink);
  595.  
  596.  
  597.  
  598. /*
  599.  *  Allows a client and/or provider to force notifications
  600.  *  which are currently queued in the MAPI notification engine
  601.  *  to be dispatched without doing a message dispatch.
  602.  */
  603.  
  604. STDAPI HrDispatchNotifications (ULONG ulFlags);
  605.  
  606.  
  607. /* Service Provider Utilities */
  608.  
  609. /*
  610.  *  Structures and utility function for building a display table
  611.  *  from resources.
  612.  */
  613.  
  614. typedef struct {
  615.     ULONG           ulCtlType;          /* DTCT_LABEL, etc. */
  616.     ULONG           ulCtlFlags;         /* DT_REQUIRED, etc. */
  617.     LPBYTE          lpbNotif;           /*  pointer to notification data */
  618.     ULONG           cbNotif;            /* count of bytes of notification data */
  619.     LPTSTR          lpszFilter;         /* character filter for edit/combobox */
  620.     ULONG           ulItemID;           /* to validate parallel dlg template entry */
  621.     union {                             /* ulCtlType discriminates */
  622.         LPVOID          lpv;            /* Initialize this to avoid warnings */
  623.         LPDTBLLABEL     lplabel;
  624.         LPDTBLEDIT      lpedit;
  625.         LPDTBLLBX       lplbx;
  626.         LPDTBLCOMBOBOX  lpcombobox;
  627.         LPDTBLDDLBX     lpddlbx;
  628.         LPDTBLCHECKBOX  lpcheckbox;
  629.         LPDTBLGROUPBOX  lpgroupbox;
  630.         LPDTBLBUTTON    lpbutton;
  631.         LPDTBLRADIOBUTTON lpradiobutton;
  632.         LPDTBLMVLISTBOX lpmvlbx;
  633.         LPDTBLMVDDLBX   lpmvddlbx;
  634.         LPDTBLPAGE      lppage;
  635.     } ctl;
  636. } DTCTL, FAR *LPDTCTL;
  637.  
  638. typedef struct {
  639.     ULONG           cctl;
  640.     LPTSTR          lpszResourceName;   /* as usual, may be an integer ID */
  641.     union {                             /* as usual, may be an integer ID */
  642.         LPTSTR          lpszComponent;
  643.         ULONG           ulItemID;
  644.     };
  645.     LPDTCTL         lpctl;
  646. } DTPAGE, FAR *LPDTPAGE;
  647.  
  648.  
  649.  
  650. STDAPI
  651. BuildDisplayTable(  LPALLOCATEBUFFER    lpAllocateBuffer,
  652.                     LPALLOCATEMORE      lpAllocateMore,
  653.                     LPFREEBUFFER        lpFreeBuffer,
  654.                     LPMALLOC            lpMalloc,
  655.                     HINSTANCE           hInstance,
  656.                     UINT                cPages,
  657.                     LPDTPAGE            lpPage,
  658.                     ULONG               ulFlags,
  659.                     LPMAPITABLE *       lppTable,
  660.                     LPTABLEDATA *       lppTblData );
  661.  
  662.  
  663. /* MAPI structure validation/copy utilities */
  664.  
  665. /*
  666.  *  Validate, copy, and adjust pointers in MAPI structures:
  667.  *      notification
  668.  *      property value array
  669.  *      option data
  670.  */
  671.  
  672. STDAPI_(SCODE)
  673. ScCountNotifications(int cNotifications, LPNOTIFICATION lpNotifications,
  674.         ULONG FAR *lpcb);
  675.  
  676. STDAPI_(SCODE)
  677. ScCopyNotifications(int cNotification, LPNOTIFICATION lpNotifications,
  678.         LPVOID lpvDst, ULONG FAR *lpcb);
  679.  
  680. STDAPI_(SCODE)
  681. ScRelocNotifications(int cNotification, LPNOTIFICATION lpNotifications,
  682.         LPVOID lpvBaseOld, LPVOID lpvBaseNew, ULONG FAR *lpcb);
  683.  
  684.  
  685. STDAPI_(SCODE)
  686. ScCountProps(int cValues, LPSPropValue lpPropArray, ULONG FAR *lpcb);
  687.  
  688. STDAPI_(LPSPropValue)
  689. LpValFindProp(ULONG ulPropTag, ULONG cValues, LPSPropValue lpPropArray);
  690.  
  691. STDAPI_(SCODE)
  692. ScCopyProps(int cValues, LPSPropValue lpPropArray, LPVOID lpvDst,
  693.         ULONG FAR *lpcb);
  694.  
  695. STDAPI_(SCODE)
  696. ScRelocProps(int cValues, LPSPropValue lpPropArray,
  697.         LPVOID lpvBaseOld, LPVOID lpvBaseNew, ULONG FAR *lpcb);
  698.  
  699. STDAPI_(SCODE)
  700. ScDupPropset(int cValues, LPSPropValue lpPropArray,
  701.         LPALLOCATEBUFFER lpAllocateBuffer, LPSPropValue FAR *lppPropArray);
  702.  
  703.  
  704. /* General utility functions */
  705.  
  706. /* Related to the OLE Component object model */
  707.  
  708. STDAPI_(ULONG)          UlAddRef(LPVOID lpunk);
  709. STDAPI_(ULONG)          UlRelease(LPVOID lpunk);
  710.  
  711. /* Related to the MAPI interface */
  712.  
  713. STDAPI                  HrGetOneProp(LPMAPIPROP lpMapiProp, ULONG ulPropTag,
  714.                         LPSPropValue FAR *lppProp);
  715. STDAPI                  HrSetOneProp(LPMAPIPROP lpMapiProp,
  716.                         LPSPropValue lpProp);
  717. STDAPI_(BOOL)           FPropExists(LPMAPIPROP lpMapiProp, ULONG ulPropTag);
  718. STDAPI_(LPSPropValue)   PpropFindProp(LPSPropValue lpPropArray, ULONG cValues,
  719.                         ULONG ulPropTag);
  720. STDAPI_(void)           FreePadrlist(LPADRLIST lpAdrlist);
  721. STDAPI_(void)           FreeProws(LPSRowSet lpRows);
  722. STDAPI                  HrQueryAllRows(LPMAPITABLE lpTable, 
  723.                         LPSPropTagArray lpPropTags,
  724.                         LPSRestriction lpRestriction,
  725.                         LPSSortOrderSet lpSortOrderSet,
  726.                         LONG crowsMax,
  727.                         LPSRowSet FAR *lppRows);
  728.  
  729. /* Create or validate the IPM folder tree in a message store */
  730.  
  731. #define MAPI_FORCE_CREATE   1
  732. #define MAPI_FULL_IPM_TREE  2
  733.  
  734. STDAPI                  HrValidateIPMSubtree(LPMDB lpMDB, ULONG ulFlags,
  735.                         ULONG FAR *lpcValues, LPSPropValue FAR *lppValues,
  736.                         LPMAPIERROR FAR *lpperr);
  737.  
  738. /* Encoding and decoding strings */
  739.  
  740. STDAPI_(BOOL)           FBinFromHex(LPTSTR lpsz, LPBYTE lpb);
  741. STDAPI_(SCODE)          ScBinFromHexBounded(LPTSTR lpsz, LPBYTE lpb, ULONG cb);
  742. STDAPI_(void)           HexFromBin(LPBYTE lpb, int cb, LPTSTR lpsz);
  743. STDAPI_(ULONG)          UlFromSzHex(LPCTSTR lpsz);
  744.  
  745. /* Encoding and decoding entry IDs */
  746. STDAPI                  HrEntryIDFromSz(LPTSTR lpsz, ULONG FAR *lpcb,
  747.                         LPENTRYID FAR *lppEntryID);
  748. STDAPI                  HrSzFromEntryID(ULONG cb, LPENTRYID lpEntryID,
  749.                         LPTSTR FAR *lpsz);
  750. STDAPI                  HrComposeEID(LPMAPISESSION lpSession,
  751.                         ULONG cbStoreRecordKey, LPBYTE lpStoreRecordKey,
  752.                         ULONG cbMsgEntryID, LPENTRYID lpMsgEntryID,
  753.                         ULONG FAR *lpcbEID, LPENTRYID FAR *lppEntryID);
  754. STDAPI                  HrDecomposeEID(LPMAPISESSION lpSession,
  755.                         ULONG cbEntryID, LPENTRYID lpEntryID,
  756.                         ULONG FAR *lpcbStoreEntryID,
  757.                         LPENTRYID FAR *lppStoreEntryID,
  758.                         ULONG FAR *lpcbMsgEntryID,
  759.                         LPENTRYID FAR *lppMsgEntryID);
  760. STDAPI                  HrComposeMsgID(LPMAPISESSION lpSession,
  761.                         ULONG cbStoreSearchKey, LPBYTE pStoreSearchKey,
  762.                         ULONG cbMsgEntryID, LPENTRYID lpMsgEntryID,
  763.                         LPTSTR FAR *lpszMsgID);
  764. STDAPI                  HrDecomposeMsgID(LPMAPISESSION lpSession,
  765.                         LPTSTR lpszMsgID,
  766.                         ULONG FAR *lpcbStoreEntryID,
  767.                         LPENTRYID FAR *lppStoreEntryID,
  768.                         ULONG FAR *lppcbMsgEntryID,
  769.                         LPENTRYID FAR *lppMsgEntryID);
  770.  
  771. /* C runtime substitutes */
  772.  
  773.  
  774. STDAPI_(LPTSTR)         SzFindCh(LPCTSTR lpsz, USHORT ch);      /* strchr */
  775. STDAPI_(LPTSTR)         SzFindLastCh(LPCTSTR lpsz, USHORT ch);  /* strrchr */
  776. STDAPI_(LPTSTR)         SzFindSz(LPCTSTR lpsz, LPCTSTR lpszKey); /*strstr */
  777. STDAPI_(unsigned int)   UFromSz(LPCTSTR lpsz);                  /* atoi */
  778.  
  779. STDAPI_(SCODE)          ScUNCFromLocalPath(LPSTR lpszLocal, LPSTR lpszUNC,
  780.                         UINT cchUNC);
  781. STDAPI_(SCODE)          ScLocalPathFromUNC(LPSTR lpszUNC, LPSTR lpszLocal,
  782.                         UINT cchLocal);
  783.  
  784. /* 64-bit arithmetic with times */
  785.  
  786. STDAPI_(FILETIME)       FtAddFt(FILETIME ftAddend1, FILETIME ftAddend2);
  787. STDAPI_(FILETIME)       FtMulDwDw(DWORD ftMultiplicand, DWORD ftMultiplier);
  788. STDAPI_(FILETIME)       FtMulDw(DWORD ftMultiplier, FILETIME ftMultiplicand);
  789. STDAPI_(FILETIME)       FtSubFt(FILETIME ftMinuend, FILETIME ftSubtrahend);
  790. STDAPI_(FILETIME)       FtNegFt(FILETIME ft);
  791.  
  792. /* Message composition */
  793.  
  794. STDAPI_(SCODE)          ScCreateConversationIndex (ULONG cbParent,
  795.                             LPBYTE lpbParent,
  796.                             ULONG FAR * lpcbConvIndex,
  797.                             LPBYTE FAR * lppbConvIndex);
  798.  
  799. /* Store support */
  800.  
  801. STDAPI WrapStoreEntryID (ULONG ulFlags, LPTSTR lpszDLLName, ULONG cbOrigEntry,
  802.     LPENTRYID lpOrigEntry, ULONG *lpcbWrappedEntry, LPENTRYID *lppWrappedEntry);
  803.  
  804. /* RTF Sync Utilities */
  805.  
  806. #define RTF_SYNC_RTF_CHANGED    ((ULONG) 0x00000001)
  807. #define RTF_SYNC_BODY_CHANGED   ((ULONG) 0x00000002)
  808.  
  809. STDAPI_(HRESULT)
  810. RTFSync (LPMESSAGE lpMessage, ULONG ulFlags, BOOL FAR * lpfMessageUpdated);
  811.  
  812.  
  813. /* Flags for WrapCompressedRTFStream() */
  814.  
  815. /****** MAPI_MODIFY             ((ULONG) 0x00000001) mapidefs.h */
  816. /****** STORE_UNCOMPRESSED_RTF  ((ULONG) 0x00008000) mapidefs.h */
  817.  
  818. STDAPI_(HRESULT)
  819. WrapCompressedRTFStream (LPSTREAM lpCompressedRTFStream,
  820.         ULONG ulFlags, LPSTREAM FAR * lpUncompressedRTFStream);
  821.  
  822. /* Storage on Stream */
  823.  
  824. #if defined(_WIN32) || defined(WIN16)
  825. STDAPI_(HRESULT)
  826. HrIStorageFromStream (LPUNKNOWN lpUnkIn,
  827.     LPCIID lpInterface, ULONG ulFlags, LPSTORAGE FAR * lppStorageOut);
  828. #endif
  829.  
  830.  
  831. /*
  832.  * Setup and cleanup. 
  833.  *
  834.  * Providers never need to make these calls.
  835.  *
  836.  * Test applications and the like which do not call MAPIInitialize
  837.  * may want to call them, so that the few utility functions which
  838.  * need MAPI allocators (and do not ask for them explicitly)
  839.  * will work.
  840.  */
  841.  
  842. /* All flags are reserved for ScInitMapiUtil. */
  843.  
  844. STDAPI_(SCODE)          ScInitMapiUtil(ULONG ulFlags);
  845. STDAPI_(VOID)           DeinitMapiUtil(VOID);
  846.  
  847.  
  848. /*
  849.  *  Entry point names.
  850.  *  
  851.  *  These are for new entry points defined since MAPI first shipped
  852.  *  in Windows 95. Using these names in a GetProcAddress call makes
  853.  *  it easier to write code which uses them optionally.
  854.  */
  855.  
  856. #if defined (WIN16)
  857. #define szHrDispatchNotifications "HrDispatchNotifications"
  858. #elif defined (_WIN32) && defined (_X86_)
  859. #define szHrDispatchNotifications "_HrDispatchNotifications@4"
  860. #elif defined (_ALPHA_) || defined (_MIPS_) || defined (_PPC_)
  861. #define szHrDispatchNotifications "HrDispatchNotifications"
  862. #endif
  863.  
  864. typedef HRESULT (STDAPICALLTYPE DISPATCHNOTIFICATIONS)(ULONG ulFlags);
  865. typedef DISPATCHNOTIFICATIONS FAR * LPDISPATCHNOTIFICATIONS;
  866.  
  867. #if defined (WIN16)
  868. #define szScCreateConversationIndex "ScCreateConversationIndex"
  869. #elif defined (_WIN32) && defined (_X86_)
  870. #define szScCreateConversationIndex "_ScCreateConversationIndex@16"
  871. #elif defined (_ALPHA_) || defined (_MIPS_) || defined (_PPC_)
  872. #define szScCreateConversationIndex "ScCreateConversationIndex"
  873. #endif
  874.  
  875. typedef SCODE (STDAPICALLTYPE CREATECONVERSATIONINDEX)(ULONG cbParent,
  876.     LPBYTE lpbParent, ULONG FAR *lpcbConvIndex, LPBYTE FAR *lppbConvIndex);
  877. typedef CREATECONVERSATIONINDEX FAR *LPCREATECONVERSATIONINDEX;
  878.  
  879. #ifdef __cplusplus
  880. }
  881. #endif
  882.  
  883. #pragma option pop /*P_O_Pop*/
  884. #endif /* _MAPIUTIL_H_ */
  885.