home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / edkutils.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  21KB  |  390 lines
  1. // --edkutils.h-----------------------------------------------------------------
  2. //  EDK utility functions.
  3. //
  4. //  Copyright 1986 - 1998 Microsoft Corporation.  All Rights Reserved.
  5. // -----------------------------------------------------------------------------
  6.  
  7. #ifndef _EDKUTILS_H_
  8. #define _EDKUTILS_H_
  9.  
  10. #ifdef __cplusplus
  11. extern "C" {
  12. #endif // __cplusplus
  13.  
  14. #define EXCHANGE_DS     1
  15. #define EXCHANGE_IS     2
  16. #define EXCHANGE_MTA    3
  17. #define EXCHANGE_SA     4
  18.  
  19. //$--_HrWriteFile-------------------------------------------------------------
  20. //  Transfer contents from a given memory location & length to an open file.
  21. // -----------------------------------------------------------------------------
  22. HRESULT _HrWriteFile(                   // RETURNS: return code
  23.     IN HANDLE hFile,                    // file handle
  24.     IN ULONG cbmem,                     // count of bytes of memory
  25.     IN LPBYTE lpbmem);                  // pointer to memory
  26.  
  27. //$--HrCreateDirEntryId------------------------------------------------------
  28. //  Create a directory entry ID given the address of the object
  29. // -----------------------------------------------------------------------------
  30. HRESULT HrCreateDirEntryId(          // RETURNS: return code
  31.     IN LPSTR lpszAddress,               // pointer to address
  32.     OUT ULONG *lpcbeid,                 // count of bytes in entry ID
  33.     OUT LPENTRYID *lppeid);             // pointer to entry ID
  34.  
  35. //$--_HrMemoryToFile----------------------------------------------------------
  36. //  Transfer contents from a given memory location & length to a given file.
  37. // -----------------------------------------------------------------------------
  38. HRESULT _HrMemoryToFile(              // RETURNS: return code
  39.     IN ULONG cbmem,                     // count of bytes of memory
  40.     IN LPBYTE lpbmem,                   // pointer to memory
  41.     IN LPSTR lpszFilename);             // pointer to destination file name
  42.  
  43. //$--_HrFileToMemory----------------------------------------------------------
  44. //  Transfer contents from a given file to memory.
  45. // -----------------------------------------------------------------------------
  46. HRESULT _HrFileToMemory(              // RETURNS: return code
  47.     IN LPSTR lpszFilename,              // pointer to source file name
  48.     OUT ULONG *lpcbmem,                 // pointer to count of bytes of memory
  49.                                         // variable
  50.     OUT LPBYTE *lppbmem);               // pointer to bytes of memory address
  51.                                         // variable
  52.  
  53. //$--HrGetMailboxDN----------------------------------------------------------
  54. //  Retrieves mailbox distinguished name from current session object.
  55. //  Example output: /O=Enterprise/OU=Site/CN=Recipients/CN=MailboxName
  56. // -----------------------------------------------------------------------------
  57. HRESULT HrGetMailboxDN(
  58.     IN  LPMAPISESSION lphSession,       // current session handle
  59.     OUT LPSTR*  ppszMailboxDN);         // distinguished name of mailbox.
  60.  
  61. //$--HrGetServerDN----------------------------------------------------------
  62. //  Retrieves server distinguished name from current session object.
  63. //  Example output: /O=Enterprise/OU=Site/CN=Configuration/CN=Servers/CN=ServerName
  64. // -----------------------------------------------------------------------------
  65. HRESULT HrGetServerDN(
  66.     IN  LPMAPISESSION lphSession,       // current session handle
  67.     OUT LPSTR*  ppszServerDN);          // distinguished name of server. 
  68.  
  69. //$--_HrFindArrayValue--------------------------------------------------------
  70. // Scan through an array of string pointers searching for a value string that
  71. // matches up to the length of the value string.  Case INSENSITIVE.
  72. //
  73. // OUTPUT:  pnIndex will contain the index into the array of the match.  It will
  74. //          contain ~0 if no match was found.  
  75. //
  76. // RETURNS: NOERROR
  77. //          EDK_E_NOT_FOUND if match was not found.
  78. //          EDK_E_AMBIGUOUS if more than one match found.
  79. //          E_INVALIDARG
  80. // -----------------------------------------------------------------------------
  81. HRESULT _HrFindArrayValue(// RETURNS: return code
  82.     IN  LPSTR  pszValue,    // string value to find.
  83.     IN  LPSTR* rgpszArray,  // array of strings containing known values.
  84.     IN  ULONG  nArraySize,  // number of known values.
  85.     OUT ULONG* pnIndex);    // index of known value, ~0 if no match found.
  86.  
  87. //$--_HrExpandCommandLineArgument---------------------------------------------
  88. //  Expands abbreviated command line flags of the form -FLAG=VALUE (or
  89. //  /FLAG=VALUE) to their full text forms returning the index of the  
  90. //  matching flag and a pointer to the data part of the flag (ie the 
  91. //  part after the equals sign).  The caller passes an array of known 
  92. //  flag names, and the function tries to make an unambiguous match 
  93. //  with one of the names.  In this way users can be offered the 
  94. //  convenience of entering /V=Foo, instead of
  95. //  /VERY-LONG-AND-CLUMSY-NAME=Foo (assuming no other flag begins with
  96. //  V, otherwise the user might have to enter more letters).
  97. //
  98. //  The comparison is not case sensitive; the flag names /BLUTO and
  99. //  -bluto are not distinguished, and /b might match on either of them.
  100. //
  101. //  To maintain greater compatibility with other Microsoft NT and DOS
  102. //  command line applications, the ":" character may be substituted 
  103. //  for the "=".  So /FLAG:VALUE or -FLAG:VALUE are also valid.
  104. // -----------------------------------------------------------------------------
  105.  
  106. HRESULT _HrExpandCommandLineArgument(
  107.     IN  LPSTR  pszArg,          // flag user entered
  108.     IN  LPSTR* rgpszArgArray,   // array of known flag names (w/o leading dashes)
  109.     IN  ULONG  nArraySize,      // number of known flags
  110.     OUT ULONG* pnFlagIndex,     // index of known flag, -1 if no match found.
  111.     OUT LPSTR* ppszFlagName,    // known flag name
  112.     OUT LPSTR* ppszArgData);    // user data for flag
  113.  
  114. //$--_nEcFromHr---------------------------------------------------------------
  115. //  Convert an HRESULT to an exit code suitable for return
  116. //  from a console application.
  117. //
  118. //  NOTE:
  119. //
  120. //      EDK HRESULTS get converted to their "code" (current 1 - 4).
  121. //      Any successful HRESULT converts to zero.
  122. //      Any EDK "approved" Win32 or OLE HRESULT gets converted
  123. //      to its EDK exit code (currently 101 - 105).
  124. //      Any non-EDK approved HRESULT gets converted to the negative
  125. //      of its "code" (e.g. -8).
  126. //-----------------------------------------------------------------------------
  127. INT _nEcFromHr(                       // RETURNS: INT
  128.     IN HRESULT hr);                     // HRESULT to convert to exit code
  129.  
  130. //$--HrIdentifyRegistryRootKey--------------------------------------------------
  131. //  Checks that a fully qualified key name begins with one of the four
  132. //    predefined NT Registry keys: HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT,
  133. //    HKEY_CURRENT_USER, or HKEY_USERS.  The output from this function
  134. //    can be passed to registry functions like RegOpenKeyEx().
  135. //
  136. //  NOTE:
  137. //
  138. //        Successful completion.  hkKey is the Registry key handle,
  139. //        pszSubKey points to the remainder of the subkey string.  Note
  140. //        that it is legitimate for pszSubKey to be NULL, meaning that
  141. //        the user is trying to access values in the root of one of the
  142. //        predefined registry keys.
  143. // -----------------------------------------------------------------------------
  144. HRESULT HrIdentifyRegistryRootKey(  // RETURNS: return code
  145.     IN  LPSTR pszKey,               // pointer to fully qualified key name
  146.     OUT HKEY *phkKeyHandle,         // pointer to key handle
  147.     OUT LPSTR *ppszSubKey);         // pointer to subkey section
  148.  
  149. //$--_HrReadRegistrySZ--------------------------------------------------------
  150. //  Read a string from the registry.
  151. // -----------------------------------------------------------------------------
  152. HRESULT _HrReadRegistrySZ(            // RETURNS: return code
  153.     IN HKEY hRegistryKey,                // registry key to read value from
  154.     IN LPSTR lpszValueName,                // name of value to read
  155.     OUT LPSTR lpszBuffer,                // buffer to read value into
  156.     IN OUT DWORD *lpcbBufferSize);        // size of buffer to read value into
  157.  
  158. //$--_HrReadRegistryDWORD-----------------------------------------------------
  159. //  Read a DWORD integer from the registry.
  160. // -----------------------------------------------------------------------------
  161. HRESULT _HrReadRegistryDWORD(            // RETURNS: return code
  162.     IN HKEY hRegistryKey,                // registry key to read value from
  163.     IN LPSTR lpszValueName,                // name of value to read
  164.     OUT LPDWORD lpdwBuffer);            // address of DWORD to read value into
  165.  
  166. //$--_HrWriteRegistrySZ-------------------------------------------------------
  167. //  Write a string to the registry.
  168. // -----------------------------------------------------------------------------
  169. HRESULT _HrWriteRegistrySZ(            // RETURNS: return code
  170.     IN HKEY hRegistryKey,                // registry key to write value to
  171.     IN LPSTR lpszValueName,                // name of value to write
  172.     IN LPCSTR lpszValue);                // string value to write
  173.  
  174. //$--_HrWriteRegistryDWORD----------------------------------------------------
  175. //  Write a DWORD integer to the registry.
  176. // -----------------------------------------------------------------------------
  177. HRESULT _HrWriteRegistryDWORD(        // RETURNS: return code
  178.     IN HKEY hRegistryKey,                // registry key to write value to
  179.     IN LPSTR lpszValueName,                // name of value to write
  180.     IN DWORD dwValue);                    // DWORD value to write
  181.  
  182. //$--_HrInputCommandLinePassword---------------------------------------------------------
  183. //  Input password and echo *'s.
  184. // -----------------------------------------------------------------------------
  185. HRESULT _HrInputCommandLinePassword(                // RETURNS: return code
  186.     IN DWORD dwFlags,                    // reserved--must be zero
  187.     IN DWORD cbLength,                      // size of the buffer in bytes
  188.     OUT LPSTR pszBuffer);                // buffer to write string into
  189.  
  190. //$--HrStrAToStrW---------------------------------------------------------------
  191. //  Convert a byte string to a word string.  The resulting string is placed in 
  192. //  a buffer allocated using MAPIAllocateBuffer.
  193. // -----------------------------------------------------------------------------
  194. HRESULT HrStrAToStrW(                   // RETURNS: return code
  195.     IN  LPCSTR          lpszSource,     // source string
  196.     OUT LPWSTR *        lppwszDest);    // destination string
  197.  
  198. //$--HrStrWToStrA---------------------------------------------------------------
  199. //  Convert a word string to a byte string.  The resulting string is placed in 
  200. //  a buffer allocated using MAPIAllocateBuffer.
  201. // -----------------------------------------------------------------------------
  202. HRESULT HrStrWToStrA(                   // RETURNS: return code
  203.     IN  LPCWSTR         lpwszSource,    // source string
  204.     OUT LPSTR *         lppszDest);     // destination string
  205.  
  206. //$--HrStrAToStrA---------------------------------------------------------------
  207. //  Create an allocated copy of a byte string using MAPIAllocateBuffer.
  208. //  This is useful for creating macros involving TCHAR strings.
  209. // -----------------------------------------------------------------------------
  210. HRESULT HrStrAToStrA(                   // RETURNS: return code
  211.     IN  LPCSTR          lpszSource,     // source string
  212.     OUT LPSTR *         lppszDest);     // destination string
  213.  
  214. //$--HrStrWToStrW---------------------------------------------------------------
  215. //  Create an allocated copy of a word string using MAPIAllocateBuffer.
  216. //  This is useful for creating macros involving TCHAR strings.
  217. // -----------------------------------------------------------------------------
  218. HRESULT HrStrWToStrW(                   // RETURNS: return code
  219.     IN  LPCWSTR         lpwszSource,    // source string
  220.     OUT LPWSTR *        lppwszDest);    // destination string
  221.  
  222. //$--HrStr*ToStr*---------------------------------------------------------------
  223. //  Macros that implement string conversion for TCHAR strings.
  224. // -----------------------------------------------------------------------------
  225.  
  226. #ifdef UNICODE
  227.  
  228. #define HrStrToStr(Source,Dest)     HrStrWToStrW(Source,Dest)
  229. #define HrStrToStrA(Source,Dest)    HrStrWToStrA(Source,Dest)
  230. #define HrStrToStrW(Source,Dest)    HrStrWToStrW(Source,Dest)
  231. #define HrStrAToStr(Soruce,Dest)    HrStrAToStrW(Source,Dest)
  232. #define HrStrWToStr(Source,Dest)    HrStrWToStrW(Source,Dest)
  233.  
  234. #else // UNICODE
  235.  
  236. #define HrStrToStr(Source,Dest)     HrStrAToStrA(Source,Dest)
  237. #define HrStrToStrA(Source,Dest)    HrStrAToStrA(Source,Dest)
  238. #define HrStrToStrW(Source,Dest)    HrStrAToStrW(Source,Dest)
  239. #define HrStrAToStr(Soruce,Dest)    HrStrAToStrA(Source,Dest)
  240. #define HrStrWToStr(Source,Dest)    HrStrWToStrA(Source,Dest)
  241.  
  242. #endif // UNICODE
  243.  
  244. //$--HrGetServiceStatus------------------------------------------------------
  245. //  Get the current state of a service on a given machine.
  246. // -----------------------------------------------------------------------------
  247. HRESULT HrGetServiceStatus(          // RETURNS: return code
  248.     IN LPSTR lpszMachineName,           // machine name
  249.     IN LPSTR lpszServiceName ,          // service name
  250.     OUT DWORD *lpdwCurrentState);       // current state
  251.  
  252. //$--HrGetExchangeStatus-----------------------------------------------------
  253. //  Get the current state of the Exchange server on a given machine.
  254. // -----------------------------------------------------------------------------
  255. HRESULT HrGetExchangeStatus(         // RETURNS: return code
  256.     IN LPSTR lpszMachineName,           // machine name
  257.     OUT DWORD *lpdwService,             // service
  258.     OUT DWORD *lpdwCurrentState);       // current state
  259.  
  260. //$--HrGetExchangeServiceStatus----------------------------------------------
  261. //  Get the current state of an Exchange service on a given machine.
  262. // -----------------------------------------------------------------------------
  263. HRESULT HrGetExchangeServiceStatus(  // RETURNS: return code
  264.     IN LPSTR lpszMachineName,           // machine name
  265.     IN  DWORD dwService,                // service
  266.     OUT DWORD *lpdwCurrentState);       // current state
  267.  
  268. //$--FMachineExists---------------------------------------------------------
  269. //  Returns TRUE if the computer exists.
  270. // -----------------------------------------------------------------------------
  271. BOOL FMachineExists(                // RETURNS: TRUE/FALSE
  272.     IN LPSTR  lpszComputerName);        // address of name of remote computer 
  273.  
  274. //$--_HrFindFile--------------------------------------------------------------
  275. //  Find a file in a directory subtree.
  276. // -----------------------------------------------------------------------------
  277. HRESULT _HrFindFile(                  // RETURNS: return code
  278.     IN LPSTR lpszInPathName,            // starting path name
  279.     IN LPSTR lpszInFileName,            // file name
  280.     OUT LPSTR lpszOutPathName);         // path name where file first found
  281.  
  282. //$--GetSystemEnvironmentVariable-----------------------------------------------
  283. //  Gets a system environment variable.
  284. // -----------------------------------------------------------------------------
  285. DWORD GetSystemEnvironmentVariable(     // RETURNS: size of value
  286.     IN LPSTR  lpszName,                 // environment variable name 
  287.     OUT LPSTR  lpszValue,               // buffer for variable value 
  288.     OUT DWORD  cchValue);               // size of buffer, in characters 
  289.  
  290. //$--SetSystemEnvironmentVariable-----------------------------------------------
  291. //  Sets a system environment variable permanently.
  292. // -----------------------------------------------------------------------------
  293. BOOL SetSystemEnvironmentVariable(      // RETURNS: TRUE/FALSE
  294.     IN LPCSTR  lpszName,                // environment variable name  
  295.     IN LPCSTR  lpszValue);              // new value for variable 
  296.  
  297. //$--GetUserEnvironmentVariable-------------------------------------------------
  298. //  Gets a user environment variable.
  299. // -----------------------------------------------------------------------------
  300. DWORD GetUserEnvironmentVariable(       // RETURNS: size of value
  301.     IN LPSTR  lpszName,                 // environment variable name 
  302.     OUT LPSTR  lpszValue,               // buffer for variable value 
  303.     OUT DWORD  cchValue);               // size of buffer, in characters 
  304.  
  305. //$--SetUserEnvironmentVariable-------------------------------------------------
  306. //  Sets a user environment variable permanently.
  307. // -----------------------------------------------------------------------------
  308. BOOL SetUserEnvironmentVariable(        // RETURNS: TRUE/FALSE
  309.     IN LPCSTR  lpszName,                // environment variable name  
  310.     IN LPCSTR  lpszValue);              // new value for variable 
  311.  
  312. //$--HrTextToRTFCompressed---------------------------------------------------
  313. //  Convert plain ANSI text to its RTF compressed equivalent for a message.
  314. // -----------------------------------------------------------------------------
  315. HRESULT HrTextToRTFCompressed(       // RETURNS: return code
  316.     IN ULONG cchText,                   // # of characters of text
  317.     IN LPSTREAM lpText,                 // plain text stream pointer
  318.     IN ULONG cAttachments,                // # of message attachments
  319.     IN ULONG * rgiRendering,            // attachment rendering positions
  320.     IN LPMESSAGE lpMsg,                 // message pointer
  321.     IN ULONG cpid);                     // code page for the text stream
  322.  
  323. //$--HrRTFCompressedToText---------------------------------------------------
  324. //  Convert message's compressed RTF to its ANSI equivalent.
  325. // -----------------------------------------------------------------------------
  326. HRESULT HrRTFCompressedToText(       // RETURNS: return code
  327.             IN LPMESSAGE lpMsg,         // MAPI message pointer
  328.             IN LPSTREAM pText,          // stream to copy ANSI text to
  329.             IN ULONG cpid,                // code page for  the text stream
  330.             OUT ULONG * pcb);           // # bytes copied to stream
  331.  
  332. //$--HrStrTokAll@---------------------------------------------------------------
  333. //  Splits string lpsz at token separators and points elements of array
  334. //  *lpppsz to string components.
  335. //------------------------------------------------------------------------------
  336. HRESULT HrStrTokAllW(                   // RETURNS: return code
  337.     IN LPCWSTR lpsz,                    // separated string
  338.     IN LPCWSTR lpszEOT,                 // pointer to string containing separators
  339.     OUT ULONG * lpcpsz,                 // count of string pointers
  340.     OUT LPWSTR ** lpppsz);              // pointer to list of strings
  341.  
  342. HRESULT HrStrTokAllA(                   // RETURNS: return code
  343.     IN LPCSTR lpsz,                     // separated string
  344.     IN LPCSTR lpszEOT,                  // pointer to string containing separators
  345.     OUT ULONG * lpcpsz,                 // count of string pointers
  346.     OUT LPSTR ** lpppsz);               // pointer to list of strings
  347.  
  348. #ifdef UNICODE
  349. #define HrStrTokAll HrStrTokAllW
  350. #else
  351. #define HrStrTokAll HrStrTokAllA
  352. #endif
  353.  
  354. //$--HrCreateProfileName-----------------------------------------------------
  355. //  Create a unique profile name.
  356. // -----------------------------------------------------------------------------
  357. HRESULT HrCreateProfileName(         // RETURNS: return code
  358.     IN  LPSTR lpszPrefix,               // prefix of profile name
  359.     IN  ULONG  cBufferSize,             // size of buffer in bytes
  360.     IN OUT LPSTR lpszBuffer);           // buffer
  361.  
  362. //$--HrGetFileVersionInfo----------------------------------------------------
  363. //  Get the file version information.
  364. // -----------------------------------------------------------------------------
  365. HRESULT HrGetFileVersionInfo(        // RETURNS: return code
  366.     IN  LPSTR lpszFileName,             // file name
  367.     OUT LPVOID *lppVersionInfo);        // file version information
  368.  
  369. //$--_GetFileNameFromFullPath--------------------------------------------------
  370. //  Return a pointer to the file name.
  371. // -----------------------------------------------------------------------------
  372. LPSTR _GetFileNameFromFullPath(       // RETURNS: file name
  373.     IN LPSTR lpszFullPath);            // full path name
  374.  
  375. //$--HrCreateDirEntryIdEx-------------------------------------------------------
  376. //  Create a directory entry ID given the address of the object
  377. //  in the directory.
  378. // -----------------------------------------------------------------------------
  379. HRESULT HrCreateDirEntryIdEx(            // RETURNS: HRESULT
  380.     IN    LPADRBOOK    lpAdrBook,            // address book (directory) to look in
  381.     IN    LPSTR        lpszDN,                // object distinguished name
  382.     OUT    ULONG *        lpcbEntryID,        // count of bytes in entry ID
  383.     OUT    LPENTRYID * lppEntryID);        // pointer to entry ID
  384.  
  385. #ifdef __cplusplus
  386. }
  387. #endif
  388.  
  389. #endif
  390.