392 lines
20 KiB
C
392 lines
20 KiB
C
// --edkutils.h-----------------------------------------------------------------
|
|
// EDK utility functions.
|
|
//
|
|
// Copyright 1986 - 1998 Microsoft Corporation. All Rights Reserved.
|
|
// -----------------------------------------------------------------------------
|
|
|
|
#ifndef _EDKUTILS_H_
|
|
#pragma option push -b -a8 -pc -A- /*P_O_Push*/
|
|
#define _EDKUTILS_H_
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif // __cplusplus
|
|
|
|
#define EXCHANGE_DS 1
|
|
#define EXCHANGE_IS 2
|
|
#define EXCHANGE_MTA 3
|
|
#define EXCHANGE_SA 4
|
|
|
|
//$--_HrWriteFile-------------------------------------------------------------
|
|
// Transfer contents from a given memory location & length to an open file.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrWriteFile( // RETURNS: return code
|
|
IN HANDLE hFile, // file handle
|
|
IN ULONG cbmem, // count of bytes of memory
|
|
IN LPBYTE lpbmem); // pointer to memory
|
|
|
|
//$--HrCreateDirEntryId------------------------------------------------------
|
|
// Create a directory entry ID given the address of the object
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrCreateDirEntryId( // RETURNS: return code
|
|
IN LPSTR lpszAddress, // pointer to address
|
|
OUT ULONG *lpcbeid, // count of bytes in entry ID
|
|
OUT LPENTRYID *lppeid); // pointer to entry ID
|
|
|
|
//$--_HrMemoryToFile----------------------------------------------------------
|
|
// Transfer contents from a given memory location & length to a given file.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrMemoryToFile( // RETURNS: return code
|
|
IN ULONG cbmem, // count of bytes of memory
|
|
IN LPBYTE lpbmem, // pointer to memory
|
|
IN LPSTR lpszFilename); // pointer to destination file name
|
|
|
|
//$--_HrFileToMemory----------------------------------------------------------
|
|
// Transfer contents from a given file to memory.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrFileToMemory( // RETURNS: return code
|
|
IN LPSTR lpszFilename, // pointer to source file name
|
|
OUT ULONG *lpcbmem, // pointer to count of bytes of memory
|
|
// variable
|
|
OUT LPBYTE *lppbmem); // pointer to bytes of memory address
|
|
// variable
|
|
|
|
//$--HrGetMailboxDN----------------------------------------------------------
|
|
// Retrieves mailbox distinguished name from current session object.
|
|
// Example output: /O=Enterprise/OU=Site/CN=Recipients/CN=MailboxName
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrGetMailboxDN(
|
|
IN LPMAPISESSION lphSession, // current session handle
|
|
OUT LPSTR* ppszMailboxDN); // distinguished name of mailbox.
|
|
|
|
//$--HrGetServerDN----------------------------------------------------------
|
|
// Retrieves server distinguished name from current session object.
|
|
// Example output: /O=Enterprise/OU=Site/CN=Configuration/CN=Servers/CN=ServerName
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrGetServerDN(
|
|
IN LPMAPISESSION lphSession, // current session handle
|
|
OUT LPSTR* ppszServerDN); // distinguished name of server.
|
|
|
|
//$--_HrFindArrayValue--------------------------------------------------------
|
|
// Scan through an array of string pointers searching for a value string that
|
|
// matches up to the length of the value string. Case INSENSITIVE.
|
|
//
|
|
// OUTPUT: pnIndex will contain the index into the array of the match. It will
|
|
// contain ~0 if no match was found.
|
|
//
|
|
// RETURNS: NOERROR
|
|
// EDK_E_NOT_FOUND if match was not found.
|
|
// EDK_E_AMBIGUOUS if more than one match found.
|
|
// E_INVALIDARG
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrFindArrayValue(// RETURNS: return code
|
|
IN LPSTR pszValue, // string value to find.
|
|
IN LPSTR* rgpszArray, // array of strings containing known values.
|
|
IN ULONG nArraySize, // number of known values.
|
|
OUT ULONG* pnIndex); // index of known value, ~0 if no match found.
|
|
|
|
//$--_HrExpandCommandLineArgument---------------------------------------------
|
|
// Expands abbreviated command line flags of the form -FLAG=VALUE (or
|
|
// /FLAG=VALUE) to their full text forms returning the index of the
|
|
// matching flag and a pointer to the data part of the flag (ie the
|
|
// part after the equals sign). The caller passes an array of known
|
|
// flag names, and the function tries to make an unambiguous match
|
|
// with one of the names. In this way users can be offered the
|
|
// convenience of entering /V=Foo, instead of
|
|
// /VERY-LONG-AND-CLUMSY-NAME=Foo (assuming no other flag begins with
|
|
// V, otherwise the user might have to enter more letters).
|
|
//
|
|
// The comparison is not case sensitive; the flag names /BLUTO and
|
|
// -bluto are not distinguished, and /b might match on either of them.
|
|
//
|
|
// To maintain greater compatibility with other Microsoft NT and DOS
|
|
// command line applications, the ":" character may be substituted
|
|
// for the "=". So /FLAG:VALUE or -FLAG:VALUE are also valid.
|
|
// -----------------------------------------------------------------------------
|
|
|
|
HRESULT _HrExpandCommandLineArgument(
|
|
IN LPSTR pszArg, // flag user entered
|
|
IN LPSTR* rgpszArgArray, // array of known flag names (w/o leading dashes)
|
|
IN ULONG nArraySize, // number of known flags
|
|
OUT ULONG* pnFlagIndex, // index of known flag, -1 if no match found.
|
|
OUT LPSTR* ppszFlagName, // known flag name
|
|
OUT LPSTR* ppszArgData); // user data for flag
|
|
|
|
//$--_nEcFromHr---------------------------------------------------------------
|
|
// Convert an HRESULT to an exit code suitable for return
|
|
// from a console application.
|
|
//
|
|
// NOTE:
|
|
//
|
|
// EDK HRESULTS get converted to their "code" (current 1 - 4).
|
|
// Any successful HRESULT converts to zero.
|
|
// Any EDK "approved" Win32 or OLE HRESULT gets converted
|
|
// to its EDK exit code (currently 101 - 105).
|
|
// Any non-EDK approved HRESULT gets converted to the negative
|
|
// of its "code" (e.g. -8).
|
|
//-----------------------------------------------------------------------------
|
|
INT _nEcFromHr( // RETURNS: INT
|
|
IN HRESULT hr); // HRESULT to convert to exit code
|
|
|
|
//$--HrIdentifyRegistryRootKey--------------------------------------------------
|
|
// Checks that a fully qualified key name begins with one of the four
|
|
// predefined NT Registry keys: HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT,
|
|
// HKEY_CURRENT_USER, or HKEY_USERS. The output from this function
|
|
// can be passed to registry functions like RegOpenKeyEx().
|
|
//
|
|
// NOTE:
|
|
//
|
|
// Successful completion. hkKey is the Registry key handle,
|
|
// pszSubKey points to the remainder of the subkey string. Note
|
|
// that it is legitimate for pszSubKey to be NULL, meaning that
|
|
// the user is trying to access values in the root of one of the
|
|
// predefined registry keys.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrIdentifyRegistryRootKey( // RETURNS: return code
|
|
IN LPSTR pszKey, // pointer to fully qualified key name
|
|
OUT HKEY *phkKeyHandle, // pointer to key handle
|
|
OUT LPSTR *ppszSubKey); // pointer to subkey section
|
|
|
|
//$--_HrReadRegistrySZ--------------------------------------------------------
|
|
// Read a string from the registry.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrReadRegistrySZ( // RETURNS: return code
|
|
IN HKEY hRegistryKey, // registry key to read value from
|
|
IN LPSTR lpszValueName, // name of value to read
|
|
OUT LPSTR lpszBuffer, // buffer to read value into
|
|
IN OUT DWORD *lpcbBufferSize); // size of buffer to read value into
|
|
|
|
//$--_HrReadRegistryDWORD-----------------------------------------------------
|
|
// Read a DWORD integer from the registry.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrReadRegistryDWORD( // RETURNS: return code
|
|
IN HKEY hRegistryKey, // registry key to read value from
|
|
IN LPSTR lpszValueName, // name of value to read
|
|
OUT LPDWORD lpdwBuffer); // address of DWORD to read value into
|
|
|
|
//$--_HrWriteRegistrySZ-------------------------------------------------------
|
|
// Write a string to the registry.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrWriteRegistrySZ( // RETURNS: return code
|
|
IN HKEY hRegistryKey, // registry key to write value to
|
|
IN LPSTR lpszValueName, // name of value to write
|
|
IN LPCSTR lpszValue); // string value to write
|
|
|
|
//$--_HrWriteRegistryDWORD----------------------------------------------------
|
|
// Write a DWORD integer to the registry.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrWriteRegistryDWORD( // RETURNS: return code
|
|
IN HKEY hRegistryKey, // registry key to write value to
|
|
IN LPSTR lpszValueName, // name of value to write
|
|
IN DWORD dwValue); // DWORD value to write
|
|
|
|
//$--_HrInputCommandLinePassword---------------------------------------------------------
|
|
// Input password and echo *'s.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrInputCommandLinePassword( // RETURNS: return code
|
|
IN DWORD dwFlags, // reserved--must be zero
|
|
IN DWORD cbLength, // size of the buffer in bytes
|
|
OUT LPSTR pszBuffer); // buffer to write string into
|
|
|
|
//$--HrStrAToStrW---------------------------------------------------------------
|
|
// Convert a byte string to a word string. The resulting string is placed in
|
|
// a buffer allocated using MAPIAllocateBuffer.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrStrAToStrW( // RETURNS: return code
|
|
IN LPCSTR lpszSource, // source string
|
|
OUT LPWSTR * lppwszDest); // destination string
|
|
|
|
//$--HrStrWToStrA---------------------------------------------------------------
|
|
// Convert a word string to a byte string. The resulting string is placed in
|
|
// a buffer allocated using MAPIAllocateBuffer.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrStrWToStrA( // RETURNS: return code
|
|
IN LPCWSTR lpwszSource, // source string
|
|
OUT LPSTR * lppszDest); // destination string
|
|
|
|
//$--HrStrAToStrA---------------------------------------------------------------
|
|
// Create an allocated copy of a byte string using MAPIAllocateBuffer.
|
|
// This is useful for creating macros involving TCHAR strings.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrStrAToStrA( // RETURNS: return code
|
|
IN LPCSTR lpszSource, // source string
|
|
OUT LPSTR * lppszDest); // destination string
|
|
|
|
//$--HrStrWToStrW---------------------------------------------------------------
|
|
// Create an allocated copy of a word string using MAPIAllocateBuffer.
|
|
// This is useful for creating macros involving TCHAR strings.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrStrWToStrW( // RETURNS: return code
|
|
IN LPCWSTR lpwszSource, // source string
|
|
OUT LPWSTR * lppwszDest); // destination string
|
|
|
|
//$--HrStr*ToStr*---------------------------------------------------------------
|
|
// Macros that implement string conversion for TCHAR strings.
|
|
// -----------------------------------------------------------------------------
|
|
|
|
#ifdef UNICODE
|
|
|
|
#define HrStrToStr(Source,Dest) HrStrWToStrW(Source,Dest)
|
|
#define HrStrToStrA(Source,Dest) HrStrWToStrA(Source,Dest)
|
|
#define HrStrToStrW(Source,Dest) HrStrWToStrW(Source,Dest)
|
|
#define HrStrAToStr(Soruce,Dest) HrStrAToStrW(Source,Dest)
|
|
#define HrStrWToStr(Source,Dest) HrStrWToStrW(Source,Dest)
|
|
|
|
#else // UNICODE
|
|
|
|
#define HrStrToStr(Source,Dest) HrStrAToStrA(Source,Dest)
|
|
#define HrStrToStrA(Source,Dest) HrStrAToStrA(Source,Dest)
|
|
#define HrStrToStrW(Source,Dest) HrStrAToStrW(Source,Dest)
|
|
#define HrStrAToStr(Soruce,Dest) HrStrAToStrA(Source,Dest)
|
|
#define HrStrWToStr(Source,Dest) HrStrWToStrA(Source,Dest)
|
|
|
|
#endif // UNICODE
|
|
|
|
//$--HrGetServiceStatus------------------------------------------------------
|
|
// Get the current state of a service on a given machine.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrGetServiceStatus( // RETURNS: return code
|
|
IN LPSTR lpszMachineName, // machine name
|
|
IN LPSTR lpszServiceName , // service name
|
|
OUT DWORD *lpdwCurrentState); // current state
|
|
|
|
//$--HrGetExchangeStatus-----------------------------------------------------
|
|
// Get the current state of the Exchange server on a given machine.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrGetExchangeStatus( // RETURNS: return code
|
|
IN LPSTR lpszMachineName, // machine name
|
|
OUT DWORD *lpdwService, // service
|
|
OUT DWORD *lpdwCurrentState); // current state
|
|
|
|
//$--HrGetExchangeServiceStatus----------------------------------------------
|
|
// Get the current state of an Exchange service on a given machine.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrGetExchangeServiceStatus( // RETURNS: return code
|
|
IN LPSTR lpszMachineName, // machine name
|
|
IN DWORD dwService, // service
|
|
OUT DWORD *lpdwCurrentState); // current state
|
|
|
|
//$--FMachineExists---------------------------------------------------------
|
|
// Returns TRUE if the computer exists.
|
|
// -----------------------------------------------------------------------------
|
|
BOOL FMachineExists( // RETURNS: TRUE/FALSE
|
|
IN LPSTR lpszComputerName); // address of name of remote computer
|
|
|
|
//$--_HrFindFile--------------------------------------------------------------
|
|
// Find a file in a directory subtree.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT _HrFindFile( // RETURNS: return code
|
|
IN LPSTR lpszInPathName, // starting path name
|
|
IN LPSTR lpszInFileName, // file name
|
|
OUT LPSTR lpszOutPathName); // path name where file first found
|
|
|
|
//$--GetSystemEnvironmentVariable-----------------------------------------------
|
|
// Gets a system environment variable.
|
|
// -----------------------------------------------------------------------------
|
|
DWORD GetSystemEnvironmentVariable( // RETURNS: size of value
|
|
IN LPSTR lpszName, // environment variable name
|
|
OUT LPSTR lpszValue, // buffer for variable value
|
|
OUT DWORD cchValue); // size of buffer, in characters
|
|
|
|
//$--SetSystemEnvironmentVariable-----------------------------------------------
|
|
// Sets a system environment variable permanently.
|
|
// -----------------------------------------------------------------------------
|
|
BOOL SetSystemEnvironmentVariable( // RETURNS: TRUE/FALSE
|
|
IN LPCSTR lpszName, // environment variable name
|
|
IN LPCSTR lpszValue); // new value for variable
|
|
|
|
//$--GetUserEnvironmentVariable-------------------------------------------------
|
|
// Gets a user environment variable.
|
|
// -----------------------------------------------------------------------------
|
|
DWORD GetUserEnvironmentVariable( // RETURNS: size of value
|
|
IN LPSTR lpszName, // environment variable name
|
|
OUT LPSTR lpszValue, // buffer for variable value
|
|
OUT DWORD cchValue); // size of buffer, in characters
|
|
|
|
//$--SetUserEnvironmentVariable-------------------------------------------------
|
|
// Sets a user environment variable permanently.
|
|
// -----------------------------------------------------------------------------
|
|
BOOL SetUserEnvironmentVariable( // RETURNS: TRUE/FALSE
|
|
IN LPCSTR lpszName, // environment variable name
|
|
IN LPCSTR lpszValue); // new value for variable
|
|
|
|
//$--HrTextToRTFCompressed---------------------------------------------------
|
|
// Convert plain ANSI text to its RTF compressed equivalent for a message.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrTextToRTFCompressed( // RETURNS: return code
|
|
IN ULONG cchText, // # of characters of text
|
|
IN LPSTREAM lpText, // plain text stream pointer
|
|
IN ULONG cAttachments, // # of message attachments
|
|
IN ULONG * rgiRendering, // attachment rendering positions
|
|
IN LPMESSAGE lpMsg, // message pointer
|
|
IN ULONG cpid); // code page for the text stream
|
|
|
|
//$--HrRTFCompressedToText---------------------------------------------------
|
|
// Convert message's compressed RTF to its ANSI equivalent.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrRTFCompressedToText( // RETURNS: return code
|
|
IN LPMESSAGE lpMsg, // MAPI message pointer
|
|
IN LPSTREAM pText, // stream to copy ANSI text to
|
|
IN ULONG cpid, // code page for the text stream
|
|
OUT ULONG * pcb); // # bytes copied to stream
|
|
|
|
//$--HrStrTokAll@---------------------------------------------------------------
|
|
// Splits string lpsz at token separators and points elements of array
|
|
// *lpppsz to string components.
|
|
//------------------------------------------------------------------------------
|
|
HRESULT HrStrTokAllW( // RETURNS: return code
|
|
IN LPCWSTR lpsz, // separated string
|
|
IN LPCWSTR lpszEOT, // pointer to string containing separators
|
|
OUT ULONG * lpcpsz, // count of string pointers
|
|
OUT LPWSTR ** lpppsz); // pointer to list of strings
|
|
|
|
HRESULT HrStrTokAllA( // RETURNS: return code
|
|
IN LPCSTR lpsz, // separated string
|
|
IN LPCSTR lpszEOT, // pointer to string containing separators
|
|
OUT ULONG * lpcpsz, // count of string pointers
|
|
OUT LPSTR ** lpppsz); // pointer to list of strings
|
|
|
|
#ifdef UNICODE
|
|
#define HrStrTokAll HrStrTokAllW
|
|
#else
|
|
#define HrStrTokAll HrStrTokAllA
|
|
#endif
|
|
|
|
//$--HrCreateProfileName-----------------------------------------------------
|
|
// Create a unique profile name.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrCreateProfileName( // RETURNS: return code
|
|
IN LPSTR lpszPrefix, // prefix of profile name
|
|
IN ULONG cBufferSize, // size of buffer in bytes
|
|
IN OUT LPSTR lpszBuffer); // buffer
|
|
|
|
//$--HrGetFileVersionInfo----------------------------------------------------
|
|
// Get the file version information.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrGetFileVersionInfo( // RETURNS: return code
|
|
IN LPSTR lpszFileName, // file name
|
|
OUT LPVOID *lppVersionInfo); // file version information
|
|
|
|
//$--_GetFileNameFromFullPath--------------------------------------------------
|
|
// Return a pointer to the file name.
|
|
// -----------------------------------------------------------------------------
|
|
LPSTR _GetFileNameFromFullPath( // RETURNS: file name
|
|
IN LPSTR lpszFullPath); // full path name
|
|
|
|
//$--HrCreateDirEntryIdEx-------------------------------------------------------
|
|
// Create a directory entry ID given the address of the object
|
|
// in the directory.
|
|
// -----------------------------------------------------------------------------
|
|
HRESULT HrCreateDirEntryIdEx( // RETURNS: HRESULT
|
|
IN LPADRBOOK lpAdrBook, // address book (directory) to look in
|
|
IN LPSTR lpszDN, // object distinguished name
|
|
OUT ULONG * lpcbEntryID, // count of bytes in entry ID
|
|
OUT LPENTRYID * lppEntryID); // pointer to entry ID
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#pragma option pop /*P_O_Pop*/
|
|
#endif
|