Cross Point


IMemoryAccess Interface Reference

Inheritance diagram for IMemoryAccess:

IEventBase List of all members.

Detailed Description

This interface handles all memory related functionality.

The most important functionality that is supported by this interface is the UploadFirmware method. This method can be used to upload a new operating system and/or application into the reader.

The uploading process can never be canceled since that would leave an incomplete OS or Application in the reader, making the reader inaccesable!.

When performing the upload operation asynchronously, the status of the current upload process can be determined using the IsUploading property.

Another method of this object is the IsSystemAreaChecksumOk property which can check if the system area of this reader is valid. If it is not valid, this reader might be a potential source of errors.


Public Member Functions

HRESULT Reader ([out, retval] IProximityReader **ppintfReader)
 Returns the reader this memoryaccess object belongs to.

HRESULT UploadFirmware ([in] BSTR OSFilename,[in] BSTR ApplicationFilename,[in] EFlashArea eFlashArea,[in, defaultvalue(1)] VARIANT_BOOL UploadAsync,[in, defaultvalue(100)] long lMaxNumberOfSteps)
 This function loads new firmware into the Flash memory of this reader.

HRESULT IsUploading ([out, retval] ECollectingStatus *peStatus)
 Returns the status of this reader's uploading process.

HRESULT ReadMemory ([in] EMemoryType MemoryType,[in] long Address,[in] short NumberOfBytesToRead,[out, retval] VARIANT *pvtMemoryBlock)
 Read a block of memory from the EEPROM or Flash memory.

HRESULT WriteMemory ([in] EMemoryType MemoryType,[in] long Address,[in] VARIANT *Data,[in, defaultvalue(0)] VARIANT_BOOL WriteAsync,[out, retval] VARIANT_BOOL *pfSucceeded)
 Write a block of memory to the EEPROM, Flash or Processor memory.

HRESULT VerifyFlashMemory ([in] EFlashArea FlashArea,[out, retval] VARIANT_BOOL *pfAreaOk)
 Verify the flash memory.

HRESULT IsSystemAreaChecksumOk ([out, retval] VARIANT_BOOL *pfSystemAreaOk)
 Returns true if the system area checksum is valid.


Member Function Documentation

IMemoryAccess::Reader [out, retval] IProximityReader **  ppintfReader  ) 
 

Returns the reader this memoryaccess object belongs to.

Parameters:
ppintfReader Receives the reader object.
Precondition:
ppintfReader is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
IProximityReader

IMemoryAccess::UploadFirmware [in] BSTR  bstrOSFilename,
[in] BSTR  bstrApplicationFilename,
[in] EFlashArea  eFlashArea,
[in, defaultvalue(1)] VARIANT_BOOL  fUploadAsync,
[in, defaultvalue(100)] long  lMaxNumberOfSteps
 

This function loads new firmware into the Flash memory of this reader.

Use this method to upload a new OS, or Application (or both) into this reader. Since the uploading of new firmware can only be done if the reader is currently in bootloader mode the UploadFirmware method will first make sure the reader is in bootloader mode by resetting it (if it is not already in bootloader mode). It will then start by erasing the flash area where the new firmware should be stored. The next step will be to upload the new firmware. When the uploading process has finished, the reader is reset to activate the new firmware using the IProximityReader::Reset method.

This method is capable of uploading a separate OS and/or Application firmware but also capable of uploading a single firmware file (combined OS and application into a single file).

When both OS and Application should be uploaded, the following steps are performed:

  1. Make sure that the reader is in bootloader mode (if not in bootloader, reset the reader to bootloader mode).
  2. Erase the flash memory OS area.
  3. Upload the OS firmware.
  4. Erase the flash memory Application area.
  5. Upload the Application firmware.

Steps 2 and 3 will be skipped if no OS needs to be flashed, 4 and 5 will be skipped if no Application needs to flashed. When uploading a single firmware file, first step 1 is performed, then both the OS and Application flash areas are erased, next the entire firmware file is uploaded at once.

