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