/*--------------------------------------------------------------------------- * Copyright (C) 1999,2000 Dallas Semiconductor Corporation, All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included * in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR * OTHER DEALINGS IN THE SOFTWARE. * * Except as contained in this notice, the name of Dallas Semiconductor * shall not be used except as stated in the Dallas Semiconductor * Branding Policy. *--------------------------------------------------------------------------- */ package com.dalsemi.onewire.container; // imports import com.dalsemi.onewire.OneWireException; import com.dalsemi.onewire.adapter.OneWireIOException; /** * Memory bank interface class for basic memory communication with * iButtons (or 1-Wire devices). This class should be implemented * for each memory bank type. * * @version 0.00, 28 Aug 2000 * @author DS */ public interface MemoryBank { //-------- //-------- Memory Bank Feature methods //-------- /** * Query to see get a string description of the current memory bank. * * @return String containing the memory bank description */ public String getBankDescription (); /** * Query to see if the current memory bank is general purpose * user memory. If it is NOT then it is Memory-Mapped and writing * values to this memory will affect the behavior of the 1-Wire * device. * * @return 'true' if current memory bank is general purpose */ public boolean isGeneralPurposeMemory (); /** * Query to get the size of the memory bank in bytes. * * @return number of bytes in current memory bank */ public int getSize (); /** * Query to see if current memory bank is read/write. * * @return 'true' if current memory bank is read/write */ public boolean isReadWrite (); /** * Query to see if current memory bank is write write once such * as with EPROM technology. * * @return 'true' if current memory bank can only be written once */ public boolean isWriteOnce (); /** * Query to see if current memory bank is read only. * * @return 'true' if current memory bank can only be read */ public boolean isReadOnly (); /** * Query to see if current memory bank non-volatile. Memory is * non-volatile if it retains its contents even when removed from * the 1-Wire network. * * @return 'true' if current memory bank non volatile. */ public boolean isNonVolatile (); /** * Query to see if current memory bank pages need the adapter to * have a 'ProgramPulse' in order to write to the memory. * * @return 'true' if writing to the current memory bank pages * requires a 'ProgramPulse'. */ public boolean needsProgramPulse (); /** * Query to see if current memory bank pages need the adapter to * have a 'PowerDelivery' feature in order to write to the memory. * * @return 'true' if writing to the current memory bank pages * requires 'PowerDelivery'. */ public boolean needsPowerDelivery (); /** * Query to get the starting physical address of this bank. Physical * banks are sometimes sub-divided into logical banks due to changes * in attributes. * * @return physical starting address of this logical bank. */ public int getStartPhysicalAddress (); /** * Set the write verification for the 'write()' method. * * @param doReadVerf true (default) verify write in 'write' * false, don't verify write (used on * Write-Once bit manipulation) */ public void setWriteVerification (boolean doReadVerf); //-------- //-------- I/O methods //-------- /** * Read memory in the current bank with no CRC checking (device or * data). The resulting data from this API may or may not be what is on * the 1-Wire device. It is recommends that the data contain some kind * of checking (CRC) like in the readPagePacket() method or have * the 1-Wire device provide the CRC as in readPageCRC(). readPageCRC() * however is not supported on all memory types, see 'hasPageAutoCRC()'. * If neither is an option then this method could be called more * then once to at least verify that the same thing is read consistantly. * * @param startAddr starting address * @param readContinue if 'true' then device read is continued without * re-selecting. This can only be used if the new * read() continious where the last one led off * and it is inside a 'beginExclusive/endExclusive' * block. * @param readBuf byte array to place read data into * @param offset offset into readBuf to place data * @param len length in bytes to read * * @throws OneWireIOException * @throws OneWireException */ public void read (int startAddr, boolean readContinue, byte[] readBuf, int offset, int len) throws OneWireIOException, OneWireException; /** * Write memory in the current bank. It is recommended that * when writing data that some structure in the data is created * to provide error free reading back with read(). Or the * method 'writePagePacket()' could be used which automatically * wraps the data in a length and CRC. * * When using on Write-Once devices care must be taken to write into * into empty space. If write() is used to write over an unlocked * page on a Write-Once device it will fail. If write verification * is turned off with the method 'setWriteVerification(false)' then * the result will be an 'AND' of the existing data and the new data. * * @param startAddr starting address * @param writeBuf byte array containing data to write * @param offset offset into writeBuf to get data * @param len length in bytes to write * * @throws OneWireIOException * @throws OneWireException */ public void write (int startAddr, byte[] writeBuf, int offset, int len) throws OneWireIOException, OneWireException; }