unautils.pas

Voice Commnucation Components for Delphi

{$EXTERNALSYM ShellAboutW}
function ShellAboutW(Wnd: HWND; szApp, szOtherStuff: PWideChar; Icon: HICON): Integer; stdcall;

{DP:METHOD
  Wrapper for ShellAbout function
}
function guiAboutBox(const appName, otherStuff: wideString; handle: tHandle = 0; icon: hIcon = $FFFFFFFF): int;

//	DEBUG

{DP:METHOD
  Returns name of executable module with given extension.
}
function getModuleFileNameExt(const ext: wideString): wideString;
{DP:METHOD
  Produces file name with the same path as executable module.
}
function getModulePathName(const fileName: wideString = ''): wideString;

type

  // --  --
  unaInfoMessage_logTimeModeEnum = (unaLtm_default, unaLtm_none, unaLtm_date, unaLtm_time, unaLtm_dateTime, unaLtm_timeDelta, unaLtm_dateTimeDelta, unaLtm_dateTimeDelta64);


const
  //
  c_logModeFlags_critical	= $0001;
  c_logModeFlags_normal		= $0002;
  c_logModeFlags_debug 		= $0004;


var
  //
  infoLogTimeMode: unaInfoMessage_logTimeModeEnum = {$IFDEF DEBUG}unaLtm_dateTimeDelta{$ELSE}unaLtm_none{$ENDIF};
  infoLogToFile: bool = true;
  infoLogToFileName: bool = true;
  infoLogFileName: wideString = '';
  //
  infoLogToScreen: bool   = {$IFDEF CONSOLE } true {$ELSE } false {$ENDIF };
  infoLogMemoryInfo: bool = {$IFDEF DEBUG   } true {$ELSE } false {$ENDIF };
  infoLogThreadId: bool   = {$IFDEF DEBUG   } true {$ELSE } false {$ENDIF };
  //
  infoLogProcedure: infoMessageProc = nil;
  //
  infoLogMessageFlags: int = {$IFDEF DEBUG } c_logModeFlags_debug or {$ENDIF } c_logModeFlags_normal or c_logModeFlags_critical;
  //
  infoLogUseSystemTime: bool = true;	// use system(UTC) or local time for logging
  infoLogUseWideStrings: bool = false;	// use wide string when writting into log file


{DP:METHOD
  Calls infoMessage() or does nothing if <STRONG>DEBUG</STRONG> symbol was not defined.
}
function assertLog(const message: wideString; logToScreen: int = -1; logToFile: int = -1; logTimeMode: unaInfoMessage_logTimeModeEnum = unaLtm_default; logMemoryInfo: int = -1; logThreadId: int = -1): bool;
{DP:METHOD
  Displays the message on the screen, adds it to debug log file and/or passes it to the infoMessageProc.
  <BR />See setInfoMessageMode() for details.
}
function infoMessage(const message: wideString; logToScreen: int = -1; logToFile: int = -1; logTimeMode: unaInfoMessage_logTimeModeEnum = unaLtm_default; logMemoryInfo: int = -1; logThreadId: int = -1): bool;
{DP:METHOD
  Same as infoMessage() but also checks mode parameter. If (mode > infoLogMessageMode) does nothing.
}
function logMessage(const message: wideString = ''; flags: int = {$IFDEF DEBUG } c_logModeFlags_debug or {$ENDIF } c_logModeFlags_normal; logToScreen: int = -1; logToFile: int = -1; logTimeMode: unaInfoMessage_logTimeModeEnum = unaLtm_default; logMemoryInfo: int = -1; logThreadId: int = -1): bool;

{DP:METHOD
  Specifies the name of debug log and infoMessageProc procedure to be used by the infoMessage() routine.
}
function setInfoMessageMode(const logName: wideString = ''; proc: infoMessageProc = nil; logToScreen: int = -1; logToFile: int = -1; logTimeMode: unaInfoMessage_logTimeModeEnum = unaLtm_default; logMemoryInfo: int = -1; logThreadId: int = -1; useWideStrings: bool = false): string;

{$IFDEF DEBUG}
{DP:METHOD
  Used to display the memory size currently allocated by application.
}
function debug_memAllocated(): unsigned;
{$ENDIF}

// colors
type
  //
  // -- color --
  //
  pRGB = ^tRGB;
  tRGB = packed record
    case bool of
      true: (
	     r: byte;
	     g: byte;
	     b: byte;
	    );
      false: (
	      asInt: int;
	     );
  end;

  //
  // -- color ops --
  //

  tunaColorOp = (unaco_invalid, unaco_wearOut);


{DP:METHOD
}
function color2str(color: int): string;
{DP:METHOD
}
function color2rgb(color: int): tRGB;
{DP:METHOD
}
function colorShift(color: int; op: tunaColorOp): int;

//	WIN API

// 	  -- REGISTRY --

