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