1-Wire API for .NET Version 4.00
Public Member Functions | Protected Member Functions

OWFileDescriptor Class Reference

Instances of the 1-Wire file descriptor class serve as an opaque handle to the underlying machine-specific structure representing an open file, an open socket, or another source or sink of bytes. More...

List of all members.

Public Member Functions

 OWFileDescriptor ()
 Construct an invalid 1-Wire FileDescriptor.
boolean valid ()
 Tests if this file descriptor object is valid.
void sync () throws OWSyncFailedException
 Force all system buffers to synchronize with the underlying device.

Protected Member Functions

 OWFileDescriptor (OneWireContainer owd, String newPath)
 Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
 OWFileDescriptor (OneWireContainer[] owd, String newPath)
 Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
void setupFD (OneWireContainer[] owd, String newPath)
 Setups the 1-Wire FileDescrioptor providing the Filesystem 1-Wire device(s) and file path.
void open () throws OWFileNotFoundException
 Opens the file for reading.
void close () throws IOException
 Closes this file descriptor and releases any system resources associated with this stream.
void create (boolean append, boolean isDirectory, boolean makeParents, int startPage, int numberPages) throws OWFileNotFoundException
 Creates a directory or file to write.
void format () throws OneWireException, OneWireIOException
 Format the Filesystem on the 1-Wire device.
int read (byte b[], int off, int len) throws IOException
 Reads up to len bytes of data from this input stream into an array of bytes.
int read () throws IOException
 Reads a byte of data from this input stream.
long skip (long n) throws IOException
 Skips over and discards n bytes of data from the input stream.
int available () throws IOException
 Returns the number of bytes that can be read from this file input stream without blocking.
void write (int b) throws IOException
 Writes the specified byte to this file output stream.
void write (byte b[], int off, int len) throws IOException
 Writes len bytes from the specified byte array starting at offset off to this file output stream.
String getName ()
 Returns the name of the file or directory denoted by this abstract pathname.
String getParent ()
 Returns the pathname string of this abstract pathname's parent, or null if this pathname does not name a parent directory.
String getPath ()
 Converts this abstract pathname into a pathname string.
boolean exists ()
 Checks to see if the file exists.
boolean canRead ()
 Checks to see if can read the file associated with this descriptor.
boolean canWrite ()
 Checks to see if the file represented by this descriptor is writable.
boolean isDirectory ()
 Checks to see if this is a directory.
boolean isFile ()
 Checks to see if this is a file.
boolean isHidden ()
 Checks to see if this directory is hidden.
long length ()
 Get the estimated length of the file represented by this descriptor.
boolean delete ()
 Delete this file or directory represented by this descriptor.
String[] list ()
 Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.
boolean renameTo (OWFile dest)
 Renames the file denoted by this abstract pathname.
boolean setReadOnly ()
 Marks the file or directory named by this abstract pathname so that only read operations are allowed.
void mark (int readlimit)
 Mark the current position in the file being read for later reference.
void reset () throws IOException
 Reset the the read of this file back to the marked position.
void markPageUsed (int page) throws OneWireException
 Mark the specified page as used in the page bitmap.
boolean freePage (int page) throws OneWireException
 free the specified page as being un-used in the page bitmap
int getFirstFreePage (boolean counterPage) throws OneWireException
 Get the first free page from the page bitmap.
int getNextFreePage (boolean counterPage) throws OneWireException
 Get the next free page from the page bitmap.
int getFreeMemory () throws OneWireException
 Gets the number of bytes available on this device for file and directory information.
void writeBitMap () throws OneWireException
 Write the page bitmap back to the device.
void readBitMap () throws OneWireException
 Read the page bitmap.
int[] getPageList () throws OneWireException
 Get's an array of integers that represents the page list of the file or directory represented by this OWFile.
int getStartPage () throws IOException
 Returns an integer which represents the starting memory page of the file or directory represented by this OWFile.
PagedMemoryBank getMemoryBankForPage (int page)
 Get's the memory bank object for the specified page.
int getLocalPage (int page)
 Get's the local page number on the memory bank object for the specified page.
int verifyDeviceMap (int startPage, int numberOfContainers, boolean setOverdrive) throws OneWireException
 Verify the Device Map of a MASTER device is correct.
boolean createNewFile () throws IOException
 Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
int getHashCode ()
 Computes a hash code for this abstract pathname.
OneWireContainer[] getOneWireContainers ()
 Gets the OneWireContainers that represent this Filesystem.
void free ()
 Free's this file descriptors system resources.

Detailed Description

Instances of the 1-Wire file descriptor class serve as an opaque handle to the underlying machine-specific structure representing an open file, an open socket, or another source or sink of bytes.

