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