This method fires the default events of processtype ptUploadingFirmware. During this process a number of sub processes types are executed: /li Step 1 will generate the sptResetting sub process if the reader is in application mode, if the reader is already in bootloader mode, step 1 will be skipped. See IProximityReader::Reset for more information about the events fired during resetting. /li The erasing of the flash areas will generate sptErasingFirmware sub process events. Progress events are also generated during the erasing of the flash area. /li Uploading of the OS and/or the Application generates progress events. Note that both the OS and Application will generate progress events ranging from 0 to 100%. To determine what kind of image is being uploaded, an event sub process started is fired when the OS starts and stops uploading (sptUploadingOS) and one(sptUploadingCPA) when the Application starts and stops uploading. Note that this is only implemented to facility the uploading of old (separate OS and CPA) firmware. /li Uploading a single firmware file will generate only the normal progress events.

After the upload process has finished, the reader should be reset to activate the new firmware. Use the IProximityReader::Reset method to do this.

When executing the upload process asynchronously, the current state of the upload operation can be determined using the IsUploading property.

The contents of the new firmware file must be conform the Intel Hexadecimal Object Format Specification.

Parameters:
bstrOSFilename The OS hex file to upload (if empty, no OS will be uploaded). When uploading a single firmware file, pass the filename using this parameter.
bstrApplicationFilename The Application hex file to upload (if empty, no Application will be uploaded).
eFlashArea Specify what areas should be uploaded (can be or-ed together). To upload a single firmware file, set this to faFirmware.
fUploadAsync When set to false, this method will not return until the uploading process is finished.
lMaxNumberOfSteps Maximum number of progress events that will be generated (default = 100 steps).
Warning:
The flash memory of the reader is only guaranteed for 20 erase/program cycles. An error return code may indicate that the flash memory has become 'exhausted'.
See also:
IsUploading, IProximityReader::Reset

EFlashArea

IMemoryAccess::IsUploading [out, retval] ECollectingStatus peStatus  ) 
 

Returns the status of this reader's uploading process.

Parameters:
peStatus Receives the status of the uploading process.
Precondition:
peStatus is not NULL.
See also:
UploadFirmware

IMemoryAccess::ReadMemory [in] EMemoryType  eMemoryType,
[in] long  lAddress,
[in] short  sReadCount,
[out, retval] VARIANT *  pvtMemoryBlock
 

Read a block of memory from the EEPROM or Flash memory.

Parameters:
eMemoryType The memory type where the data should be read from.
lAddress The 16 bit startaddress to read from.
sReadCount Number of bytes to read.
pvtMemoryBlock Receives a block of bytes (in an array).
Precondition:
pvtMemoryBlock is not NULL.
Note:
Required authorization level: Installer.

IMemoryAccess::WriteMemory [in] EMemoryType  eMemoryType,
[in] long  lAddress,
[in] VARIANT *  pvtData,
[in, defaultvalue(0)] VARIANT_BOOL  fWriteAsync,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Write a block of memory to the EEPROM, Flash or Processor memory.

The default events of process type ptWritingMemory are generated by this method. This method however, will not fire progress events (since only small amounts of data will be generated, any delay will be neglegible small).

Parameters:
eMemoryType The memory type where the data should be written to.
lAddress The 16 bit startaddress to write to.
pvtData The data that should be written (in an array).
fWriteAsync When set to true, the write operation will be performed asynchronously.
pfSucceeded Set to true upon a successful write operation (only when the write operation is performed synchronously).
Note:
Required authorization level: Installer.
Warning:
Use this method with extreme care (or do not use at all), since writing wrong data to the wrong address might render your reader completly unusable! Maybe that uploading new firmware may work, but it is likely that your reader is damaged beyond repair!

IMemoryAccess::VerifyFlashMemory [in] EFlashArea  eFlashArea,
[out, retval] VARIANT_BOOL *  pfAreaOk
 

Verify the flash memory.

Parameters:
eFlashArea The flash area that will be verified.
pfAreaOk Set to true if the area is verified successfully.
Precondition:
pfAreaOk is not null.
Note:
Only available in bootloader mode.

IMemoryAccess::IsSystemAreaChecksumOk [out, retval] VARIANT_BOOL *  pfSystemAreaOk  ) 
 

Returns true if the system area checksum is valid.

Parameters:
pfSystemAreaOk Receives the state of the checksum of the system area (true if ok).
Precondition:
pfSystemAreaOk is not null.


© Copyright 2001 - 2006 Cross Point. Generated on Mon Mar 12 16:29:51 2007 Cross Point