The main practical use for a file descriptor is to create a OWFileInputStream or OWFileOutputStream to contain it.

Applications should not create their own file descriptors.

Author:
DS
Version:
0.01, 1 June 2001
See also:
com.dalsemi.onewire.application.file.OWFile
com.dalsemi.onewire.application.file.OWFileInputStream
com.dalsemi.onewire.application.file.OWFileOutputStream

Constructor & Destructor Documentation

Construct an invalid 1-Wire FileDescriptor.

OWFileDescriptor ( OneWireContainer  owd,
String  newPath 
) [protected]

Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.

Parameters:
owd- 1-Wire container where the filesystem resides
newPath- path containing the file/directory that represents this file descriptor
OWFileDescriptor ( OneWireContainer[]  owd,
String  newPath 
) [protected]

Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.

Parameters:
owd- 1-Wire container where the filesystem resides
newPath- path containing the file/directory that represents this file descriptor

Member Function Documentation

int available ( ) throws IOException [protected]

Returns the number of bytes that can be read from this file input stream without blocking.

Returns:
the number of bytes that can be read from this file input stream without blocking.
Exceptions:
IOExceptionif an I/O error occurs.
boolean canRead ( ) [protected]

Checks to see if can read the file associated with this descriptor.

Returns:
true if this file exists, false otherwise
boolean canWrite ( ) [protected]

Checks to see if the file represented by this descriptor is writable.

Returns:
true if this file exists and is not read only, false otherwise
void close ( ) throws IOException [protected]

Closes this file descriptor and releases any system resources associated with this stream.

Any cached writes are flushed into the filesystem. This file descriptor may no longer be used for writing bytes. If successfull (no exceptions) then the following class member variables will be set:

  • fePage - File Entry page number
  • feOffset - Offset into File Entry page
  • feData - buffer containing the last File Entry Page
  • feLen - length of packet in the last File Entry Page
  • feNumPages - Number of Pages specified in File Entry
  • feStartPage - Start Page specified in the File Entry
  • feParentPage - Parent page of current File Entry Page
  • feParentOffset - Offset into Parent page
  • lastPage - (file only) last page read
  • lastOffset - (file only) offset into last page read
  • lastLen - (file only) length of last page read
  • lastPageData - (file only) buffer for the last page read
  • filePosition - (file only) overall file position when reading
Exceptions:
IOExceptionif an I/O error occurs
void create ( boolean  append,
boolean  isDirectory,
boolean  makeParents,
int  startPage,
int  numberPages 
) throws OWFileNotFoundException [protected]

Creates a directory or file to write.

Parameters:
appendfor files only, true to append data to end of file, false to reset the file
isDirectorytrue if creating a directory, false for a file
makeParentstrue if creating all needed parent directories in order to create the file/directory
startPageNumstarting page of file/directory, -1 if not renaming
numberPagesnumber of pages in file/directory, -1 if not renaming
Exceptions:
FileNotFoundExceptionif file already opened to write, if makeParents=false and parent directories not found, if file is read only, or if there is an IO error reading filesystem
boolean createNewFile ( ) throws IOException [protected]

Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.

The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file.

Returns:
true if the named file does not exist and was successfully created; false if the named file already exists
Exceptions:
IOExceptionIf an I/O error occurred
boolean delete ( ) [protected]

Delete this file or directory represented by this descriptor.

Will fail if it is a read-only file or a non-empty directory.

Returns:
true if the file/directory was successfully deleted or false if not
boolean exists ( ) [protected]

Checks to see if the file exists.

Returns:
true if the file exists and false otherwise
void format ( ) throws OneWireException, OneWireIOException [protected]

Format the Filesystem on the 1-Wire device.

WARNING: all files/directories will be deleted in the process.

Exceptions:
OneWireExceptionwhen adapter is not setup properly
OneWireIOExceptionwhen an IO error occured reading the 1-Wire device
boolean freePage ( int  page) throws OneWireException [protected]

free the specified page as being un-used in the page bitmap

Parameters:
pagenumber to mark as un-used
Returns:
true if the page as be been marked as un-used, false if the page is on an OTP device and cannot be freed
Exceptions:
OneWireExceptionwhen an IO error occurs
int getFirstFreePage ( boolean  counterPage) throws OneWireException [protected]

Get the first free page from the page bitmap.

Parameters:
counterPage true if page needed is a 'counter' page (used in for monitary files)
Returns:
first page number that is free to write
Exceptions:
OneWireExceptionwhen an IO exception occurs
int getFreeMemory ( ) throws OneWireException [protected]

Gets the number of bytes available on this device for file and directory information.

