Aminet 18/aminetcdnumber181997.iso/Aminet/util/libs/DigNet_1_0.lha/dignet/docs/dignet.doc

Text File | 1997-02-25 | 10.8 KB | 428 lines

TABLE OF CONTENTS

dignet.library/---background---
dignet.library/---notes---
dignet.library/AbortNet
dignet.library/AllocNet
dignet.library/FreeNet
dignet.library/InitIOEXT
dignet.library/QueryNet
dignet.library/ReadIOEXT
dignet.library/ReadNet
dignet.library/Timeout
dignet.library/WriteNet


dignet.library/---background---               dignet.library/---background---


  We developed this library to ease the pain when writing serial
  network dependent programs. It's always a husle when setting up
  structure for this and that and allocate memory, init the device and
  so on. We developed this library to do the dirty work for us.
  It's straight forward to use and it does simple operations that
  covers our need. Since this library is freeware we will not implement
  "deeper" stuff such as signaling, async transfers and so on. We will
  implement our own protocol in a future version though.

  If you're gonna communicate with another machine you just allocate
  the serial.device or a compatible device, send your data from one
  side, receive them on the other. And that's all you have to do.

  You are free to implement the library as a stand-alone file in your
  archives. You should however give the file credit in your program
  visable for the user. It should say something like:

    Using dignet.library by Kenneth "Kenny" Nilsen of
    Digital Surface. Available from Aminet.

  That's all we require. If you don't want to add such a line in your
  program(s) you must include the whole library archive with all files
  as it came from Aminet.


  We don't take responsibillity if your hardware or software gets
  scrued up due to use of this library. You use it entirely at your
  own risk!


  You can mail us at:  [e-mail]
  Visit the homepage:  http://www.bgnett.no/~kenny/


dignet.library/---notes---                         dignet.library/---notes---


  The NET is described as a structure, but since it is a private
  structure it will be refered to as a APTR for the function call
  (for C programmers). You should however make sure it is on a word
  aligned address.

  To use the Read and Init IOEXT functions you must be sure that the
  IOEXT block of the device is at the same offset as the serial.device.
  For example, duart.device will work fine.

  When you write to a port you would make a small delay before you
  read the destination port since sometimes it doesn't seem like the
  datas is updated. Also, we would recommend you to transfer in small
  blocks or even just in bytes to make sure every data is transfered
  correctly. There will be implemented an own transfer protocol in a
  future release of this library.

  Do NOT call functions that are marked PRIVATE (see FD file). They
  WILL crash! You have been warned.

dignet.library/AbortNet                               dignet.library/AbortNet

NAME
    AbortNet -- aborts the device IO

SYNOPSIS

    error=AbortNet(net)
                   a0

    ULONG AbortNet(APTR);


FUNCTION
    This function will abort the iorequests at the device. All iorequests are
    stopped immediatly. Read the serial.doc for more information on how this
    works.

INPUTS
    net - ptr. to a valid net structure

RESULTS
    error - return null or an errorcode

NOTES

EXAMPLE

BUGS

SEE ALSO
    serial.doc

dignet.library/AllocNet                               dignet.library/AllocNet

NAME
    AllocNet -- Allocates a private structure to use with the other functions

SYNOPSIS

    netstruct=AllocNet(devicename,unit)
                       a1         d0

    APTR netstruct AllocNet(STRPTR,UWORD);


FUNCTION
    To use any of the functions in this library you need to allocate a net
    structure. This structure is private. The structure information needed
    for the other functions to know where and what to send/read. It also
    allocates memory to use with IOEXT, message structures and so on.
    Additional the device is flushed and aborted at startup to make a clean
    start for user. When this function returns true you are ready to use the
    device.

    The function will also init the device with the following defaults:

         baud  = 19200
         mode  = 7WIRE and XDISABLED
         read  = 8 bits
         write = 8 bits
         stop  = 1 bit
   r/w buffers = 2 kb

    To change this setting use the ReadIOEXT() and InitIOEXT().

INPUTS
    devicename - ptr. to the device name you want to open
    unit - unit number

RESULTS
    netstruct - ptr. to a private structure or NULL if any failure

NOTES
    NOTE: Devices returns NULL when succeeded. This library function will not
    reflect this result. It will return NULL only if a failure occured such
    as out of memory or the port couldn't be created or the device couldn't
    be opened. There is currently no way within the library to find the exact
    cause of the problem.

EXAMPLE

From C -
    Net=AllocNet("serial.device",0)

From Assembler -
    move.l    DignetBase,a6        ;library base in a6
    lea    DeviceName,a0        ;device name in a0
    moveq.l    #0,d0            ;unit number in d0
    jsr    _LVOAllocNet(a6)    ;call function
    move.l    d0,Net            ;store pointer
    beq    Error            ;if null go to error handling

BUGS
    Maybe an exact cause of an error should be implemented.

SEE ALSO
    FreeNet(), ReadIOEXT(), InitIOEXT()

dignet.library/FreeNet                                 dignet.library/FreeNet

NAME
    FreeNet -- Frees and cleanup the structure allocated with AllocNet()

SYNOPSIS

    FreeNet(net)
            a0

    void FreeNet(APTR);


