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