########################################################################/-Rdoc TURNED OFF-**
 # @RdocFunction .readCelHeaderV4
 #
 # @title "Read the header of a CEL v4 (binary) file"
 #
 # \description{
 #  @get "title".
 # }
 #
 # @synopsis
 #
 # \arguments{
 #  \item{con}{An open and readable @connection.}
 # }
 #
 # \value{
 #  Returns a named @list structure.
 # }
 #
 # \details{
 #  When the header is read, the file pointer is at the beginning
 #  of the data section.  See also @see "base::seek".

 #  This is an internal function that is used mainly to skip the CEL header

 #  to reach the data section.  It does not make use of Fusion SDK.
 # }
 #

 # @author "HB"

 #
 # @keyword IO
 # @keyword File
 # @keyword internal
 #**-Rdoc TURNED OFF-/#######################################################################
 .readCelHeaderV4 <- function(con, ...) {
   readInteger <- function(con, ...) {
     readBin(con, what="integer", size=4, n=1, signed=TRUE, endian="little");
   }
 
   readShort <- function(con, ...) {
     readBin(con, what="integer", size=2, n=1, signed=TRUE, endian="little");
   }
 
   readFloat <- function(con, ...) {
     readBin(con, what="double", size=4, n=1, endian="little");
   }
 
   readDWord <- function(con, ...) {

     # NOTE: Ideally we would use signed=FALSE here, but there is no
     # integer data type in R that can hold 4-byte unsigned integers.
     # Because of this limitation, readBin() will give a warning that
     # signed=FALSE only works for size=1 or 2.
     # WORKAROUND: Use signed=TRUE and assume there are no values
     # greater that .Machine$integer.max == 2^31-1. /HB 2015-04-15

     readBin(con, what="integer", size=4, n=1, signed=TRUE, endian="little");

   }
 
   readString <- function(con, ...) {
     len <- readInteger(con); # Number of characters to read
     readChar(con, nchars=len);
   }
 
   # Read and validate the MAGIC
   magic <- readInteger(con);
   if (magic != 64) {

     stop("Could not read CEL v4 file.  File format error: MAGIC == ", magic);

   }
 
   list(
     magic = magic,
     version = readInteger(con),
     cols = readInteger(con),
     rows = readInteger(con),
     total = readInteger(con),
     hdr = readString(con),
     algorithm = readString(con),
     parameters = readString(con),
     cellmargin = readInteger(con),
     noutliers = readDWord(con),
     nmasked = readDWord(con),
     nsubgrids = readInteger(con)
   )
 } # .readCelHeaderV4()
 
 
 
 ############################################################################
 # HISTORY:

 # 2011-11-01
 # o CLEANUP: Changed a signed=FALSE to signed=TRUE for a readBin() call
 #   reading 4-byte integers in .readCelHeaderV4().

 # 2006-06-18
 # o Created.  Used by updateCel() to skip header to reach data section.

 ############################################################################