1. files_1_wire_drivers_v400.zip Driver
2. COMOWAPI.txt File Contents

COMOWAPI.txt Driver File Contents (files_1_wire_drivers_v400.zip)

COM/OWAPI
A OneWireAPI Interface Library Implemented
Using Microsoft's Component Object Model

Release 4.00 beta 4


Preface
-------

This is a release of a Component Object Model (COM) solution for
developing 1-Wire applications.  The dll provided with this release
contains binary interfaces, compatible with almost any programming language
that works on a Microsoft Window's operating system.  The underlying
implementation of each interface is a Java class, which utilizes our
current Java OneWireAPI.  This makes our richest collection of support
classes for Dallas Semiconductor's 1-Wire devices available to a variety of
programming environments including C++, VisualBasic, JavaScript, JScript,
Perl, and VBScript.

This release should be considered pre-alpha, as a lot of compromises were
made to get the existing Java codebase to work in a COM interface.  These
compromises are outlined in the next section.


Documentation
-------------

Since the underlying structure of all the interfaces is actually
implemented using the Java OneWireAPI, the documentation is the same.
There are just a few rules of thumb for applying the Java documentation to
a COM interface.

1) Java uses 64-bit longs and the interfaces we used in COM don't support a
number larger than 32-bits.  For any function in Java that takes a long as
a parameter or returns a long, a string is used.  In loosely-typed
programming languages (like VisualBasic or JavaScript), the conversion
between long and string will be automatic and probably won't affect your
code in any way.  For all other languages, special care must be taken that
parameters are converted to strings and return values are converted to
64-bit longs.

2) Several of the classes in the OneWireAPI use an array of bytes for
caching state information about an object.  Unfortunately, languages that
don't allow for passing values by reference (like JavaScript) actually
cloned the data in the array for passing as a parameter.  Since this breaks
the functionality we expect from passing array values as parameters, an
object was created for containing arrays of bytes.  The object, ByteArray,
is the only object whose equivalent doesn't exist in the current Java
OneWire API and, as such, the necessary documentation is produced below:

  ByteArray
  {
    // sets the item at the given index with the given value
    void setAt(nIndex,nValue);

    // returns the numerical value at the given index
    nValue getAt(nIndex);

    // grows or shrinks the size of the array, copies all data that fits
    void setSize(nSize);

    // returns the size of the array
    nSize getSize();
  }


3) In Java, method overloading allows for methods to differ in types of
their parameters as well as in the number of parameters.  In COM, only the
number of parameters can distinguish two methods with the same name.  All
the methods that would conflict with this requirement fit into the same
pattern.  They were either expecting a string, a long, or an array of
bytes. The method that expects a string was left alone while the method
expecting a long has a new name with "FromLong" on the end.  The method
expecting an array of bytes has "FromBytes" added on the end. For example:

  Java                    COM
  isPresent(String)  -->  isPresent(String)
  isPresent(long)    -->  isPresentFromLong(String) //By rule #1 and #3
  isPresent(byte[])  -->  isPresentFromBytes(ByteArray) //By rule #2 and #3

4) Some containers in the Java OneWireAPI depend on polymorphism for their
functionality. Polymorphism is, essentially, the ability of a class to be
treated as if it was actually an instance of a parent class.  In COM,
polymorphism doesn't manifest itself in quite the same way since COM
doesn't support inheritance.  Each COM component in our architecture
represents an actual instance of an object from our OneWireAPI, but usually
a higher-level component (like MemoryBank) will actually contain an
instance of a lower-level object (like PagedMemoryBank or OTPMemoryBank).
In Java, you would simply cast the object to it's specific type.
Unfortunately, it's not that easy in COM...  So a helper method was added
to three top-level containers:  OneWireContainer, MemoryBank, and
DSPortAdapter.  The interface for the helper method is simple:

  Component getMostSpecificComponent();

The return value depends on which class you are calling it on, but if you
have an instance of OneWireContainer that is actually holding a thermochron
object (OneWireContainer21), you can be sure that calling
getMostSpecificComponent will return an instance of the OneWireContainer21
COM interface.

5) Another feature that is lost with polymorphism is the mechanism by which
you discover whether or not a particular 1-Wire device supported a
particular interface.  Polymorphism also allows a class to be treated as if
it was actually an instance of an interface that the class implements.
OneWireContainer21, for example, implements the interface
TemperatureContainer.  That is to say, OneWireContainer21 implements all
methods that are common among TemperatureContainers (like
"readTemperature").  In Java, it is common to compare an instance of a one
wire object with a particular interface using the "instanceof" keyword.  If
the "myOneWireDevice instanceof TemperatureContainer" statement returned
true, you know that you're device implements all the methods necessary for
reading temperatures.  The solution in COM is to use these methods defined
in all OneWireContainers:

  boolean isTemperatureContainer();
  boolean isADContainer();
  boolean isSwitchContainer();
  boolean isClockContainer();
  boolean isPotentiometerContainer();