{DP:METHOD
  Reads data from registry.
}
function getRegValue(const path: string; const keyName: string; var buf; var size: unsigned; rootKey: HKEY = HKEY_CURRENT_USER): long; overload;
{DP:METHOD
  Writes data to registry.
}
function setRegValue(const path: string; const keyName: string; const buf; size: unsigned; keyType: int; rootKey: HKEY = HKEY_CURRENT_USER): long; overload;
{DP:METHOD
  Reads integer value from registry.
}
function getRegValue(const path: string; const keyName: string = ''; defValue: int = 0; rootKey: HKEY = HKEY_CURRENT_USER): int; overload;
function getRegValue(const path: string; const keyName: string = ''; defValue: unsigned = 0; rootKey: HKEY = HKEY_CURRENT_USER): unsigned; overload;
{DP:METHOD
  Writes integer value into registry.
}
function setRegValue(const path: string; const keyName: string = ''; keyValue: int = 0; rootKey: HKEY = HKEY_CURRENT_USER): long; overload;
function setRegValue(const path: string; const keyName: string = ''; keyValue: unsigned = 0; rootKey: HKEY = HKEY_CURRENT_USER): long; overload;
{DP:METHOD
  Reads string value from registry.
}
function getRegValue(const path: string; const keyName: string = ''; const defValue: string = ''; rootKey: HKEY = HKEY_CURRENT_USER): string; overload;
{DP:METHOD
  Writes string value into registry.
}
function setRegValue(const path: string; const keyName: string = ''; const keyValue: string = ''; rootKey: HKEY = HKEY_CURRENT_USER): long; overload;

{DP:METHOD
  Enables or disables autorun of specified appication (current module will be used by default).
}
function enableAutorun(doEnable: bool = true; const appPath: string = ''): bool;

// - emergency -
var
  g_emergencyIsOn: bool;
  //g_emergencyAppName: string;
  g_emergencyLogFileName: wideString;

{DP:METHOD
}
function emergencyIsOn(const appName: string; emergencyCode: unsigned = 1): bool;
{DP:METHOD
}
function emergencyLog(const message: string; forceLog: bool = false): bool;

// 	  -- MESSAGES --

{DP:METHOD
  Processes messages waiting to be processed by application or window.
  <BR />Returns number of messages being processed.
}
function processMessages(wnd: hWnd = 0): unsigned;


{DP:METHOD
}
function execApp(const moduleAndParams: wideString = ''; waitForExit: bool = true; showFlags: WORD = SW_SHOW): int; overload;
function execApp(const module: wideString; const params: wideString = ''; waitForExit: bool = true; showFlags: WORD = SW_SHOW): int; overload;
{DP:METHOD
}
function locateProcess(var procEntry: PROCESSENTRY32; const exeName: string = ''): bool;

type
  pprocessEntryArray = ^processEntryArray;
  processEntryArray = array[byte] of PROCESSENTRY32;

  pHandleArray = ^handleArray;
  handleArray = array[byte] of tHandle;

{DP:METHOD
}
function locateProcesses(var procEntries: pprocessEntryArray; const exeName: string = ''): unsigned;

{DP:METHOD
}
function windowsEnum(var wnds: pHandleArray): unsigned;
{DP:METHOD
}
function windowGetFirstChild(parent: hWnd): hWnd;
{DP:METHOD
}
function getProcessWindows(var wnds: pHandleArray; processId: unsigned = 0): unsigned;
{DP:METHOD
  returns processId of first process with same module name,
  or 0 if no such proccess was found.
}
function checkIfDuplicateProcess(doFlashWindow: bool = true): unsigned; overload;
{DP:METHOD
  Returns false if no mutex with given name was created by the time
  of this function execution.

  Creates mutex if it was not created before and returns its handle.

  If mutex already exists, returns true (mutex handle will be valid only when closeIfFound is false).
}
function checkIfDuplicateProcess(const mutexName: wideString; var mutex: tHandle; closeIfFound: bool = true): bool; overload;
{DP:METHOD
}
function setPriority(value: int): int;
{DP:METHOD
}
function getPriority(): int;

{DP:METHOD
  Returns 0 if successfull.
}
function putIntoClipboard(const data: string; window: hWnd = 0{current task}): int;

//	  -- MEMORY --

{DP:METHOD
  Returns allocated memory size.
}
function ams(): int;

{DP:METHOD
  Fills memory block with specified word value.
  <BR />Count is count of words, not bytes.
}
procedure mfill(mem: pointer; count: unsigned; value: word = 0);

{DP:METHOD
  Allocates block of memory.
  <BR />fill specifies the value to fill the allocated block with.
  If fill = -1 malloc() will not fill the block. Otherwise, lowest byte from the fill value will be used to fill the block.
}
function malloc(size: unsigned; doFill: bool = false; fill: byte = 0): pointer; overload;
{DP:METHOD
  Allocates block of memory.
  <P />Data pointed by data parameter is copied into allocated block.
}
function malloc(size: unsigned; data: pointer): pointer; overload;