Returns:
number of free bytes
Exceptions:
OneWireExceptionwhen an IO exception occurs
int getHashCode ( ) [protected]

Computes a hash code for this abstract pathname.

Because equality of abstract pathnames is inherently system-dependent, so is the computation of their hash codes. On UNIX systems, the hash code of an abstract pathname is equal to the exclusive or of its pathname string and the decimal value 1234321. On Win32 systems, the hash code is equal to the exclusive or of its pathname string, convered to lower case, and the decimal value 1234321.

Returns:
A hash code for this abstract pathname
int getLocalPage ( int  page) [protected]

Get's the local page number on the memory bank object for the specified page.

This is significant if the Filesystem spans memory banks on the same or different devices.

PagedMemoryBank getMemoryBankForPage ( int  page) [protected]

Get's the memory bank object for the specified page.

This is significant if the Filesystem spans memory banks on the same or different devices.

String getName ( ) [protected]

Returns the name of the file or directory denoted by this abstract pathname.

This is just the last name in the pathname's name sequence. If the pathname's name sequence is empty, then the empty string is returned.

Returns:
The name of the file or directory denoted by this abstract pathname, or the empty string if this pathname's name sequence is empty
int getNextFreePage ( boolean  counterPage) throws OneWireException [protected]

Get the next free page from the page bitmap.

Parameters:
counterPage true if page needed is a 'counter' page (used in for monitary files)
Returns:
next page number that is free to write
Exceptions:
OneWireExceptionwhen an IO exception occurs
OneWireContainer [] getOneWireContainers ( ) [protected]

Gets the OneWireContainers that represent this Filesystem.

Returns:
array of OneWireContainer's that represent this Filesystem.
int [] getPageList ( ) throws OneWireException [protected]

Get's an array of integers that represents the page list of the file or directory represented by this OWFile.

Exceptions:
OneWireExceptionif an I/O error occurs.
String getParent ( ) [protected]

Returns the pathname string of this abstract pathname's parent, or null if this pathname does not name a parent directory.

The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.

Returns:
The pathname string of the parent directory named by this abstract pathname, or null if this pathname does not name a parent
String getPath ( ) [protected]

Converts this abstract pathname into a pathname string.

The resulting string uses the default name-separator character to separate the names in the name sequence.

Returns:
The string form of this abstract pathname
int getStartPage ( ) throws IOException [protected]

Returns an integer which represents the starting memory page of the file or directory represented by this OWFile.

Returns:
The starting page of the file or directory.
Exceptions:
IOExceptionif the file doesn't exist
boolean isDirectory ( ) [protected]

Checks to see if this is a directory.

Returns:
true if this file exists and it is a directory, false otherwise
boolean isFile ( ) [protected]

Checks to see if this is a file.

Returns:
true if this file exists and is a file, false otherwise
boolean isHidden ( ) [protected]

Checks to see if this directory is hidden.

Returns:
true if this is a directory and is marked as hidden, false otherwise
long length ( ) [protected]

Get the estimated length of the file represented by this descriptor.

This is calculated by looking at how may pages the file is using so is not a very accurate measure.

Returns:
estimated length of file in bytes
String [] list ( ) [protected]

Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.

If this abstract pathname does not denote a directory, then this method returns null. Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

Returns:
An array of strings naming the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory, or if an I/O error occurs.
void mark ( int  readlimit) [protected]

Mark the current position in the file being read for later reference.

Parameters:
readlimitlimit to keep track of the current position
void markPageUsed ( int  page) throws OneWireException [protected]

Mark the specified page as used in the page bitmap.

Parameters:
pagenumber to mark as used
Exceptions:
OneWireExceptionwhen an IO exception occurs
void open ( ) throws OWFileNotFoundException [protected]

Opens the file for reading.

If successfull (no exceptions) then the following class member variables will be set:

  • fePage - File Entry page number
  • feOffset - Offset into File Entry page
  • feData - buffer containing the last File Entry Page
  • feLen - length of packet in the last File Entry Page
  • feNumPages - Number of Pages specified in File Entry
  • feStartPage - Start Page specified in the File Entry
  • feParentPage - Parent page of current File Entry Page
  • feParentOffset - Offset into Parent page
  • lastPage - (file only) last page read
  • lastOffset - (file only) offset into last page read
  • lastLen - (file only) length of last page read
  • lastPageData - (file only) buffer for the last page read
  • filePosition - (file only) overall file position when reading
Exceptions:
FileNotFoundExceptionwhen the file/directory path is invalid or there was an IOException thrown when trying to read the device.
int read ( byte  b[],
int  off,
int  len 
) throws IOException [protected]

