       ASA Soft Memory Mapped Files components.
       Version 1.21 (16.16.98) for Delphi 2/3.
       Copyright 1998 ASA Soft.

       e-mail: asacomp@chat.ru
       Home page: http://www.chat.ru/~asacomp
                               OR
                  http://www.geocities.com/SiliconValley/Pines/3653 

    This product is shareware (see License.txt).
  If you use shareware version, the components will work only
  in Delphi environment.

  Files
  =====
    D2\*.* - files version for Delphi 2 only.
    D3\*.* - files version for Delphi 3 only.
    Dx = D2 or D3 

    Dx\FREE\MemDumpView.dcu - TMemDumpView free component (view and edit memory region)
    Dx\FREE\asaCDlg.dcu - ASA Soft commom dialogs ( TasaAboutBox free component)
    Dx\FREE\asaUCtrlReg.pas - unit contains Register procedure 
    Dx\FREE\asaUCtrlReg.dcr - component resources
    D3\FREE\asaUCtrl.dpk - source package code for installing in Delphi 3
    D3\FREE\asaUCtrl.res - resource file for package asaUCtrl
    Dx\asa_mmf.dcu - base unit, contains components: TasaMMF_API, TasaMMF.
    Dx\MemoryViewer.dcu \
    Dx\MemoryViewer.dfm - unit and form component editor (Memory Viewer for TasaMMF)
    Dx\FileMapSetupDlg.dcu \
    Dx\FileMapSetupDlg.dfm - unit and form component editor (Properties setup dialog for TasaMMF)
    Dx\FileMapReg.pas - unit contains Register procedure.
    Dx\FileMapReg.dcr - component resources unit.
    D3\fmap.dpk - source package module for installing on Delphi 3
    D3\fmap.res - resources for fmap.dpk
    Dx\Demo\HexView\*.* - demo project (Simple file viewer
  based on TasaMMF component and TMemDumpView bonus component )
    Dx\Demo\TestMMF\*.* - another demo project with several examples
  of use component TasaMMF.
    asa_mmf.txt - this file with description
    license.txt - license agreement description
    order.txt - how to register

  Installation for Delphi 3.
  ==========================
    Copy all files on the some folder, open and install from
  Delphi IDE package D3\FREE\asaUCtrl.dpk and then D3\fmap.dpk
    Folders, where the files was established should be
  specified on Lybrary page in Lybrary Path edit of
  Delphi Environment options.

  Installation for Delphi 2 (if Delphi 2 files is available).
  ===========================================================
      Copy all files on the some folder, open and install from
  Delphi IDE files D2\FREE\asaUCtrlReg.pas and then D2\FileMapReg.pas
    Folders, where the files was established should be
  specified on Lybrary page in Lybrary Path edit of
  Delphi Environment options.

                      DESCRIPTION asa_mmf UNIT:

  I. Types
  ========
  TFileAccessOption = (faGENERIC_ALL, faGENERIC_EXECUTE,
    faGENERIC_READ, faGENERIC_WRITE, faFILE_SHARE_READ,
    faFILE_SHARE_WRITE);

    This type specifies the kind of access to the object.
      faGENERIC_ALL - all access
      faGENERIC_EXECUTE - access on execute file
      faGENERIC_READ - access on read
      faGENERIC_WRITE - access on read/write

    To share the object, use a combination of one or more
    Of the following values:
      faFILE_ SHARE_READ - Subsequent open operations
    On the object will succeed only if read access is requested.
      faFILE_ SHARE_WRITE - Subsequent open operations
    On the object will succeed only if write access is requested.

  TFileAccessOptions = Set of TFileAccessOption;
    Set of file acces options (TFileAccessOption).

  TFileCreateOption = (fcCREATE_NEW, fcCREATE_ALWAYS,
  fcOPEN_EXISTING, fcOPEN_ALWAYS, fcTRUNCATE_EXISTING);
    This type specifies a way of opening or creation of a file.
      fcCREATE_NEW - Creates a new file. The function fails
    If the specified file already exists.
      fcCREATE_ALWAYS - Creates a new file. The function overwrites
    The file if it exists.
      fcOPEN_EXISTING - Opens the file. The function fails
    If the file does not exist.
      fcOPEN_ALWAYS - Opens the file, if it exists.
    If the file does not exist, the function creates the file
    As if dwCreationDistribution were CREATE _ NEW.
      fcTRUNCATE_EXISTING - Opens the file. Once opened, the file
    Is truncated so that its size is zero bytes. The calling
    Process must open the file with at least GENERIC _ WRITE access.
    The function fails if the file does not exist.

  TFileAttribute = (faARCHIVE, faCOMPRESSED, faNORMAL, faHIDDEN,
  faREADONLY, faSYSTEM, faWRITE _ THROUGH, faOVERLAPPED,
  faNO_BUFFERING, faRANDOM_ACCESS, faSEQUENTIAL_SCAN,
  faDELETE_ON_CLOSE, faBACKUP_SEMANTICS, faPOSIX_SEMANTICS,
  faSECURITY_ANONYMOUS, faSECURITY_IDENTIFICATION,
  faSECURITY_IMPERSONATION, faSECURITY_DELEGATION,
  faSECURITY_CONTEXT_TRACKING, faSECURITY_EFFECTIVE_ONLY);
    Specifies the file attributes and flags for the file.
  See Win32 API reference for full description.

  TFileAttributes = Set of TFileAttribute;
    Set of file attributes (TFileAttribute).

  TMapProtectOption = (mpPAGE_READONLY, mpPAGE_READWRITE,
  mpPAGE_WRITECOPY);
    Specifies the protection desired for the file view,
    When the file is mapped. This parameter can be one
    Of the following values:
      mpPAGE_READONLY - Gives read-only access to the committed region
    Of pages. An attempt to write to or execute the committed region
    Results in an access violation. The file specified by the
    FileHandle property must have been created with faGENERIC_READ
    Access.
      mpPAGE_READWRITE - Gives read-write access to the committed
    Region of pages. The file specified by FileHandle must have been
    Created with faGENERIC_READ and faGENERIC_WRITE access.
      mpPAGE_WRITECOPY - Gives copy on write access to the committed
    Region of pages. The files specified by the FileHandle parameter
    Must have been created with faGENERIC_READ and faGENERIC_WRITE
    access.

  TMapOption = (moSEC_COMMIT, moSEC_IMAGE, moSEC_NOCACHE, moSEC_RESERVE);
    Additional attributes for page protection.
      moSEC_COMMIT - Allocates physical storage in memory or in
    The paging file on disk for all pages of a section. This is
    The default setting.
      moSEC_IMAGE - The file specified for a section's file mapping
    Is an executable image file. Because the mapping information
    And file protection are taken from the image file, no other
    Attributes are valid with moSEC_IMAGE.
      moSEC_NOCACHE (Windows NT only) - All pages of a section are to be set as
    Non-cacheable. moSEC_NOCACHE requires either the moSEC_RESERVE
    Or moSEC_COMMIT to also be set.
      moSEC_RESERVE - Reserves all pages of a section without
    Allocating physical storage. The reserved range of pages
    Cannot be used by any other allocation operations until it
    Is released. Reserved pages can be committed in subsequent
    Calls to the VirtualAlloc function. This attribute is valid
    Only if the FileHandle parameter is (HANDLE) 0xFFFFFFFF; that is,
    A file mapping object backed by the operating sytem paging file.
  TMapOptions = set of TMapOption;
    Set of map options. (TMapOption)

  TMapViewOption = (mvFILE_MAP_WRITE, mvFILE_MAP_READ,
  mvFILE_MAP_ALL_ACCESS, mvFILE_MAP_COPY);
    Specifies the type of access to the file-mapping object and,
    Therefore, the page protection of the pages mapped by the file.
    This can be one of the following values:
      mvFILE_MAP_WRITE - Read-and-write access. The MapHandle
    Must have been created with mpPAGE_READWRITE protection.
    A read-write view of the file is mapped.
      mvFILE_MAP_READ - Read-only access. The MapHandle
    Must have been created with mpPAGE_READWRITE or
    mpPAGE_READONLY protection. A read-only view of the file is mapped.
      mvFILE_MAP_ALL_ACCESS - Same as mvFILE_MAP_WRITE.
      mvFILE_MAP_COPY - Copy on write access. If you create
    The map with mpPAGE_WRITECOPY and the view with mvFILE_MAP_COPY,
    You will receive a view to the file. If you write to it,
    The pages are automatically swappable and the modifications
    You make will not go to the original data file.
    (Windows 95: You must specifie mpPAGE_WRITECOPY; otherwise,
    An error will be returned. If you share the mapping between
    Multiple processes and one process writes to a view,
    The modification is propagated to the other process.
    The original file does not change.)
    (Windows NT: There is no restriction as to how the MapHandle
    Must be created. Copy on write is valid for any type of view.
    If you share the mapping between multiple processes and one
    Process writes to a view, the modification is not propagated
    To the other process. The original file does not change.)

  TMMFState = (mmfClosed,mmfCreated,mmfOpened,mmfMapped);
    Specifies type of the state of the file-mapping object.
      mmfClosed - object closed (all handles closed).
      mmfCreated - object is opened, up to it the object with
    such name(MapName) did not exist.
      mmfOpened - object is opened, it refers to other object
    with the same name (MapName).
      mmfMapped - object is opened by any of ways
    (mmfOpened,mmfCreated), and there is even one its view.
  TMMFStateSet = Set of TMMFState;


  II. Component TasaMMF_API.
  =========================

  1. Description.
  ---------------
    Component TasaMMF_API - base class, realizing
  Access to Windows API for memory mapped files.
     All properties and methods is protected, therefore for
  uses of its opportunities the class-successor is necessary.

  2. Properties:
  --------------

  Property FileHandle: DWORD; read-only
      Open handle to the specified file.
  Property MapHandle: DWORD;
      Open handle to the file-mapping object.
  Property Mapping [Index: LongInt]: Pointer;
      Array of base addresses for map views of
      this file-mapping object (MapHandle)
  Property MapCount: LongInt;
      Quantity map views  of this file-mapping object (MapHandle)
  Property FileName: String;
      Name of a file.
  Property MapName;
      Name for file-mapping object. If necessary
    share access from a few file-mapping objects to the some file.
  Property FileAccessOptions: TFileAccessOptions;
      File access (read-write) and file share modes.
    (see TFileAccessOptions)
  Property FileCreateOption: TFileCreateOption;
      File open/create mode. (see TFileCreateOption)
  Property FileAttributes: TFileAttributes;
      File attributes and flags. (see TFileAttributes)
  Property MapProtectOption: TMapProtectOption;
      Specifies the protection desired for the file view,
    When the file is mapped. (see TMapProtectOption
  Property MapOptions: TMapOptions;
      Additional values for MapProtectOption. (see TMapOptions)
  Property MaxSizeLow: DWORD;
      Specifies the low-order 32 bits of the maximum size
    Of the file-mapping object. If this parameter and
    MaxSizeHigh are zero, the maximum size of the
    File-mapping object is equal to the current size of
    The file identified by FileHandle.
  Property MaxSizeHigh: DWORD;
      Specifies the high-order 32 bits of the maximum size
    Of the file-mapping object.
  Property MMFState: TMMFStateSet;
      Specifies the current state of the file-mapping object.
    (see TMMFStateSet)

  3. Methods.
  -----------

  Procedure CreateMMF; virtual;
    Create new file-mapping object named MapName from file FileName
  with given properties.

  Procedure OpenMMF(AMapViewOption: TMapViewOption); virtual;
    Open existing file-mapping object named MapName with given
  properties.

  Procedure CloseMMF; virtual;
    Close file-mapping object.

  Function MapViewMMF (AMapViewOption: TMapViewOption; dwFileOffsetHigh,
          DwFileOffsetLow, dwNumberOfBytesToMap: DWORD; BaseAddr: pointer): pointer; virtual;
    Create maps a view of a file into the address space of the
  Calling process. Arguments:
    dwFileOffsetHigh - Specifies the high-order 32 bits of the
  File offset where mapping is to begin.
    dwFileOffsetLow - Specifies the low-order 32 bits of the file
  Offset where mapping is to begin. The combination of the high and
  Low offsets must specify an offset within the file that matches
  The system's memory allocation granularity, or the function fails.
  That is, the offset must be a multiple of the allocation
  Granularity. Use the GetSystemInfo function, which fills
  In the members of a SYSTEM _ INFO structure, to obtain the
  System's memory allocation granularity.
    dwNumberOfBytesToMap - Specifies the number of bytes of the file
  To map. If dwNumberOfBytesToMap is zero, the entire file is mapped.
    BaseAddr - Points to the memory address in the calling process's
  Address space where mapping should begin. This must be a multiple
  Of the system's memory allocation granularity, or the function
  Fails. Use the GetSystemInfo function, which fills in the members
  Of a SYSTEM _ INFO structure, to obtain the system's memory
  Allocation granularity. If there is not enough address space
  At the specified address, the function fails. If lpBaseAddress
  Is NULL, the operating system chooses the mapping address.

    Return Values - If the function succeeds, the return value
  is the starting address of the mapped view. If the function
  fails, the return value is NIL.

    Remarks - Mapping a file makes the specified portion of the file
  Visible in the address space of the calling process. If a suggested
  Mapping address is supplied, the file is mapped at the specified
  Address (rounded down to the nearest 64K boundary) if there is
  Enough address space at the specified address. If there is not,
  The function fails. Typically, the suggested address is used
  To specify that a file should be mapped at the same address
  In multiple processes. This requires the region of address space
  To be available in all involved processes. No other memory
  Allocation, including use of the VirtualAlloc function to reserve
  Memory, can take place in the region used for mapping.
  (Windows 95: If the BaseAddr parameter specifies a base offset,
  The function succeeds only if the same memory region is available
  For the memory mapped file in all other 32-bit processes.)
  (Windows NT: If the BaseAddr parameter specifies a base offset,
  The function succeeds if the given memory region is not already
  In use by the calling process. The system does not guarantee
  That the same memory region is available for the memory mapped
  File in other 32-bit processes.)
  Multiple views of a file (or a file-mapping object and its mapped
  File) are said to be " coherent " if they contain identical data at
  A specified time. This occurs if the file views are derived from
  The same file-mapping object. A process can duplicate a
  File-mapping object handle into another process by using the
  DuplicateHandle function, or another process can open
  A file-mapping object by name by using the OpenMMF function.
  A mapped view of a file is not guaranteed to be coherent
  With a file being accessed by the ReadFile or WriteFile function.

  Procedure FlushViewMMF (Base: pointer; dwNumberOfBytesToFlush: DWORD); virtual;
    This procedure writes to the disk a byte range within a mapped
  View of a file.
    Arguments:
    Base: pointer - Points to the base address of the byte range
  To be flushed to the disk representation of the mapped file.
    DwNumberOfBytesToFlush: DWORD - Specifies the number of bytes
  To flush. If dwNumberOfBytesToFlush is zero, the file is
  Flushed from the base address to the end of the mapping.

    Remarks - Flushing a range of a mapped view causes any
  Dirty pages within that range to be written to the disk.
  Dirty pages are those whose contents have changed since the
  File view was mapped.

  Procedure UnMapViewMMF (Base: pointer); virtual;
    This procedure unmaps a mapped view of a file from the calling
  Process's address space.
    Arguments:
    Base: pointer - Points to the base address of the mapped view
  Of a file that is to be unmapped. This value must be identical
  To the value returned by a previous call to the
  MapViewMMF method.
    Remarks - Although an application may close the file handle
  Used to create a file mapping object, the system holds the
  Corresponding file open until the last view of the file is
  Unmapped.
  (Windows 95: Files for which the last view has not yet been
  Unmapped are held open with the same sharing restrictions as
  The original file handle.)
  (Windows NT: Files for which the last view has not yet
  Been unmapped are held open with no sharing restrictions.)

  Procedure UnMapAllViews; virtual;
    This procedure unmaps all views of a file for this component.


  III. Component TasaMMF.
  =========================
    This component give to you full design-time and run-time control on
  process creating or opening memory mapped file by using properties or
  component editor. 

  1. Description.
  ---------------
    The component TasaMMF is the successor of a component TasaMMF_API
  and also adds some methods and properties. If TasaMMF_API
  is intended for more flexible and various access to API
  for file-mapping objects (for example simultaneously
  mapping a few views of one file), TasaMMF is intended for
  more convenient and simple access to file-mapping object.
  (All settings of the components are accessible from the property
  editors or component editor for TasaMMF.
  Using TasaMMF, it is impossible simultaneously to have, opened,
  some views (actually are possible, only for it, it is necessary
  to work as handles). But at the expense of it is reached
  simplicity in setting also there is no necessity for
  hand-operated coding.
    Main, that is added is an object of synchronization, for
  simplifications of use in the multiline appendices and in
  different processes.

  2. Properties.
  --------------

  Run-time
    Property Data: pointer; read-only property
      The pointer on memory, received as a result of maps a view,
    file-mapping object on address space, of calling process.
    If the object closed - that of nil.

    Property ReadOnly: Boolean; read-only property
      If file-mapping object and its map view created
    with attributes forbidding record to the address, specified in,
    Data, then ReadOnly = True. If the record is possible,
    ReadOnly = False.

    Property MMFState: TMMFStateSet; read-only property
      Inherited property. The description see is higher.

  Design-time and run-time
    Property Active: Boolean;
      Shows are opened whether or not in the given moment
    file-mapping object and its map view.
      The object can be opened, by establishing meaning in True and
    To close, by establishing meaning in False.

    Property BaseAddress: String;
      Points to the memory address in the calling process's
    address space where mapping should begin. If nil, the operating
    system chooses the mapping address.
      If the address is specified, it must be a multiple of
    the system's memory allocation granularity.

    Property FileName: String;
      Inherited property. See description higher.

    Property MapName: String;
      Inherited property. See description higher.

    Property FileAccessOptions: TFileAccessOptions;
      Inherited property. See description higher.

    Property FileCreateOption: TFileCreateOption;
      Inherited property. See description higher.

    Property FileAttributes: TFileAttributes;
      Inherited property. See description higher.

    Property MapProtectOption: TMapProtectOption;
      Inherited property. See description higher.

    Property MapOptions: TMapOptions;
      Inherited property. See description higher.

    Property MaxSizeLow: DWORD;
      Inherited property. See description higher.

    Property MaxSizeHigh: DWORD;
      Inherited property. See description higher.

    Property SynchroObject: String;
      The name of object, which you will use for synchronization
    of access. It should be identical for all objects TasaMMF,
    where you use them for access to the same file-mapping object.

    Property MapOffsetLow: DWORD;
      Specifies the low-order 32 bits of the file offset where
    mapping is to begin. The combination of the high and low
    offsets must specify an offset within the file that matches
    the system's memory allocation granularity, or the maping
    view fails. That is, the offset must be a multiple of the
    allocation granularity.

    Property MapOffsetHigh: DWORD;
      Specifies the high-order 32 bits of the file offset where
    mapping is to begin.

    Property MapSize: DWORD;
      Specifies the number of bytes of the file to map. If
    MapSize is zero, the entire file is mapped.

    Property MapViewOption: TMapViewOption;
      Specifies the type of access to the file-mapping object
    and, therefore, the page protection of the pages mapped by
    the file. (See TMapViewOption).

  3. Methods.
  -----------

  procedure   Open;
    Open file-mapping object and map view by given properties.

  procedure   Close;
    Close file-mapping object.

  function    GetRealMapSize: LongInt;
    Returns the real size of the map view  of memory.

  procedure   WaitForSynchroObject; virtual;
    The method returns when one of the following occurs:
      a) We wait while SynchroObject is busy and
         take ownership on SynchroObject.
      b) error occured.

  procedure   ReleaseSynchroObject; virtual;
     This method releases ownership of the SynchroObject.

  procedure   FreeSynchroObject; virtual;
    Release and close SynchroObject.

