home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / reference / amiga_mail_vol2 / ii-77 / async.doc next >
Text File  |  1992-12-21  |  7KB  |  207 lines
  1. (c)  Copyright 1992 Commodore-Amiga, Inc.   All rights reserved.
  2. The information contained herein is subject to change without notice,
  3. and is provided "as is" without warranty of any kind, either expressed
  4. or implied.  The entire risk as to the use of this information is
  5. assumed by the user.
  6.  
  7. TABLE OF CONTENTS
  8.  
  9. asyncio/CloseAsync
  10. asyncio/OpenAsync
  11. asyncio/ReadAsync
  12. asyncio/ReadAsyncChar
  13. asyncio/WriteAsync
  14. asyncio/WriteAsyncChar
  15. asyncio/CloseAsync                                         asyncio/CloseAsync
  16.  
  17.    NAME
  18.         CloseAsync -- close an async io file.
  19.  
  20.    SYNOPSIS
  21.         result = CloseAsync(file);
  22.  
  23.         LONG CloseAsync(struct AsyncFile *);
  24.  
  25.    FUNCTION
  26.         Closes a file, flushing any pending writes.  Once this call has been
  27.         made, the file can no longer be accessed.
  28.  
  29.    INPUTS
  30.         file - the file to close.  May be NULL.
  31.  
  32.    RESULT
  33.         result - < 0 for an error, >= 0 for success.  Indicates whether closing
  34.                  the file worked or not.  If the file was opened in read-mode,
  35.                  then this call will always work.  In case of error,
  36.                  dos.library/IoErr() can give more information.
  37.  
  38.    SEE ALSO
  39.         OpenAsync, dos.library/Close()
  40.  
  41. asyncio/OpenAsync                                           asyncio/OpenAsync
  42.  
  43.    NAME
  44.         OpenAsync -- open a file for asynchronous IO.
  45.  
  46.    SYNOPSIS
  47.         file = OpenAsync(fileName, accessMode, bufferSize);
  48.  
  49.         struct AsyncFile OpenAsync(STRPTR, UBYTE, LONG);
  50.  
  51.    FUNCTION
  52.         The named file is opened and an async file handle returned.  If the
  53.         accessMode is MODE_READ, an existing file is opened for reading.
  54.         If the value is MODE_WRITE, a new file is created for writing.  If
  55.         a file of the same name already exists, it is first deleted.  If
  56.         accessMode is MODE_APPEND, an existing file is prepared for writing.
  57.         Data written is added to the end of the file.  If the file does not
  58.         exists, it is created.
  59.  
  60.         'fileName' is a filename and CANNOT be a simple device such as NIL:, a
  61.         window specification such as CON: or RAW:, or "*".
  62.  
  63.         'bufferSize' specifies the size of the IO buffer to use.  There are
  64.         in fact two buffers allocated, each of roughly (bufferSize/2) bytes
  65.         in size.  The actual buffer size use can vary slightly as the size
  66.         is rounded to speed up DMA.
  67.  
  68.         If the file cannot be opened for any reason, the value returned
  69.         will be NULL, and a secondary error code will be available by
  70.         calling the routine dos.library/IoErr().
  71.  
  72.     INPUTS
  73.         name - name of the file to open
  74.         accessMode - one of MODE_READ, MODE_WRITE, or MODE_APPEND
  75.         bufferSize - size of IO buffer to use.  8192 is recommended as it
  76.                      provides very good performance for relatively little
  77.                      memory.
  78.  
  79.     RESULTS
  80.         file - an async file handle or NULL for failure.  You should not access
  81.                the fields in the AsyncFile structure, these are private to the
  82.                async IO routines.  In case of failure, dos.library/IoErr() can
  83.                give more information.
  84.  
  85.     SEE ALSO
  86.         CloseAsync(), dos.library/Open()
  87.  
  88. asyncio/ReadAsync                                           asyncio/ReadAsync
  89.  
  90.    NAME
  91.         ReadAsync -- read bytes from an async file.
  92.  
  93.    SYNOPSIS
  94.         actualLength = ReadAsync(file,buffer,numBytes);
  95.  
  96.         LONG ReadAsync(struct AsyncFile *file, APTR buffer, LONG numBytes);
  97.  
  98.    FUNCTION
  99.         Read() reads bytes of information from an opened async file
  100.         into the buffer given.  'numBytes' is the number of bytes to read from
  101.         the file.
  102.  
  103.         The value returned is the length of the information actually read.
  104.         So, when 'actualLength' is greater than zero, the value of
  105.         'actualLength' is the the number of characters read.  Usually
  106.         ReadAsync() will try to fill up your buffer before returning.  A value
  107.         of zero means that end-of-file has been reached.  Errors are indicated
  108.         by a value of -1.
  109.  
  110.     INPUTS
  111.         file - opened file to read, as obtained from OpenAsync()
  112.         buffer - buffer where to put bytes read
  113.         numBytes - number of bytes to read into buffer
  114.  
  115.     RESULT
  116.         actualLength - actual number of bytes read, or -1 if an error.  In
  117.                        case of error, dos.library/IoErr() can give more
  118.                        information.
  119.  
  120.     SEE ALSO
  121.         OpenAsync(), CloseAsync(), WriteAsync(), ReadCharAsync(),
  122.         dos.library/Read()
  123.  
  124. asyncio/ReadCharAsync                                   asyncio/ReadCharAsync
  125.  
  126.    NAME
  127.         ReadCharAsync -- read a single byte from an async file.
  128.  
  129.    SYNOPSIS
  130.         byte = ReadCharAsync(file);
  131.  
  132.         LONG ReadCharAsync(struct AsyncFile *file);
  133.  
  134.    FUNCTION
  135.         This function reads a single byte from an async file.  The byte is
  136.         returned, or -1 if there was an error reading, or if the end-of-file
  137.         was reached.
  138.  
  139.    INPUTS
  140.         file - opened file to read from, as obtained from OpenAsync()
  141.  
  142.    RESULT
  143.         byte - the byte read, or -1 if no byte was read.  In case of error,
  144.                dos.library/IoErr() can give more information.
  145.  
  146.    SEE ALSO
  147.         OpenAsync(), CloseAsync(), WriteCharAsync(), ReadAsync()
  148.         dos.library/Read()
  149.  
  150. asyncio/WriteAsync                                         asyncio/WriteAsync
  151.  
  152.    NAME
  153.         WriteAsync -- write data to an async file.
  154.  
  155.    SYNOPSIS
  156.         actualLength = WriteAsync(file,buffer,numBytes);
  157.  
  158.         LONG WriteAsync(struct AsyncFile *file, APTR buffer, LONG numBytes);
  159.  
  160.    FUNCTION
  161.         WriteAsync() writes bytes of data to an opened async file.  'numBytes'
  162.         indicates the number of bytes of data to be transferred.  'buffer'
  163.         points to the data to write.  The value returned is the length of
  164.         information actually written.  So, when 'numBytes' is greater than
  165.         zero, the value of 'numBytes' is the number of characters written.
  166.         Errors are indicated by a value of -1.
  167.  
  168.     INPUTS
  169.         file - an opened file, as obtained from OpenAsync()
  170.         buffer - address of data to write
  171.         numBytes - number of bytes to write to the file
  172.  
  173.     RESULT
  174.         actualLength - number of bytes written, or -1 if error.  In case
  175.                        of error, dos.library/IoErr() can give more
  176.                        information.
  177.  
  178.     SEE ALSO
  179.         OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync(),
  180.         dos.library/Write
  181.  
  182. asyncio/WriteCharAsync                                 asyncio/WriteCharAsync
  183.  
  184.    NAME
  185.         WriteCharAsync -- write a single byte to an async file.
  186.  
  187.    SYNOPSIS
  188.         result = WriteCharAsync(file,byte);
  189.  
  190.         LONG WriteCharAsync(struct AsyncFile *, UBYTE byte);
  191.  
  192.    FUNCTION
  193.         This function write a single byte to an async file.
  194.  
  195.    INPUTS
  196.         file - an opened async file, as obtained from OpenAsync()
  197.         byte - byte of data to add to the file
  198.  
  199.    RESULT
  200.         result - 1 if the byte was written, -1 if there was an error.  In
  201.                  case of error, dos.library/IoErr() can give more information.
  202.  
  203.    SEE ALSO
  204.         OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync(),
  205.         dos.library/Write
  206.  
  207.