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