Reads up to len bytes of data from this input stream into an array of bytes.

This method blocks until some input is available.

Parameters:
bthe buffer into which the data is read.
offthe start offset of the data.
lenthe maximum number of bytes read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Exceptions:
IOExceptionif an I/O error occurs.
int read ( ) throws IOException [protected]

Reads a byte of data from this input stream.

This method blocks if no input is yet available.

Returns:
the next byte of data, or -1 if the end of the file is reached.
Exceptions:
IOExceptionif an I/O error occurs.
void readBitMap ( ) throws OneWireException [protected]

Read the page bitmap.

Exceptions:
OneWireExceptionwhen an IO error occurs
boolean renameTo ( OWFile  dest) [protected]

Renames the file denoted by this abstract pathname.

Parameters:
destThe new abstract pathname for the named file
Returns:
true if and only if the renaming succeeded; false otherwise
Exceptions:
NullPointerExceptionIf parameter dest is null
void reset ( ) throws IOException [protected]

Reset the the read of this file back to the marked position.

Exceptions:
IOExceptionwhen a read error occurs
boolean setReadOnly ( ) [protected]

Marks the file or directory named by this abstract pathname so that only read operations are allowed.

After invoking this method the file or directory is guaranteed not to change until it is either deleted or marked to allow write access. Whether or not a read-only file or directory may be deleted depends upon the underlying system.

Returns:
true if and only if the operation succeeded; false otherwise
void setupFD ( OneWireContainer[]  owd,
String  newPath 
) [protected]

Setups the 1-Wire FileDescrioptor providing the Filesystem 1-Wire device(s) and file path.

Parameters:
owd- 1-Wire container where the filesystem resides
newPath- path containing the file/directory that represents this file descriptor
long skip ( long  n) throws IOException [protected]

Skips over and discards n bytes of data from the input stream.

The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned.

Parameters:
nthe number of bytes to be skipped.
Returns:
the actual number of bytes skipped.
Exceptions:
IOExceptionif an I/O error occurs.
void sync ( ) throws OWSyncFailedException

Force all system buffers to synchronize with the underlying device.

This method returns after all modified data and attributes of this FileDescriptor have been written to the relevant device(s). In particular, if this FileDescriptor refers to a physical storage medium, such as a file in a file system, sync will not return until all in-memory modified copies of buffers associated with this FileDesecriptor have been written to the physical medium.

sync is meant to be used by code that requires physical storage (such as a file) to be in a known state For example, a class that provided a simple transaction facility might use sync to ensure that all changes to a file caused by a given transaction were recorded on a storage medium.

sync only affects buffers downstream of this FileDescriptor. If any in-memory buffering is being done by the application (for example, by a BufferedOutputStream object), those buffers must be flushed into the OWFileDescriptor (for example, by invoking OutputStream.flush) before that data will be affected by sync.

This method may be called multiple times if the source of OWSyncFailedException has been rectified (1-Wire device was reattached to the network).

Exceptions:
OWSyncFailedExceptionThrown when the buffers cannot be flushed, or because the system cannot guarantee that all the buffers have been synchronized with physical media.
boolean valid ( )

Tests if this file descriptor object is valid.

Returns:
true if the file descriptor object represents a valid, open file, socket, or other active I/O connection; false otherwise.
int verifyDeviceMap ( int  startPage,
int  numberOfContainers,
boolean  setOverdrive 
) throws OneWireException [protected]

Verify the Device Map of a MASTER device is correct.

Parameters:
pagestarting page number of the device map file
numberOfContainersto re-create the OneWireContainer array in the instance variable from the devices listed in the device map 'owd[]'. Zero indicates leave the list alone. >0 means recreate the array keeping the same MASTER device.
setOverdrive true if set new containers to do a max speed of overdrive if possible
Returns:
the number of devices in the device map if the current device list is INVALID and returns zero if the current device list is VALID.
Exceptions:
OneWireExceptionwhen an IO error occurs
void write ( int  b) throws IOException [protected]

Writes the specified byte to this file output stream.

Implements the write method of OutputStream.

Parameters:
bthe byte to be written.
Exceptions:
IOExceptionif an I/O error occurs.
void write ( byte  b[],
int  off,
int  len 
) throws IOException [protected]

Writes len bytes from the specified byte array starting at offset off to this file output stream.

Parameters:
bthe data.
offthe start offset in the data.
lenthe number of bytes to write.
Exceptions:
IOExceptionif an I/O error occurs.
void writeBitMap ( ) throws OneWireException [protected]

Write the page bitmap back to the device.

Exceptions:
OneWireExceptionwhen an IO error occurs

The documentation for this class was generated from the following file: