home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / rulecls.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-25  |  13.6 KB  |  445 lines
  1. // --rulecls.h-----------------------------------------------------------------
  2. //
  3. // Rule class interface header.
  4. //
  5. // Copyright (C) Microsoft Corp. 1986-1998. All rights reserved.
  6. //
  7. // ----------------------------------------------------------------------------
  8.  
  9. #if !defined(_RULECLS_H_)
  10. #define _RULECLS_H_
  11.  
  12. // $$--LPACTIONS---------------------------------------------------------------
  13. //
  14. // Pointer to ACTIONS structure defined in edkmdb.h.
  15. //
  16. // ----------------------------------------------------------------------------
  17.  
  18. typedef ACTIONS FAR *   LPACTIONS;  // should be moved to edkmdb.h
  19.  
  20. // $$--IExchangeFolderRules----------------------------------------------------
  21. //
  22. // Definition of interface for folder rules class CFolderRules.
  23. //
  24. // ----------------------------------------------------------------------------
  25.  
  26. #undef         INTERFACE
  27. #define         INTERFACE  IExchangeFolderRules
  28.  
  29. // Manifest for cursor position indicating we are at the end of the rules table.
  30.  
  31. #define    RULE_PAST_END        ((LONG) -1)
  32.  
  33. DECLARE_INTERFACE_(IExchangeFolderRules, IUnknown)
  34. {
  35. #ifndef NO_BASEINTERFACE_FUNCS
  36.  
  37.     /* IUnknown methods */
  38.  
  39.     STDMETHOD(QueryInterface)(
  40.         THIS_
  41.         REFIID                    riid,
  42.         LPVOID FAR *            ppvObj
  43.         )                                        PURE;
  44.  
  45.     STDMETHOD_(ULONG, AddRef)(
  46.         THIS
  47.         )                                        PURE;
  48.  
  49.     STDMETHOD_(ULONG, Release)(
  50.         THIS
  51.         )                                        PURE;
  52.  
  53. #endif
  54.  
  55.     /* IExchangeFolderRules methods */
  56.  
  57.     STDMETHOD(HrDelete)(
  58.         THIS
  59.         )                                                    PURE;
  60.  
  61.     STDMETHOD(HrDisable)(
  62.         THIS
  63.         )                                                    PURE;
  64.  
  65.     STDMETHOD(HrEnable)(
  66.         THIS
  67.         )                                                    PURE;
  68.  
  69.     STDMETHOD(HrGet)(
  70.         THIS_
  71.         LPLONG                    lplState,
  72.         LPSRestriction FAR *    lppRestriction,
  73.         LPACTIONS FAR *            lppActions,
  74.         LPLONG                    lplLevel,
  75.         LPSTR FAR *                lppszName
  76.         )                                                    PURE;
  77.  
  78.     STDMETHOD(HrInsert)(
  79.         THIS_
  80.         LONG                    lState,
  81.         LPSRestriction            lpRestriction,
  82.         LPACTIONS                lpActions,
  83.         LONG                    lLevel,
  84.         LPSTR                    lpszName
  85.         )                                                    PURE;
  86.  
  87.     STDMETHOD(HrSeek)(
  88.         THIS_
  89.         LONG                    lPos
  90.         )                                                    PURE;
  91.  
  92.     STDMETHOD(HrTell)(
  93.         THIS_
  94.         LPLONG                    lplPos
  95.         )                                                    PURE;
  96. };
  97.  
  98. // $$--LPFOLDERRULES-----------------------------------------------------------
  99. //
  100. // Pointer to IExchangeFolderRules interface.
  101. //
  102. // ----------------------------------------------------------------------------
  103.  
  104. typedef IExchangeFolderRules FAR* LPFOLDERRULES;
  105.  
  106. //
  107. // Helper functions defined in module RULECLS.
  108. //
  109.  
  110. // $--HrCopyActions------------------------------------------------------------
  111. //
  112. // DESCRIPTION:    Make a copy of an ACTIONS structure and all its subelements.
  113. //
  114. // INPUT:
  115. //
  116. //    [lpActsSrc]        -- Ptr to ACTIONS structure to be copied.
  117. //    [lpObject]        -- Ptr to an existing MAPI buffer allocated by 
  118. //                       MAPIAllocateBuffer(), or NULL if the returned structure
  119. //                       is to be allocated using MAPIAllocateBuffer().
  120. // OUTPUT:
  121. //
  122. //    [lppActsDest]    -- Ptr to be set to copy of ACTIONS structure.
  123. //
  124. // RETURNS:     HRESULT --  NOERROR            if successful;
  125. //                            E_INVALIDARG    if bad input;
  126. //                            E_OUTOFMEMORY    if insufficient memory;
  127. //                          E_FAIL            otherwise.
  128. //
  129. //-----------------------------------------------------------------------------
  130.  
  131. STDAPI
  132. HrCopyActions(                            // RETURNS: HRESULT
  133.     IN        LPACTIONS        lpActsSrc,  // source action ptr
  134.     IN        LPVOID            lpObject,    // ptr to existing MAPI buffer
  135.     OUT        LPACTIONS FAR *    lppActsDest // ptr to destination ACTIONS buffer
  136.     );
  137.  
  138.  
  139. // $--HrCopyRestriction--------------------------------------------------------
  140. //
  141. // DESCRIPTION:    Make a copy of an SRestriction structure and all its
  142. //                subelements.
  143. //
  144. // INPUT:
  145. //
  146. //    [lpResSrc]        -- Ptr to restriction to be copied.
  147. //    [lpObject]        -- Ptr to an existing MAPI buffer allocated by 
  148. //                       MAPIAllocateBuffer(), or NULL if the returned structure
  149. //                       is to be allocated using MAPIAllocateBuffer().
  150. //
  151. // OUTPUT:
  152. //
  153. //    [lppResDest]    -- Ptr to be set to copy of restriction.
  154. //
  155. // RETURNS:     NOERROR            if successful;
  156. //                E_INVALIDARG    if bad input;
  157. //                E_OUTOFMEMORY    if insufficient memory;
  158. //              E_FAIL            otherwise.
  159. //
  160. //-----------------------------------------------------------------------------
  161.  
  162. STDAPI
  163. HrCopyRestriction(                                // RETURNS: HRESULT
  164.     IN        LPSRestriction            lpResSrc,   // source restriction ptr
  165.     IN        LPVOID                    lpObject,    // ptr to existing MAPI buffer
  166.     OUT        LPSRestriction FAR *    lppResDest  // dest restriction buffer ptr
  167.     );
  168.  
  169.  
  170. // $--HrFolderRulesGetProviders------------------------------------------------
  171. //
  172. // DESCRIPTION:    Get an array of rules provider names for a given folder.
  173. //
  174. // INPUT:
  175. //
  176. //    [lpMDB]                -- Pointer to message store containing folder.
  177. //  [cbentryid]            -- Number of bytes in folder's entry identifier.
  178. //  [lpentryid]            -- Folder's entry identifier.
  179. //
  180. // OUTPUT:
  181. //
  182. //  [lpcProviders]        -- Pointer to ulong that will be set to count of
  183. //                           providers on successful return.
  184. //    [lpppszProviders]    -- Pointer to array of string pointers that will be set
  185. //                           to point at an array of provider name string pointers
  186. //                           on successful return.
  187. //
  188. // RETURNS:     NOERROR                if successful;
  189. //                E_INVALIDARG        if bad input;
  190. //                E_OUTOFMEMORY        if not enough memory;
  191. //                E_NOINTERFACE        if rules table does not exist on folder;
  192. //              E_FAIL                 otherwise.
  193. //
  194. //-----------------------------------------------------------------------------
  195.  
  196. STDAPI
  197. HrFolderRulesGetProviders(                        // RETURNS: HRESULT
  198.     IN        LPMDB                lpMDB,            // MAPI MDB store ptr
  199.     IN        ULONG                cbentryid,        // # bytes in entry ID
  200.     IN        LPENTRYID            lpentryid,        // entry ID ptr
  201.     OUT        LPULONG                lpcProviders,    // count of providers
  202.     OUT        LPSTR FAR * FAR *    lpppszProviders    // ptr to array of providers
  203.     );
  204.  
  205.  
  206. // $--HrFolderRulesOpen--------------------------------------------------------
  207. //
  208. // DESCRIPTION:    Get a pointer to an object which implements the
  209. //                IExchangeFolderRules interface defined in rulecls.h.
  210. //
  211. // INPUT:
  212. //
  213. //    [lpMDB]                -- Pointer to message store containing folder.
  214. //  [cbentryid]            -- Number of bytes in folder's entry identifier.
  215. //  [lpentryid]            -- Folder's entry identifier.
  216. //  [lpszProvider]        -- Provider for rules.  Multiple providers may have
  217. //                           rules on a folder. The IExchangeFolderRules interface
  218. //                           provides access to the rules associated with a
  219. //                           single specified provider.
  220. //
  221. // OUTPUT:
  222. //
  223. //  [lppFolderRules]    -- Pointer to object which supports interface.
  224. //
  225. // RETURNS:     NOERROR                if successful;
  226. //                E_INVALIDARG        if bad input;
  227. //                E_OUTOFMEMORY        if not enough memory;
  228. //                E_NOINTERFACE        if rules table does not exist on folder;
  229. //              E_FAIL                 otherwise.
  230. //
  231. //-----------------------------------------------------------------------------
  232.  
  233. STDAPI
  234. HrFolderRulesOpen(                                // RETURNS: HRESULT
  235.     IN        LPMDB                lpMDB,            // MAPI MDB store ptr
  236.     IN        ULONG                cbentryid,        // # bytes in entry ID
  237.     IN        LPENTRYID            lpentryid,        // entry ID ptr
  238.     IN        LPSTR                lpszProvider,    // provider name
  239.     OUT        LPFOLDERRULES FAR *    lppFolderRules  // ptr to folder rules buffer
  240.     );
  241.  
  242.  
  243. // $--HrActionToString---------------------------------------------------------
  244. //
  245. // DESCRIPTION:    Get a string representation of an ACTION.
  246. //
  247. // INPUT:
  248. //
  249. //  [lpSession]        -- MAPI session ptr.
  250. //    [lpAction]        -- Ptr to ACTION.
  251. //
  252. // OUTPUT:
  253. //
  254. //    [lppszString]    -- Ptr to ptr that will be set to point at generated
  255. //                       string representation on successful return.
  256. //
  257. // RETURNS:     NOERROR             if successful;
  258. //              E_INVALIDARG        if bad input;
  259. //              E_OUTOFMEMORY        if not enough memory;
  260. //              E_FAIL                otherwise.
  261. //
  262. //-----------------------------------------------------------------------------
  263.  
  264. STDAPI
  265. HrActionToString(                            // RETURNS: HRESULT
  266.     IN        LPMAPISESSION    lpSession,      // MAPI session ptr
  267.     IN        LPACTION        lpAction,        // action ptr
  268.     OUT        LPSTR FAR *        lppszString        // string ptr ptr
  269.     );
  270.  
  271.  
  272. // $--HrRestrictionToString----------------------------------------------------
  273. //
  274. // DESCRIPTION:    Get a string representation of an SRestriction.
  275. //
  276. // INPUT:
  277. //
  278. //    [lpRestriction]    -- Ptr to restriction.
  279. //
  280. // OUTPUT:
  281. //
  282. //    [lppszString]    -- Ptr to ptr that will be set to point at generated
  283. //                       string representation on successful return.
  284. //
  285. // RETURNS:     NOERROR             if successful;
  286. //              E_INVALIDARG        if bad input;
  287. //              E_OUTOFMEMORY        if not enough memory;
  288. //              E_FAIL                otherwise.
  289. //
  290. //-----------------------------------------------------------------------------
  291.  
  292. STDAPI
  293. HrRestrictionToString(                        // RETURNS: HRESULT
  294.     IN        LPSRestriction    lpRestriction,    // restriction ptr
  295.     OUT        LPSTR FAR *        lppszString        // string ptr ptr
  296.     );
  297.  
  298.  
  299. // $--HrStringToAction---------------------------------------------------------
  300. //
  301. // DESCRIPTION:    Generate an ACTION structure that describes the action
  302. //                provided in *lpszString.
  303. //
  304. // INPUT:
  305. //
  306. //    [lpSession]        -- Ptr to MAPI session.
  307. //    [lpFolder]        -- Ptr to MAPI folder action applies to.  MUST have been
  308. //                       opened with MAPI_MODIFY access.
  309. //    [lpszString]    -- Action string specifying ACTION to be generated.
  310. //    [lpObject]        -- Ptr to an existing MAPI buffer allocated by 
  311. //                       MAPIAllocateBuffer().  NULL is not permitted. Ideally,
  312. //                       this is a ptr to the parent ACTIONS structure.
  313. //
  314. // INPUT/OUTPUT:
  315. //
  316. //    [lpAction]        -- Ptr to ACTION structure that will be filled in.  This
  317. //                       is allocated by the caller.  Ideally, this is a ptr to
  318. //                       an ACTION array element that was allocated by the caller
  319. //                       using a MAPIAllocateMore() that referenced the parent
  320. //                       ACTIONS structure.
  321. //
  322. // RETURNS:     NOERROR                if successful;
  323. //                E_INVALIDARG        if bad input;
  324. //              E_OUTOFMEMORY        if out of memory;
  325. //              E_FAIL                otherwise.
  326. //-----------------------------------------------------------------------------
  327.  
  328. STDAPI
  329. HrStringToAction(                            // RETURNS: HRESULT
  330.     IN        LPMAPISESSION    lpSession,        // ptr to MAPI session
  331.     IN        LPMAPIFOLDER    lpFolder,        // ptr to MAPI folder
  332.     IN        LPSTR            lpszString,        // string ptr
  333.     IN        LPVOID            lpObject,        // ptr to existing MAPI buf
  334.     IN OUT    LPACTION        lpAction          // ACTION ptr
  335.     );
  336.  
  337.  
  338. // $--HrStringToRestriction----------------------------------------------------
  339. //
  340. // DESCRIPTION:    Generate an SRestriction structure that describes the 
  341. //                restriction condition provided in *lpszString.
  342. //
  343. // INPUT:
  344. //
  345. //    [lpszString]    -- Condition string specifying restriction to be generated.
  346. //    [lpObject]        -- Ptr to an existing MAPI buffer allocated by 
  347. //                       MAPIAllocateBuffer(), or NULL if the returned structure
  348. //                       is to be allocated using MAPIAllocateBuffer().
  349. //
  350. // OUTPUT:
  351. //
  352. //    [lppRestriction]    -- Ptr to ptr that will be set to point at generated
  353. //                           restriction on successful return.
  354. //
  355. // RETURNS:     NOERROR            if successful;
  356. //                E_INVALIDARG    if bad input;
  357. //              E_FAIL             otherwise.
  358. //
  359. // Conditional expression grammar used for HrStringToRestriction()
  360. // lpszString parameter:
  361. // 
  362. // Condition ::=    SimpleCondition                        |
  363. //                    Condition "|" Condition                |
  364. //                    Condition "&" Condition                |
  365. //                    "(" Condition ")"                    |
  366. //                    "!" Condition
  367. //
  368. // "|" is the logical OR operator.
  369. // "&" is the logical AND operator.
  370. // "!" is the logical NOT operator.
  371. //
  372. // Conditional expressions are evaluated from left to right with "|" and "&"
  373. // having equal precedence. "!" is a unary operator that applies to the operand
  374. // to its immediate right.
  375. //
  376. // SimpleCondition ::=    BooleanCondition                |
  377. //                        NumericCondition                |
  378. //                        StringCondition                    |
  379. //                        TimeCondition
  380. //
  381. // BooleanCondition ::=    BoolTag "=" BooleanLiteral
  382. //
  383. // NumericCondition ::=    NumericTag "=" NumericLiteral    |
  384. //                        NumericTag "#" NumericLiteral    |
  385. //                        NumericTag ">" NumericLiteral    |
  386. //                        NumericTag "<" NumericLiteral
  387. //
  388. // The meaning of the NumericCondition operators should be evident.
  389. //
  390. // StringCondition ::=    StringTag "=" StringLiteral        |
  391. //                        StringTag "#" StringLiteral        |
  392. //                        StringTag "}" StringLiteral
  393. //
  394. // "=" is the equality operator.
  395. // "#" is the inequality operator.
  396. // "}" is the contains operator (a "}" b means a contains b).
  397. //
  398. // TimeCondition ::=    TimeTag "=" TimeLiteral            |
  399. //                        TimeTag "#" TimeLiteral            |
  400. //                        TimeTag ">" TimeLiteral            |
  401. //                        TimeTag "<" TimeLiteral
  402. //
  403. // Note that time literals have a resolution of 1 second, so equality and 
  404. // inequality may not be the best conditional tests.
  405. //
  406. // BoolTag ::=        PT_xxx for a property with a boolean (PT_BOOLEAN) value    |
  407. //                    "[B" HexNumber "]"
  408. //
  409. // NumericTag ::=    PR_xxxx for a property with a numeric (PT_LONG) value    |
  410. //                    "[N" HexNumber "]"
  411. //
  412. // StringTag ::=    PR_xxxx for a property with a string
  413. //                  (PT_STRING8 or PT_UNICODE) value                        |
  414. //                    "[S" HexNumber "]"
  415. //
  416. // TimeTag ::=        PR_xxxx for a property with a time (PT_SYSTIME) value    |
  417. //                    "[T" HexNumber "]"
  418. //
  419. // BooleanLiteral ::=    "0"                    |
  420. //                        "1"
  421. //
  422. // NumericLiteral ::=    DecimalNumber
  423. //
  424. // StringLiteral ::=    String enclosed in quotes ("xxx").
  425. //
  426. // TimeLiteral ::=        HH:MM{:SS} YYYY-MM-DD (24 hour clock, local time)
  427. //
  428. // DecimalNumber ::=     DecimalDigit...        |
  429. //                        +DecimalDigit...    |
  430. //                        -DecimalDigit...
  431. //
  432. // HexNumber ::=        HexDigit...
  433. //
  434. //-----------------------------------------------------------------------------
  435.  
  436. STDAPI
  437. HrStringToRestriction(                                // RETURNS: HRESULT
  438.     IN        LPSTR                    lpszString,        // string
  439.     IN        LPVOID                    lpObject,        // ptr to existing MAPI buf
  440.     OUT        LPSRestriction FAR *    lppRestriction  // restriction buffer ptr
  441.     );
  442.  
  443.  
  444. #endif
  445.