/****************************************************************************
 *  INTEL CONFIDENTIAL
 *  Copyright 2006 Intel Corporation All Rights Reserved.
 *
 *  The source code contained or described herein and all documents related
 *  to the source code ("Material") are owned by Intel Corporation or its
 *  suppliers or licensors. Title to the Material remains with Intel
 *  Corporation or its suppliers and licensors. The Material may contain
 *  trade secrets and proprietary and confidential information of Intel
 *  Corporation and its suppliers and licensors, and is protected by
 *  worldwide copyright and trade secret laws and treaty provisions. No part
 *  of the Material may be used, copied, reproduced, modified, published,
 *  uploaded, posted, transmitted, distributed, or disclosed in any way
 *  without Intel's prior express written permission.
 *
 *  No license under any patent, copyright, trade secret or other
 *  intellectual property right is granted to or conferred upon you by
 *  disclosure or delivery of the Materials, either expressly, by
 *  implication, inducement, estoppel or otherwise. Any license under such
 *  intellectual property rights must be express and approved by Intel in
 *  writing.
 *
 *  Unless otherwise agreed by Intel in writing, you may not remove or alter
 *  this notice or any other notice embedded in Materials by Intel or Intel's
 *  suppliers or licensors in any way.
 ****************************************************************************/

/****************************************************************************
 * Description: Defines functions that manipulate raw files and device
 *              virtual files.
 ****************************************************************************/

#ifndef COMPAT_FILDES_
#define COMPAT_FILDES_

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

#include <fcntl.h>
#include <sys/file.h>

#include "compat_lib.h"

/* Valid non-zero values for the accessMode argument to CPL_FileOpen */
enum CPL_accessModeValues {
    CPL_READ      = O_RDONLY,
    CPL_WRITE     = O_WRONLY,
    CPL_READWRITE = O_RDWR
};

/* Valid components to the optFlag argument to CPL_FileOpen */
enum CPL_optFlagValues {
    CPL_APPEND = O_APPEND,
    CPL_SYNC   = O_SYNC,
    CPL_CREAT  = O_CREAT,
    CPL_TRUNC  = O_TRUNC,
    CPL_EXCL   = O_EXCL
};

/* Valid values for the offset argument to CPL_FileSeek */
enum CPL_offsetValues {
    CPL_SEEKSTART   = SEEK_SET,
    CPL_SEEKCURRENT = SEEK_CUR,
    CPL_SEEKEND     = SEEK_END
};

/* Valid components of the operation argument of CPL_FileLock */
enum CPL_lockOperationValues {
    CPL_SHAREDLOCK    = LOCK_SH,
    CPL_EXCLUSIVELOCK = LOCK_EX,
    CPL_UNLOCK        = LOCK_UN,
    CPL_NONBLOCKING   = LOCK_NB
};



/****************************************************************************
 *  Function:    CPL_FileOpen
 *  Description: Opens a file for use by the following functions.
 *  Parameters:
 *    path        [IN] The path to the file to be opened or created.
 *    accessMode  [IN] What kinds of access are needed.  Valid values are
 *                     zero, CPL_READ, CPL_WRITE, and CPL_READWRITE (which is
 *                     just shorthand for CPL_READ | CPL_WRITE).
 *    optFlag     [IN] A bitfield of flags.  Values to be ORed together:
 *                        CPL_APPEND  Seek to the end of the file.
 *                        CPL_SYNC    Keep the physical device in sync.
 *                        CPL_CREAT   Create the file if necessary.
 *                        CPL_TRUNC   Truncate the file if it exists.
 *                        CPL_EXCL    Return an error if file exists.
 *  Returns:     An open file descriptor, or -1 on error.
 ****************************************************************************/
INT32S CPL_FileOpen(const char *path,
                    INT32S      accessMode,
                    INT32S      optFlag);

/****************************************************************************
 *  Function:    CPL_FileRead
 *  Description: Reads bytes from a file descriptor.
 *  Parameters:  fildes   [IN] The file descriptor to read from.
 *               buf     [OUT] A buffer to put the read bytes into.
 *               nbyte    [IN] The maximum number of bytes to read.
 *  Returns:     The actual number of bytes read, or -1 on error.
 ****************************************************************************/
INT32S CPL_FileRead(INT32S fildes,
                    void * buf,
                    INT32U nbyte);

/****************************************************************************
 *  Function:    CPL_FileWrite
 *  Description: Writes bytes to a file descriptor.
 *  Parameters:  fildes  [IN] The file descriptor to write to.
 *               buf     [IN] A buffer containing the bytes to write.
 *               nbyte   [IN] The maximum number of bytes to write.
 *  Returns:     The actual number of bytes written, or -1 on error.
 ****************************************************************************/
INT32S CPL_FileWrite(INT32S       fildes,
                     const void * buf,
                     INT32U       nbyte);

/****************************************************************************
 *  Function:    CPL_FileSeek
 *  Description: Moves the location where read and write operations occur.
 *  Parameters:  fildes  [IN] The file descriptor to move the pointer of.
 *               offset  [IN] Where to move the file pointer, relative to...
 *               whence  [IN] The location of an offset of 0.  Valid values
 *                            are SEEK_SET (beginning), SEEK_CUR and SEEK_END.
 *  Returns:     The new offset (measured from start of file) or -1 on error.
 ****************************************************************************/
INT32S CPL_FileSeek(INT32S fildes,
                    INT32S offset,
                    INT32S whence);

/****************************************************************************
 *  Function:    CPL_FileLock
 *  Description: Locks or unlocks the file pointed to by a file descriptor.
 *  Parameters:  fildes    [IN] A descriptor for the file to lock or unlock.
 *               operation [IN] What file-locking operation to perform.  Use
 *                              CPL_SHAREDLOCK for a shared lock,
 *                              CPL_EXCLUSIVELOCK for an exclusive lock,
 *                              and CPL_UNLOCK to unlock.
 *                              Adding CPL_NONBLOCKING via OR makes it a
 *                              non-blocking operation.
 *  Returns:     Zero on success, or -1 on error.  If CPL_NONBLOCKING was
 *               provided and the file was locked, CPL_GetError() returns
 *               CPL_WARN_WOULDBLOCK.  
 ****************************************************************************/
INT32S CPL_FileLock(INT32S fildes,
                    INT32S operation);

/****************************************************************************
 *  Function:    CPL_FileClose
 *  Description: Closes a file descriptor.
 *  Parameters:  fildes   [IN] The file descriptor to close.
 *  Returns:     Zero on success, or -1 on error.
 ****************************************************************************/
INT32S CPL_FileClose(INT32S fildes);

/****************************************************************************
 *  Function:    CPL_FileFlush
 *  Description: Flushes all written bytes to storage
 *  Parameters:  fildes  [IN] The file descriptor to write to.
 *  Returns:     Zero on successs, or -1 on error.
 ****************************************************************************/
INT32S CPL_FileFlush(INT32S fildes);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* COMPAT_FILDES_ */