FUNCTION
    This function will free the structure allocated with AllocNet(). It will
    also flush, abort, wait and close the device and then free memory
    allocated with AllocNet().

INPUTS
    net - ptr. to a valid net structure

EXAMPLE
    FreeNet(net)

BUGS

SEE ALSO
    AllocNet()


dignet.library/InitIOEXT                             dignet.library/InitIOEXT

NAME
    InitIOEXT -- Init the IOEXT structure of a device (serial/duart etc.)

SYNOPSIS

    error=InitIOEXT(net,newIOEXT,size)
                    a0  a1       d0

    ULONG InitIOEXT(APTR,APTR,ULONG);


FUNCTION
    This function will init the IOEXT and call the device function
    SetParameters. Only use this with devices that are compatible with the
    serial device (for example duart.device).

    Always use the ReadIOEXT() first to copy current settings of the device
    to your buffer. This way you only have to change some fields. If not you
    will have to setup the whole IOEXT struture.

INPUTS
    net - ptr. to a valid net structure
    newIOEXT - ptr. to new settings
    size - number of bytes to copy

RESULTS
    error - reflects the io_error field. Null if ok.

NOTES

EXAMPLE

BUGS

SEE ALSO
    ReadIOEXT()

dignet.library/QueryNet                               dignet.library/QueryNet

NAME
    QueryNet -- Query the device and return number of chars that are
                available for read.

SYNOPSIS

    chars=QueryNet(net)
                  a0

    ULONG QueryNet(APTR);


FUNCTION
    Use this function before you ReadNet() the device. This function will
    return number of bytes that are available to read. You can parse the
    result directly to ReadNet(). If zero bytes the ReadNet() will abort and
    return.

INPUTS
    net - ptr. to a valid net structure

RESULTS
    chars - number of chars available to read

NOTES

EXAMPLE

BUGS

SEE ALSO
    ReadNet()

dignet.library/ReadIOEXT                             dignet.library/ReadIOEXT

NAME
    ReadIOEXT -- Copies current settings in IOEXT to a buffer

SYNOPSIS

    ReadIOEXT(net,buffer,size)
               a0  a1     d0

    void ReadIOEXT(APTR,APTR,ULONG);


FUNCTION
    This function will copy current setting of the IOEXT structure used to
    for example to set baud rate in the serial device. The device has to be
    compatible with the serial device to read successfully. The reason for
    this is that it reads from an offset that is valid for the serial.device.
    If another device has its IOEXT structure at same offset this function
    and the InitIOEXT() function can be used. Remember to set number of
    bytes to copy.

INPUTS
    net - ptr. to a valid net structure
    buffer - ptr. to a buffer to copy to
    size - number of bytes to copy

NOTES
    Be careful when not using a serial.device compatible device.

EXAMPLE

BUGS

SEE ALSO
    InitIOEXT()

dignet.library/ReadNet                                 dignet.library/ReadNet

NAME
    ReadNet -- reads x bytes from the device

SYNOPSIS

    error=ReadNet(net,buffer,size)
                  a0  a1     d0

    ULONG ReadNet(APTR,APTR,ULONG);


FUNCTION
    This function will read from the device. You should first call a query
    function to check the number of bytes waiting and then read those into
    your buffer. If zero bytes this function will abort immediatly so it is
    safe to call it. If you ask for more bytes than are available this
    function will wait until the amont can be obtained.

INPUTS
    net - ptr. to a valid net structure
    buffer - ptr. to a buffer
    size - number of bytes to read

RESULTS
    error - null if ok, it reflect the io_error field

NOTES

EXAMPLE
    error=ReadNet(net,buffer,queryresult)

BUGS

SEE ALSO
    WriteNet(), QueryNet()


dignet.library/Timeout                                 dignet.library/Timeout

NAME
    Timeout -- waits x seconds to receive char(s) on the device for reading

SYNOPSIS

    chars=Timeout(net,seconds)
                  a0  d0

    ULONG Timeout(APTR,UWORD);


FUNCTION
    You can use this function to give a device a certain amont of time to get
    a char or more on the port for reading. You set seconds to wait. If a
    char or more is received the function will return with the current amount
    of chars in buffer. If timeout occure it will return with NULL.

    Null seconds is valid, however it will just call the QueryNet() function
    instead and return immediatly.

INPUTS
    net - ptr. to a valid net structure
    seconds - number of seconds to wait for timeout

RESULTS
    chars - number of chars received before timeout or NULL if none

NOTES

EXAMPLE

BUGS

SEE ALSO

dignet.library/WriteNet                               dignet.library/WriteNet

NAME
    WriteNet -- Writes x bytes to the device

SYNOPSIS

    error=WriteNet(net,buffer,size)
                   a0  a1     d0

    ULONG WriteNet(APTR,APTR,ULONG);


FUNCTION
    This function write a number of bytes (really a copy) from a buffer of
    size x. The function returns immediatly.

INPUTS
    net - ptr. to a valid net structure
    buffer - ptr. to a buffer taht contains bytes to write
    size - number of bytes to write

RESULTS
    error - reflects the io_error field. Null if ok.

NOTES

EXAMPLE
    error=WriteNet(net,buffer,100)

BUGS
    There had to be implemented a delay of 20/50 of a second to not return
    strange result if queried and read right after a write.

SEE ALSO
    ReadNet()