{DP:METHOD
  Compares two memory blocks.
  <P />Returns true if all bytes are equal.
}
function mcompare(p1, p2: pointer; size: unsigned): bool;

{DP:METHOD
  Reallocates block of memory.
  <BR />Has same functionality as ReallocMem() routine.
  <BR />Returns the resulting pointer.
}
function mrealloc(var data; newSize: unsigned = 0): pointer;

{DP:METHOD
  Scans memory for a byte value.
  Count is number of bytes in buf array.
}
function mscanb(buf: pointer; count: unsigned; value: uint8): pointer;
{DP:METHOD
  Scans memory for a word value.
  Count is number of words in buf array.
}
function mscanw(buf: pointer; count: unsigned; value: uint16): pointer;
{DP:METHOD
  Scans memory for a double word value.
  Count is number of double words in buf array.
}
function mscand(buf: pointer; count: unsigned; value: uint32): pointer;
{DP:METHOD
  Scans memory for a quad word value.
  Count is number of quad words in buf array.
}
function mscanq(buf: pointer; count: uint; const value: int64): pointer;
{DP:METHOD
  Scans memory for array of bytes, pointed by value.
  bufSize is number of bytes in buf array.
  valueLen is number of bytes in value array.
}
function mscanbuf(buf: pArray; bufSize: uint; value: pArray; valueLen: unsigned): pointer;

{DP:METHOD
  Disposes an object.
  <P />Assigns nil value to the object reference.
}
function freeAndNil(var objRef): bool;

{$IFDEF CHECK_MEMORY_LEAKS }

const
  // -- should be enough, increase if necessary --
  maxLeakEntries 	= $20000;
  maxCallStackDepth	= 20;

{DP:METHOD
  passing larger stack size may result in AV for small stacks,
  but increases the possible depth of call stack entry points
}
procedure mleaks_start(maxStackSize: unsigned = 250{fits for most cases});
{DP:METHOD
}
procedure mleaks_stop(produceReport: bool = true);

{$ENDIF }	// CHECK_MEMORY_LEAKS

//	  -- EVENTS --

{DP:METHOD
  Waits specified amount of time for event to be sent in signaled state.
  <BR />Returns true if event was sent to signaled state.
}
function waitForObject(handle: tHandle; timeout: unsigned = 1): bool;

//	  -- HRPC/WINDOWS TIMER --

var
  hrpc_Freq: int64 = 0;		// ticks per second
  hrpc_FreqMs: int64 = 0;	// ticks per millisecond

{DP:METHOD
  "Marks" current time. Uses high-resolution performance counter (HPRC) if possible or GetTickCount() otherwise.
}
function timeMark(): int64;
{DP:METHOD
  Returns number of milliseconds passed between given mark and current time. Uses high-resolution performance counter (HPRC) if available, or GetTickCount() otherwise.
}
function timeElapsed32(mark: int64): unsigned;
{DP:METHOD
  Returns number of internal ticks passed between given mark and current time. Uses high-resolution performance counter (HPRC) if available.
}
function timeElapsed64ticks(mark: int64): int64;
{DP:METHOD
  Returns number of milliseconds passed between given mark and current time. Uses high-resolution performance counter (HPRC) if available, or GetTickCount() otherwise.
}
function timeElapsed64(mark: int64): int64;

//
function sanityCheck(var mark: int64; maxSlice: unsigned = 300; sleepSlice: unsigned = 20; careMessages: bool = true): bool;
function sanityCheck64(var mark: int64; maxSlice: int64 = 300000; sleepSlice: unsigned = 20; careMessages: bool = false): bool;

//	  -- ERROR --

{DP:METHOD
  Returns Windows system error message for given error code.
  <P />If errorCode parameter is 0 (default) it will be replaced with Window.GetLastError() value.
}
function getSysErrorText(errorCode: int = 0; avoidGetCall: bool = false): wideString;

// 	OTHER

// -- --
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.
}
function choice(value: bool; true_choice: char = ' '; false_choice: char = ' '): char; overload;
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.
}
function choice(value: bool; true_choice: int = 1; false_choice: int = 0): int; overload;
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.
}
function choice(value: bool; true_choice: unsigned = 1; false_choice: unsigned = 0): unsigned; overload;
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.
}
function choice(value: bool; const true_choice: string; const false_choice: string = ''): string; overload;
{$IFDEF __AFTER_D5__ }
function choice(value: bool; const true_choice: wideString; const false_choice: wideString = ''): wideString; overload;
{$ENDIF }
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.
}
function choice(value: bool; true_choice: boolean = true; false_choice: boolean = false): bool; overload;
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.
}
function choice(value: bool; true_choice: tObject = nil; false_choice: tObject = nil): tObject; overload;
{DP:METHOD
  Returns one of the choices depending on value of boolean selector.