6) Functions in Java that used to return the java.util.Calendar object now
return the current time in milliseconds since Jan 1, 1970 GMT.  This is the
unix standard for representing time.

What's Missing
--------------

The only constructs missing from the Java OneWireAPI are the event
interfaces.  This release of COM/OWAPI will not have support for 1-Wire
network/monitor events. This may be added in future releases.

Supported Interfaces
--------------------

The complete lists of supported interfaces, and their associated ClassIDs 
are available in the JavDocs (html files located in the /docs folder).

Installation
------------

1) Copy the owapi.dll onto your hard drive.
2) Type:
        regsvr32 /s <path to dll>
3) Unzip the class files into your <windows>\Java\trustlib folder.


Uninstallation
--------------
1) Type:
        regsvr32 /s /u <path to dll>
2) Delete the owapi.dll.
3) Delete the com.dalsemi.onewire.* class files from your
<windows>\Java\trustlib folder.


Appendix A - Dealing with Unix Time in VisualBasic
--------------------------------------------------

All of the Java methods dealing with time, such as the methods in the
ClockContainer interface implemented by OneWireContainer21, all return time
values and expect time values represented in the Unix standard.  That is to
say each time value is actually a long value representing the number of
milliseconds that have passed since midnight on Jan 1, 1970 in greenwich
mean time.  VisualBasic uses a completely different scheme, so this
appendix is here to provide a few helper functions for VB users.  The
function VBDateToUnixTime takes a valid VB date value as a parameter and
returns a string which represents the unix time value.  This parameter must
be treated as a string because it's value is too large a number for VB to
handle directly.  The function UnixTimeToVBDate takes a unix time value and
returns a valid VB date value.  Note that these functions do not maintain
"millisecond" accuracy.

''''''''''''''''''''''''''
' Necessary declarations
''''''''''''''''''''''''''
Private Type SYSTEMTIME
   wYear         As Integer
   wMonth        As Integer
   wDayOfWeek    As Integer
   wDay          As Integer
   wHour         As Integer
   wMinute       As Integer
   wSecond       As Integer
   wMilliseconds As Integer
End Type

Private Type TIME_ZONE_INFORMATION
   Bias As Long
   StandardName(0 To ((32 * 2) - 1)) As Byte
   StandardDate As SYSTEMTIME
   StandardBias As Long
   DaylightName(0 To ((32 * 2) - 1)) As Byte
   DaylightDate As SYSTEMTIME
   DaylightBias As Long
End Type

Private Declare Function GetTimeZoneInformation Lib "kernel32" _
    (lpTimeZoneInformation As TIME_ZONE_INFORMATION) As Long

''''''''''''''''''''''''''
' Helper functions
''''''''''''''''''''''''''
'Convert the current time in milliseconds to a VB Date format
Private Function UnixTimeToVBDate(UnixTime As String) As Date
    Dim Seconds As Long
    Seconds = Left(UnixTime, Len(UnixTime) - 3)
    UnixTimeToVBDate = DateAdd("s", Seconds, GetBeginningOfTime())
End Function

'Convert the current time to the number of milliseconds since
' Jan 1, 1970 00:00:00 GMT
Private Function VBDateToUnixTime(vbDate As Date) As String
    Dim UnixTime As String
    UnixTime = DateDiff("s", GetBeginningOfTime(), vbDate)
    VBDateToUnixTime = UnixTime & "000"
End Function

'This function returns the Unix standard beginning of time
'  Jan 1, 1970 00:00:00 GMT
'But adjusted to your timezone.
Private Function GetBeginningOfTime()
    Dim tz As TIME_ZONE_INFORMATION

    Select Case GetTimeZoneInformation(tz)
        Case 0:
            'Unknown, Go ahead and send GMT
            GetBeginningOfTime = #1/1/1970#
        Case 1:
            'Standard time
            GetBeginningOfTime = DateAdd("n", _
                        -(tz.Bias + tz.StandardBias), #1/1/1970#)
        Case 2:
            'Daylight Saving time
            GetBeginningOfTime = DateAdd("n", _
                        -(tz.Bias + tz.DaylightBias), #1/1/1970#)
    End Select
End Function