unautils.pas

Voice Commnucation Components for Delphi

(*
	----------------------------------------------

	  unaUtils.pas
	  basic routines

	----------------------------------------------
	  This source code cannot be used without
	  proper license granted to you as a private
	  person or an entity by the Lake of Soft, Ltd

	  Visit http://lakeofsoft.com/ for more information.

	  Copyright (c) 2001, 2006 Lake of Soft, Ltd
		     All rights reserved
	----------------------------------------------

	  created by:
		Lake, 25 Aug 2001

	  modified by:
		Lake, Aug-Dec 2001
		Lake, Jan-Dec 2002
		Lake, Jan-Dec 2003
		Lake, Jan-Dec 2004
		Lake, Jan-Oct 2005
		Lake, Jan-Feb 2006

	----------------------------------------------
*)

{$I unaDef.inc}

{xx $DEFINE __SYSUTILS_H_ }	// must be defined, if you want to use this unit along with sysUtils.pas

{xx $DEFINE HOOK_EXCEPTIONS_ALWAYS }	// when defined will hook exceptions regardless to symbol __SYSUTILS_H_ definition
					// when not defined exceptions will be hooked only when symbol __SYSUTILS_H_ is not defined

{xx $DEFINE CHECK_MEMORY_LEAKS }	// enable memory leaks checking routines

unit
  unaUtils;

{DP:UNIT
  Contains useful routines used by other units and classes.
  <P /><STRONG>NOTE:</STRONG> This unit installs own simple exceptions and assertions handling code unless <STRONG>__SYSUTILS_H_</STRONG> symbol is defined (usually in Project Options).
  This symbol is also defined automatically for GUI target of VC 2.1 Pro.
}

interface

uses
  Windows, unaTypes,
{$IFDEF __SYSUTILS_H_ }
  SysUtils,
{$IFDEF __AFTER_D5__ }
  Variants,
{$ENDIF}
{$ENDIF}
  TlHelp32;

{
  Note from Delphi Help.

procedure Test(A: Integer; var B: Char; C: Double; const D: string; E: Pointer);

  - a call to Test passes A in EAX as a 32-bit integer,
			  B in EDX as a pointer to a Char,
		      and D in ECX as a pointer to a long-string memory block;
    C and E are pushed onto the stack as two double-words and a 32-bit pointer,
    in that order.

Under the register convention, Self behaves as if it were declared before
all other parameters. It is therefore always passed in the EAX register.

For a string, dynamic array, method pointer, variant, or Int64 result,
the effects are the same as if the function result were declared as an additional
var parameter following the declared parameters. In other words, the caller passes
an additional 32-bit pointer that points to a variable in which to return the
function result.

Register saving conventions
Procedures and functions must preserve the EBX, ESI, EDI, and EBP registers,
but can modify the EAX, EDX, and ECX registers. When implementing a
constructor or destructor in assembler, be sure to preserve the DL register.

Procedures and functions are invoked with the assumption that the CPU抯 direction
flag is cleared (corresponding to a CLD instruction) and must return with the
direction flag cleared.

}


type
  // type section is required to be the first for docProducer to work correctly

  {DP:METHOD
    This procedure type is used by infoMessage() routine.
  }
  infoMessageProc = procedure (const message: wideString);

//	MATH

{$IFDEF __SYSUTILS_H_ }
{$ELSE}

type
  pWordArray = ^tWordArray;
  tWordArray = array[0..16383] of Word;

{DP:METHOD
  Returns A if A &lt; B, or B otherwise.
}
function min(A, B: int): int; overload;
function min(A, B: unsigned): unsigned; overload;
function min(A, B: int64): int64; overload;
{DP:METHOD
  Returns A if A &gt; B, or B otherwise.
}
function max(A, B: int): int; overload;
function max(A, B: unsigned): unsigned; overload;
function max(A, B: int64): int64; overload;
function max(A, B: double): double; overload;

{DP:METHOD
}
procedure abort();

{$ENDIF }	// not __SYSUTILS_H_

//	ENCODING

{DP:METHOD
  Encodes data with base64 method.
  <BR />Returns encoded result as string.
}
function base64encode(data: pointer; size: unsigned): string; overload;
{DP:METHOD
  Encodes string with base64 method.
  <BR />Returns encoded result as string.
}
function base64encode(const data: string): string; overload;
{DP:METHOD
  Decodes string encoded with base64 method.
  <BR />Returns decoded result as string.
}
function base64decode(const data: string): string; overload;
{DP:METHOD
  Decodes data encoded with base64 method.
  <BR />Returns decoded result as string.
}
function base64decode(data: pointer; len: unsigned): string; overload;
{DP:METHOD
  Decodes data encoded with base64 method.
  <BR />NOTE: buf will be allocated. Make sure buf is not the only pointer on allocated memory before calling this routine. Use mrealloc() to deallocate memory pointed by buf.
  <BR />Returns size of decoded data in bytes.
}
function base64decode(const data: string; out buf: pointer): unsigned; overload;

{
}
function base65encode(data: pointer; len: unsigned): string; overload;
function base65encode(const data: string): string; overload;
{
}
function base65decode(data: pointer; len: unsigned): string; overload;
function base65decode(const data: string): string; overload;

// --  --
function baseXencode(const data, key: string; ver: int): string;
function baseXdecode(const data, key: string; ver: int): string;

{DP:METHOD
  Calculates CRC32 checksum.
  <P />Based on Hagen Reddmann code.
}
function crc32(const data: string; crc: uint32 = $FFFFFFFF): uint32; overload;
{DP:METHOD
  Calculates CRC32 checksum.
  <P />Based on Hagen Reddmann code.
}
function crc32(data: pointer; len: unsigned; crc: uint32 = $FFFFFFFF): uint32; overload;
{DP:METHOD
  Calculates CRC32 checksum.
  <P />Based on Hagen Reddmann code.
}
function crc16(data: pointer; len: unsigned): uint16;
{DP:METHOD
  Calculates CRC8 checksum.
  <P />Based on Hagen Reddmann code.
}
function crc8(data: pointer; len: unsigned): uint8;
{DP:METHOD
  Calculates CRC4 checksum.
  <P />Based on Hagen Reddmann code.
}
function crc4(data: pointer; len: unsigned): uint8;




// UTF8/UTF16/UNICODE functions

const
  //
  zeroWidthNonBreakingSpace     = $FEFF;
  zeroWidthNonBreakingSpaceW 	= wideChar(zeroWidthNonBreakingSpace);
  zeroWidthNonBreakingSpaceUTF8 = #$EF#$BB#$BF;

  //
  unicodeHighSurrogateStart = $D800;
  unicodeHighSurrogateEnd   = $DBFF;
  unicodeLowSurrogateStart  = $DC00;
  unicodeLowSurrogateEnd    = $DFFF;


function cp2UTF8(cp: uint32): string;
function highSurrogate(cp: uint32): uint16;
function lowSurrogate(cp: uint32): uint16;
function isHighSurrogate(w: uint16): bool;
function isLowSurrogate(w: uint16): bool;
function surrogate2cp(highSurrogate, lowSurrogate: uint16): uint32;
function UTF162UTF8(const w: wideString): string;
function UTF82UTF16(const s: string): wideString;


//	FILES

{DP:METHOD
  Returns nice string about file size.
}
function fileSize2str(sz: int64): string;
{DP:METHOD
  Returns true if specified file exists.
}
function fileExists(const name: wideString): bool;
{DP:METHOD
  Creates specified file. If file already exists, truncates it to zero-length file (if truncate is true).
  <BR />Returns INVALID_HANDLE_VALUE if file creation has been failed for some reason;
  <BR />Returns 0 if file was created successfully, and leaveOpen equals false;
  <BR />Returns file handle if file was created successfully, and leaveOpen equals true.
}
function fileCreate(const name: wideString; truncate: bool = true; leaveOpen: bool = false): tHandle;
{DP:METHOD
  Opens a file. Returns INVALID_HANDLE_VALUE if file does not exist, or some other error occured.
  Returns 0 otherwise.
}
function fileOpen(const name: wideString; wantWrites: bool = false; allowSharedWrites: bool = true): tHandle;
{DP:METHOD
}
function fileClose(f: tHandle): bool;
{DP:METHOD
  Truncates file at specified position.
  <BR />Returns false if truncation has been failed for some reason.
}
function fileTruncate(handle: tHandle; pos: unsigned = 0; posMode: unsigned = FILE_BEGIN): bool;
{DP:METHOD
  Writes data into file specified by name at specified position. Creates the file if it does not exists before operation.
  <BR />Returns:
  <UL>
	<LI>0 if operation has been completed successfully, or buf = nil, or size &lt; 1.</LI>
	<LI>-1 if no file name was given.</LI>
	<LI>-2 if there was some error in opening the file.</LI>
	<LI>-3 if operation has been failed for some reason.</LI>
	<LI>-4 if number of bytes written does not equal to given size.</LI>
  </UL>
}
function writeToFile(const name: wideString; buf: pointer; size: unsigned; pos: unsigned = 0; posMode: unsigned = FILE_END): int; overload;
function writeToFile(const name: wideString; const buf: string; pos: unsigned = 0; posMode: unsigned = FILE_END): int; overload;
{DP:METHOD
  Writes data into the file specified by handle at specified position.
  <BR />Returns:
  <UL>
	<LI>0 if operation has been completed successfully, or buf = nil, or size &lt; 1.</LI>
	<LI>-2 if invalid file handle has been passed.</LI>
	<LI>-3 if operation has been failed for some reason.</LI>
	<LI>-4 if number of bytes written does not equal to given size.</LI>
  </UL>
}
function writeToFile(handle: tHandle; buf: pointer; size: unsigned; pos: unsigned = 0; posMode: unsigned = FILE_CURRENT): int; overload;
function writeToFile(handle: tHandle; const buf: string; pos: unsigned = 0; posMode: unsigned = FILE_CURRENT): int; overload;
{DP:METHOD
  Reads data from file specified by name at specified position.
  <BR />size will be set to number of bytes actually read from the file, or to 0 if some error occurs.
  <BR />Returns:
  <UL>
	<LI>0 if operation has been completed successfully, or buf = nil, or size &lt; 1.</LI>
	<LI>-1 if no file name was given.</LI>
	<LI>-2 if there was an error in opening the file.</LI>
	<LI>-3 if operation has been failed for some reason.</LI>
	<LI>-4 if number of bytes read does not equal to given size.</LI>
  </UL>
}
function readFromFile(const name: wideString; buf: pointer; var size: unsigned; pos: unsigned = 0; posMode: unsigned = FILE_BEGIN): int; overload;
function readFromFile(const name: wideString; pos: unsigned = 0; posMode: unsigned = FILE_BEGIN): string; overload;
function readFromFileW(const name: wideString; pos: unsigned = 0; posMode: unsigned = FILE_BEGIN): wideString;
{DP:METHOD
  Reads data from file specified by name at specified position.
  <BR />size will be set to number of bytes actually read from the file, or to 0 if some error occurs.
  <BR />Returns:
  <UL>
	<LI>0 if operation has been completed successfully, or buf = nil, or size &lt; 1.</LI>
	<LI>-2 if invalid file handle has been passed.</LI>
	<LI>-3 if operation has been failed for some reason.</LI>
	<LI>-4 if number of bytes read does not equal to given size.</LI>
  </UL>
}
function readFromFile(handle: tHandle; buf: pointer; var size: unsigned; pos: unsigned = 0; posMode: unsigned = FILE_CURRENT): int; overload;
{DP:METHOD
  Returns file size, or -1 if file does not exists.
}
function fileSize(const name: wideString): int; overload;
{DP:METHOD
  Returns file size, or -1 if file does not exists.
}
function fileSize(handle: tHandle): int; overload;
{DP:METHOD
  Seeks the file to specified position.
  <BR />Returns resulting file position or -1 if file handle is invalid.
}
function fileSeek(handle: tHandle; pos: int32 = 0; posMode: unsigned = FILE_BEGIN): int;
{DP:METHOD
  Renames the file.
}
function fileMove(const oldName, newName: wideString): bool;
{DP:METHOD
  Copies the file.
}
function fileCopy(const oldName, newName: wideString; failIfExists: bool): bool;
{DP:METHOD
  Removes the file.
}
function fileDelete(const fileName: wideString): bool;
{DP:METHOD
  Returns CRC32 checksum of a file.
}
function fileChecksum(f: tHandle; crc: uint32 = $FFFFFFFF): uint32; overload;
{DP:METHOD
  Returns CRC32 checksum of a file.
}
function fileChecksum(const fileName: wideString): uint32; overload;
{DP:METHOD
}
function fileModificationDateTime(const fileName: wideString; useLocalTime: bool = true): SYSTEMTIME; overload;
{DP:METHOD
}
function fileModificationDateTime(f: tHandle; useLocalTime: bool = true): SYSTEMTIME; overload;

{DP:METHOD
  Returns true if specified directory exists.
}
function directoryExistsW(const name: wideString): bool;
{DP:METHOD
  Ensures specified path exists. Recursively creates directories as required.
}
function forceDirectoriesW(const path: wideString): bool;
{DP:METHOD
  Returns file path (without file name).
}
function extractFilePathW(const fileName: wideString): wideString;
{DP:METHOD
  Returns file name (without file path).
}
function extractFileNameW(const fileName: wideString): wideString;
{DP:METHOD
  Replaces the file extension with given one.
}
function changeFileExtW(const fileName: wideString; const ext: wideString = '.txt'): wideString;
{DP:METHOD
}
function GetLongPathNameW(shortPathName: wideString): wideString;


const
  { Browsing for directory. }

  {$EXTERNALSYM BIF_RETURNONLYFSDIRS}
  BIF_RETURNONLYFSDIRS   = $0001;  { For finding a folder to start document searching }
  {$EXTERNALSYM BIF_DONTGOBELOWDOMAIN}
  BIF_DONTGOBELOWDOMAIN  = $0002;  { For starting the Find Computer }
  {$EXTERNALSYM BIF_STATUSTEXT}
  BIF_STATUSTEXT         = $0004;
  {$EXTERNALSYM BIF_RETURNFSANCESTORS}
  BIF_RETURNFSANCESTORS  = $0008;
  {$EXTERNALSYM BIF_EDITBOX}
  BIF_EDITBOX            = $0010;
  {$EXTERNALSYM BIF_VALIDATE}