home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / msgemit.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  18KB  |  438 lines
  1. // --msgemit.h--------------------------------------------------------------
  2. //
  3. // API entry points for the msgemit static link library.
  4. // Contains helper functions for converting MAPI messages to 
  5. // 822-style headers and 822-style ASCII headers to MAPI messages.
  6. //
  7. // Copyright (C) Microsoft Corp., 1986-1996.  All rights reserved.
  8. //
  9. // ---------------------------------------------------------------------------
  10.  
  11. #ifndef _MSGEMIT_H
  12. #define _MSGEMIT_H
  13.  
  14. #ifdef __cplusplus
  15. extern "C" {
  16. #endif // __cplusplus
  17.  
  18. // Constants for the binary encode and decode functions.
  19. const ULONG nBytesEncodePerLine     =   24; // # of bytes encoded per line
  20. const ULONG nCharsPerEncodedByte    =   3;  // # of chars written per encoded byte
  21.  
  22. // Convenient macro for determining the number of data bytes (not
  23. // counting the null terminator) in a string.
  24. static __inline ULONG cbStrBytes(
  25.     IN LPCSTR pszString)     // string pointer
  26. {
  27.     return (lstrlenA(pszString));
  28. }
  29.  
  30. //$--HrCreateDateTimeString@-------------------------------------------------
  31. //
  32. // DESCRIPTION: Builds a date & time (UT) created string for a MAPI message file time
  33. //
  34. // INPUT:       lpFileTime  --  file time structure pointer (UT)
  35. //
  36. // OUTPUT:      lppTimeString   --  Pointer to time string output buffer
  37. //
  38. // RETURNS:     HRESULT     --  NOERROR if successful,
  39. //                              E_INVALIDARG if bad input,
  40. //                              E_OUTOFMEMORY if memory problems,
  41. //                              E_FAIL otherwise
  42. //
  43. // ---------------------------------------------------------------------------
  44.  
  45. HRESULT HrCreateDateTimeStringW(
  46.     IN LPFILETIME lpFileTime,      // file time structure pointer
  47.     OUT LPWSTR * lppTimeString);   // pointer to time string buffer
  48.  
  49. HRESULT HrCreateDateTimeStringA(
  50.     IN LPFILETIME lpFileTime,      // file time structure pointer
  51.     OUT LPSTR * lppTimeString);    // pointer to time string buffer
  52.  
  53. #ifdef UNICODE
  54. #define HrCreateDateTimeString  HrCreateDateTimeStringW
  55. #else
  56. #define HrCreateDateTimeString  HrCreateDateTimeStringA
  57. #endif
  58.  
  59. //$--HrCreateImportanceString------------------------------------------------
  60. //
  61. // DESCRIPTION: Creates an message importance string from a MAPI message importance value
  62. //
  63. // INPUT:       ulImportance    --  message's PR_IMPORTANCE value
  64. //              
  65. // OUTPUT:      lppImportance --  Pointer to importance string buffer
  66. //
  67. // RETURNS:     HRESULT     --  NOERROR if successful,
  68. //                              E_INVALIDARG if invalid parameter,
  69. //                              E_OUTOFMEMORY if memory problems,
  70. //                              E_FAIL otherwise.
  71. //
  72. // ---------------------------------------------------------------------------
  73.  
  74. HRESULT HrCreateImportanceString(                   //  RETURNS:    HRESULT
  75.                     IN ULONG ulImportance,            // message's PR_IMPORTANCE value
  76.                     OUT LPSTR * lppImportance);  // pointer to importance string buffer
  77.  
  78. //$--HrEmitTagDataLine-------------------------------------------------------
  79. //
  80. // DESCRIPTION: Emits a line constructed from a static tag and dynamic
  81. //              data to the specified stream.
  82. //
  83. // INPUT:       lpszTag --  tag portion of line
  84. //              lpData      --  data portion of line    (may be "")
  85. //              lpStream    --  stream to write line to
  86. //
  87. // RETURNS:     HRESULT     --  NOERROR if successful,
  88. //                              E_INVALIDARG if invalid parameter,d
  89. //                              E_FAIL otherwise
  90. //
  91. // ---------------------------------------------------------------------------
  92.  
  93. HRESULT HrEmitTagDataLine(   
  94.         IN LPCSTR lpszTag,      // static portion of line
  95.         IN LPSTR lpData,        // dynamic portion of line
  96.         IN LPSTREAM lpStream);  // stream to write line to
  97.  
  98. //$--HrCreatePriorityString-------------------------------------------------------
  99. //
  100. // DESCRIPTION: Creates message priority data string from a MAPI priority value
  101. //
  102. // INPUT:       ulPriority  --  message's PR_PRIORITY value
  103. //
  104. // OUTPUT:      lppPriorityString --  message priority data string pointer
  105. //
  106. // RETURNS:     HRESULT     --  NOERROR if successful,
  107. //                              E_INVALIDARG if invalid parameter,
  108. //                              E_OUTOFMEMORY if memory problems
  109. //                              E_FAIL otherwise
  110. //
  111. // ---------------------------------------------------------------------------
  112.  
  113. HRESULT HrCreatePriorityString(   
  114.         IN ULONG ulPriority,            // message's PR_PRIORITY value
  115.         OUT LPSTR * lppPriorityString); // message priority data string pointer
  116.  
  117. //$--HrEDKEncodeBinaryStreamDataToStream-----------------------------------------------
  118. //
  119. // DESCRIPTION: Copies binary data from an input stream or
  120. //              specified output stream,
  121. //              encoding each byte as a two-character
  122. //              hexadecimal ASCII representation of the byte.
  123. //              E.g. 255 becomes 'FF'.
  124. //
  125. // INPUT:       
  126. //              lpStreamIn  --  input stream pointer
  127. //              lpStreamOut --  output stream pointer
  128. //
  129. // RETURNS:     HRESULT     --  NOERROR if successful,
  130. //                              E_INVALIDARG if invalid parameter,
  131. //                              E_FAIL otherwise
  132. //
  133. // ---------------------------------------------------------------------------
  134. HRESULT HrEDKEncodeBinaryStreamDataToStream(               
  135.                     IN LPSTREAM lpStreamIn,     // input stream pointer
  136.                     IN LPSTREAM lpStreamOut);   // output stream pointer
  137.  
  138. //$--HrCreateExternalTraceString------------------------------------------------
  139. //
  140. // DESCRIPTION: Creates a string from a message's external trace information.
  141. //
  142. // INPUT:       lAction --  trace action
  143. //              lpCountry   --  country
  144. //              lpADMDName  --  ADMD name
  145. //              lpPRMDId    --  PRMD identifier
  146. //          
  147. // OUTPUT:      lppTraceString  --  pointer to trace information string buffer
  148. //
  149. // RETURNS:     HRESULT     --  NOERROR if successful,
  150. //                              E_INVALIDARG if invalid parameter,
  151. //                              E_OUTOFMEMORY if memory problems
  152. //                              E_FAIL otherwise,
  153. //
  154. // -----------------------------------------------------------------------------
  155.  
  156. HRESULT HrCreateExternalTraceString(        
  157.     IN LONG lAction,             // trace action
  158.     IN LPSTR lpCountry,          // country name
  159.     IN LPSTR lpADMDName,         // ADMD name
  160.     IN LPSTR lpPRMDId,           // PRMD identifier    
  161.     OUT LPSTR * lppTraceString); // trace information string pointer
  162.  
  163. //$--HrCreateInternalTraceString------------------------------------------------
  164. //
  165. // DESCRIPTION: Creates a string from a message's internal trace information.
  166. //
  167. // INPUT:       lAction        --  trace action
  168. //              lpCountry   --  country
  169. //              lpADMDName  --  ADMD name
  170. //              lpPRMDId    --  PRMD identifier
  171. //                lpMTAName    --  MTA name
  172. //          
  173. // OUTPUT:      lppTraceString  --  pointer to trace information string buffer
  174. //
  175. // RETURNS:     HRESULT     --  NOERROR if successful,
  176. //                              E_INVALIDARG if invalid parameter,
  177. //                              E_OUTOFMEMORY if memory problems
  178. //                              E_FAIL otherwise,
  179. //
  180. // -----------------------------------------------------------------------------
  181.  
  182. HRESULT HrCreateInternalTraceString(        
  183.     IN LONG lAction,             // trace action
  184.     IN LPSTR lpCountry,          // country name
  185.     IN LPSTR lpADMDName,         // ADMD name
  186.     IN LPSTR lpPRMDId,           // PRMD identifier    
  187.     IN LPSTR lpMTAName,             // MTA name
  188.     OUT LPSTR * lppTraceString); // trace information string pointer
  189.  
  190. //$--HrGetRecipientList------------------------------------------
  191. //
  192. // DESCRIPTION: Utility function which retrieves columns 
  193. // desired from a MAPI recipient table.
  194. //
  195. // INPUT:   lpMessage   --  pointer to MAPI message
  196. //          lpPropTags  --  list of columns (properties) to retrieve
  197. //          
  198. // OUTPUT:  lppRows --  pointer to array of rows returned pointer.
  199. //
  200. // RETURNS: HRESULT --  NOERROR if successful,
  201. //                      E_INVALIDARG if bad input,
  202. //                      E_FAIL otherwise
  203. //
  204. // -------------------------------------------------------------
  205. HRESULT HrGetRecipientList(           
  206.         IN LPMESSAGE lpMessage,         // MAPI message pointer
  207.         IN LPSPropTagArray lpPropTags,  // properties (columns) desired
  208.         OUT LPSRowSet * lppRows);       // pointer to rows returned
  209.  
  210. //$--HrParseTagAndData-------------------------------------------------------
  211. //
  212. // DESCRIPTION: Parse ASCII 822-style header line into
  213. //              tag and data components.
  214. //
  215. // INPUT:       lpStream    --  stream pointer to read from
  216. //
  217. // OUTPUT:      pcbRead --  number of bytes read from stream
  218. //              ppTag   --  pointer to tag buffer
  219. //              ppData  --  pointer to data buffer
  220. //
  221. // RETURNS:     HRESULT --  NOERROR if successful,
  222. //                          E_INVALIDARG if bad input
  223. //                          E_OUTOFMEMORY if memory problem
  224. //                          E_EOF if end of stream
  225. //                          E_FAIL otherwise
  226. //
  227. // ---------------------------------------------------------------------------
  228. HRESULT HrParseTagAndData(
  229.         IN LPSTREAM lpStream,   // stream pointer
  230.         OUT ULONG * pcbRead,    // # of bytes read
  231.         OUT LPSTR * lppTag,     // pointer to tag buffer
  232.         OUT LPSTR * lppData);   // pointer to data buffer
  233.  
  234. //$--HrParseDateTimeString----------------------------------------------------
  235. //
  236. // DESCRIPTION: Parses a date and time string into a file time
  237. //              structure.
  238. //
  239. // INPUT:       lpDateTimeString    --  date and time string
  240. //
  241. // OUTPUT:      pFileTime   --  file time pointer
  242. //
  243. // RETURNS:     HRESULT --  NOERROR if successful,
  244. //                          E_INVALIDARG if bad input,
  245. //                          E_FAIL otherwise
  246. //
  247. // ----------------------------------------------------------------------------
  248. HRESULT HrParseDateTimeString(
  249.     IN LPSTR lpDateTimeString,      // date and time string
  250.     OUT FILETIME * pFileTime);      // file time pointer
  251.  
  252. //$--HrParsePriorityString----------------------------------------------------
  253. //
  254. // DESCRIPTION: Convert a priority string to its associated
  255. //              integer value.
  256. //
  257. // INPUT:       lpPriority  --  priority string
  258. //             
  259. // OUTPUT:      pulPriority --  pointer to priority value
  260. //
  261. // RETURNS:     HRESULT --  NOERROR if successful,
  262. //                          E_INVALIDARG if bad input,
  263. //                          E_FAIL otherwise
  264. //
  265. // ----------------------------------------------------------------------------
  266. HRESULT HrParsePriorityString(
  267.     IN LPSTR lpPriority,        // Priority string
  268.     OUT ULONG * pulPriority);   // priority value pointer
  269.  
  270. //$--HrParseImportanceString----------------------------------------------------
  271. //
  272. // DESCRIPTION: Convert an importance string to its associated
  273. //              integer value.
  274. //
  275. // INPUT:       lpImportance  --  importance string
  276. //             
  277. // OUTPUT:      pulImportance --  pointer to importance value
  278. //
  279. // RETURNS:     HRESULT --  NOERROR if successful,
  280. //                          E_INVALIDARG if bad input,
  281. //                          E_FAIL otherwise
  282. //
  283. // ----------------------------------------------------------------------------
  284. HRESULT HrParseImportanceString(
  285.     IN LPSTR lpImportance,      // Importance string
  286.     OUT ULONG * pulImportance); // importance value pointer
  287.  
  288. //$--HrParseExternalTraceString-------------------------------------------------
  289. //
  290. // DESCRIPTION: Parse External-Received-By or 
  291. //              External-Attempted-By trace string into a
  292. //              its separate components.
  293. //
  294. // INPUT:       lpTraceString   --  External-Received/Attempted-By trace string
  295. //
  296. // OUTPUT:      plAction   --  trace action
  297. //              pCountry  --  country name
  298. //              pADMDName --  ADMD name
  299. //              pPRMDId   --  PRMD identifier
  300. //
  301. // RETURNS: HRESULT --  NOERROR if successful,
  302. //                      E_INVALIDARG if bad input
  303. //                      E_FAIL otherwise
  304. //
  305. // ----------------------------------------------------------------------------
  306. HRESULT HrParseExternalTraceString(
  307.     IN LPSTR lpTraceString,      // trace information string
  308.     OUT LONG * plAction,         // trace action pointer
  309.     OUT CHAR * pCountry,         // country name
  310.     OUT CHAR * pADMDName,        // ADMD name
  311.     OUT CHAR * pPRMDId);         // PRMD identifier
  312.  
  313. //$--HrParseInternalTraceString-------------------------------------------------
  314. //
  315. // DESCRIPTION: Parse Internal-Received-By or 
  316. //              Internal-Attempted-By trace string into 
  317. //              its separate components.
  318. //
  319. // INPUT:       lpTraceString   --  Internal-Received/Attempted-By trace string
  320. //
  321. // OUTPUT:      plAction  --  trace action
  322. //              pCountry  --  country name
  323. //              pADMDName --  ADMD name
  324. //              pPRMDId   --  PRMD identifier
  325. //              pMTAName  --  MTA name
  326. //
  327. // RETURNS: HRESULT --  NOERROR if successful,
  328. //                      E_INVALIDARG if bad input
  329. //                      E_FAIL otherwise
  330. //
  331. // -----------------------------------------------------------------------------
  332. HRESULT HrParseInternalTraceString(
  333.     IN LPSTR lpTraceString,      // trace information string
  334.     OUT LONG * plAction,         // trace action pointer
  335.     OUT CHAR * pCountry,         // country name
  336.     OUT CHAR * pADMDName,        // ADMD name
  337.     OUT CHAR * pPRMDId,          // PRMD identifier
  338.     OUT CHAR * pMTAName);        // MTA name
  339.  
  340. //$--HrParseAttachmentHeader--------------------------------------------------
  341. //
  342. // DESCRIPTION: Parse attachment header data into its file name
  343. //              and file size components.
  344. //
  345. // INPUT:   lpHeader    --  attachment header data string
  346. //
  347. // OUTPUT:  lppFileName --  attachment file name
  348. //          pcb         --  pointer to # of bytes in attachment
  349. //
  350. // RETURNS: HRESULT --  NOERROR if successful,
  351. //                      E_INVALIDARG if bad input,
  352. //                      E_FAIL otherwise.
  353. //
  354. // ----------------------------------------------------------------------------
  355. HRESULT HrParseAttachmentHeader(
  356.     IN LPSTR lpHeader,         // attachment header data string
  357.     OUT LPSTR * lppFileName,   // attachment file name
  358.     OUT ULONG * pcb);          // pointer to number of bytes in file name
  359.  
  360. //$--HrEDKDecodeBinaryStreamDataToStream-----------------------------------------------
  361. //
  362. // DESCRIPTION: Read attachment hexadecimal encoding from input
  363. //              stream to attachment.
  364. //
  365. // INPUT:       cb  --  number of bytes in binary attachment.
  366. //              lpStream    --  stream pointer
  367. //              lpAttach    --  attachment pointer
  368. //
  369. // RETURNS:     HRESULT --  NOERROR if successful,
  370. //                          E_INVALIDARG if bad input
  371. //                          E_FAIL otherwise.
  372. //
  373. // ----------------------------------------------------------------------------
  374.  
  375. HRESULT HrEDKDecodeBinaryStreamDataToStream(
  376.     IN LPSTREAM lpStreamIn,     // input stream
  377.     IN ULONG cb,                // number of bytes in original binary data
  378.     IN LPSTREAM lpStreamOut);   // output stream
  379.  
  380. //$--HrEDKParseSubjectPrefix---------------------------------------------------
  381. //
  382. // DESCRIPTION: Break a subject into its prefix component & its
  383. //              original subject component.  (The prefix is everything
  384. //              up to and including the first colon and the first space
  385. //              after the colon, if any.
  386. //
  387. // INPUT:       pszSubject --  subject text
  388. //
  389. // OUTPUT       ppszPrefix  --  prefix string pointer
  390. //              ppszOrigSub --  original subject pointer
  391. //
  392. // RETURNS:     HRESULT --  NOERROR if successful,
  393. //                          E_INVALIDARG if bad input,
  394. //                          E_OUTOFMEMORY if memory propblems,
  395. //                          E_FAIL otherwise.
  396. //
  397. // ----------------------------------------------------------------------------
  398. HRESULT HrEDKParseSubjectPrefix(
  399.             IN LPSTR pszSubject,       // subject text
  400.             OUT LPSTR * ppszPrefix,    // subject prefix
  401.             OUT LPSTR * ppszOrigSub);  // original subject text
  402.  
  403. //$--nEDKEncodedBytes-------------------------------------------------------------
  404. //
  405. // DESCRIPTION: Returns the number of encoded bytes based on the number of 
  406. //              un-encoded bytes.
  407. //
  408. // INPUT:       cbUnencoded --  # of un-encoded bytes
  409. //
  410. // RETURNS:     ULONG   --  # of encoded bytes
  411. //
  412. // NOTE:        This is implemented as a static __inline macro for 
  413. //              efficiency and because it is so simple.
  414. //
  415. //-----------------------------------------------------------------------------
  416. static __inline ULONG nEDKEncodedBytes(
  417.             IN ULONG cbUnencoded)   // # of un-encoded bytes
  418. {
  419.     ASSERTERROR(cbUnencoded != 0, "Bad cbUnencoded");   // debug check
  420.  
  421.     if ( (cbUnencoded % nBytesEncodePerLine) == 0 )
  422.     {
  423.         return ( (nCharsPerEncodedByte * cbUnencoded) + 
  424.                  (cbUnencoded/nBytesEncodePerLine) );
  425.     }
  426.     else
  427.     {
  428.         return ( (nCharsPerEncodedByte * cbUnencoded) + 
  429.                  (cbUnencoded/nBytesEncodePerLine) + 1 );
  430.     }
  431. }
  432.  
  433. #ifdef __cplusplus
  434. }
  435. #endif // __cplusplus
  436.  
  437. #endif
  438.