// Copyright (c) 2002 David Muse
// See the COPYING file for more information.

#ifndef RUDIMENTS_FILEDESCRIPTOR_H
#define RUDIMENTS_FILEDESCRIPTOR_H

#include <rudiments/private/filedescriptorincludes.h>

// The filedescriptor class is a base class for other classes that utilize
// file descriptors.

class filedescriptor {
        public:
                        filedescriptor();
                                // Creates an uninitialized filedescriptor.
                virtual ~filedescriptor();
                                // Calls close() if it hasn't already been
                                // called.


                bool    close();
                                // Closes the file descriptor.
                                // Returns true on success and false on failure.

                int     getFileDescriptor() const;
                                // Returns the file descriptor.
                void    setFileDescriptor(int filedesc);
                                // Sets the file descriptor associated with
                                // the class to "filedesc".

                int     duplicate() const;
                                // Duplicates the file descriptor and returns
                                // the handle of the duplicate descriptor.  The
                                // old and new descriptors may be used
                                // interchangeably, they share locks, position
                                // pointers, flags (except the close-on-exec
                                // flag), etc.
                                //
                                // Returns the lowest-numbered unused descriptor
                                // on success or -1 on failure.
                bool    duplicate(int newfd) const;
                                // Sets file descriptor handle "newfd" to be a
                                // duplicate of this file descriptor.  If
                                // "newfd" is already open, it will be closed
                                // first.
                                //
                                // Returns true on success and false on failure.

                #ifdef RUDIMENTS_HAS_SSL
                void    setSSLContext(SSL_CTX *ctx);
                                // Associates SSL context "ctx" with the
                                // filedescriptor.  Passing in a NULL for "ctx"
                                // has the additional side effect of calling
                                // deInitializeSSL() below.
                bool    initializeSSL();
                                // Should be called after calling
                                // setSSLContext() and one of open(),
                                // create() or connect() (from socket child
                                // classes). Causes the appropriate SSL
                                // function to be called instead of or in
                                // concert with read(), write(), connect(),
                                // accept() and close() methods.
                                //
                                // Returns true on success and false on failure
                SSL     *getSSL() const;
                                // Returns a pointer to the currently
                                // initialized SSL handle or NULL if
                                // initializeSSL() has not been called or
                                // failed.
                void    deInitializeSSL();
                                // Causes read(), write(), connect(), accept()
                                // and close() methods to be performed
                                // without the accompanying SSL-specific
                                // functions.

                int     getSSLResult() const;
                                // Returns the result code of the previously
                                // executed SSL command.  If a method fails
                                // but errno is 0 then an SSL-related error
                                // occurred.  You may call SSL_get_error()
                                // on the result of this method to determine
                                // the exact error.
                #endif

                virtual bool    useNonBlockingMode() const;
                                // Puts the file descriptor in non-blocking
                                // mode.  Returns true on success and false on
                                // failure.
                virtual bool    useBlockingMode() const;
                                // Puts the file descriptor in blocking mode.
                                // Returns true on success and false on
                                // failure.
                bool    isUsingNonBlockingMode() const;
                                // Returns true if the file descriptor is in
                                // non-blocking mode and false otherwise.

                // Write methods - write data to the file descriptor.
                // These methods return the number of bytes that were
                // successfully written or RESULT_ERROR if an error occurred.
                ssize_t write(unsigned short number);
                                // Write "number" to the file descriptor.
                ssize_t write(unsigned long number);
                                // Write "number" to the file descriptor.
                ssize_t write(short number);
                                // Write "number" to the file descriptor.
                ssize_t write(long number);
                                // Write "number" to the file descriptor.
                ssize_t write(float number);
                                // Write "number" to the file descriptor.
                ssize_t write(double number);
                                // Write "number" to the file descriptor.
                ssize_t write(unsigned char character);
                                // Write "character" to the file descriptor.
                ssize_t write(char character);
                                // Write "character" to the file descriptor.
                ssize_t write(bool value);
                                // Write "value" to the file descriptor.
                ssize_t write(const unsigned char *string);
                                // Write "string" to the file descriptor.  Note
                                // that "string" must be NULL-terminated.
                ssize_t write(const char *string);
                                // Write "string" to the file descriptor.  Note
                                // that "string" must be NULL-terminated.
                ssize_t write(const unsigned char *string, size_t size);
                                // Write "size" bytes from "string" to the file
                                // descriptor.  Note that it is possible to
                                // write beyond the string's NULL terminator
                                // using this method.
                ssize_t write(const char *string, size_t size);
                                // Write "size" bytes from "string" to the file
                                // descriptor.  Note that it is possible to
                                // write beyond the string's NULL terminator
                                // using this method.
                ssize_t write(const void *buffer, size_t size);
                                // Write "size" bytes from "buffer" to the file
                                // descriptor.


                // Write methods - write data to the file descriptor with a
                // timeout of "sec" seconds and "usec" microseconds.
                // These methods return the number of bytes that were
                // successfully written, RESULT_ERROR if an error occurred or
                // RESULT_TIMEOUT if a timeout occurred.
                ssize_t write(unsigned short number, long sec, long usec);
                                // Write "number" to the file descriptor.
                ssize_t write(unsigned long number, long sec, long usec);
                                // Write "number" to the file descriptor.
                ssize_t write(short number, long sec, long usec);
                                // Write "number" to the file descriptor.
                ssize_t write(long number, long sec, long usec);
                                // Write "number" to the file descriptor.
                ssize_t write(float number, long sec, long usec);
                                // Write "number" to the file descriptor.
                ssize_t write(double number, long sec, long usec);
                                // Write "number" to the file descriptor.
                ssize_t write(unsigned char character, long sec, long usec);
                                // Write "character" to the file descriptor.
                ssize_t write(char character, long sec, long usec);
                                // Write "character" to the file descriptor.
                ssize_t write(bool value, long sec, long usec);
                                // Write "value" to the file descriptor.
                ssize_t write(const unsigned char *string, long sec, long usec);
                                // Write "string" to the file descriptor.  Note
                                // that "string" must be NULL-terminated.
                ssize_t write(const char *string, long sec, long usec);
                                // Write "string" to the file descriptor.  Note
                                // that "string" must be NULL-terminated.
                ssize_t write(const unsigned char *string, size_t size,
                                                        long sec, long usec);
                                // Write "size" bytes from "string" to the file
                                // descriptor.  Note that it is possible to
                                // write beyond the string's NULL terminator
                                // using this method.
                ssize_t write(const char *string, size_t size,
                                                        long sec, long usec);
                                // Write "size" bytes from "string" to the file
                                // descriptor.  Note that it is possible to
                                // write beyond the string's NULL terminator
                                // using this method.
                ssize_t write(const void *buffer, size_t size,
                                                        long sec, long usec);
                                // Write "size" bytes from "buffer" to the file
                                // descriptor.


                // Read methods - read data from the file descriptor.
                // These methods return the number of bytes that were
                // successfully read or RESULT_ERROR if an error occurred.
                ssize_t read(unsigned short *buffer);
                                // Reads sizeof(unsigned short) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(unsigned long *buffer);
                                // Reads sizeof(unsigned long) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(short *buffer);
                                // Reads sizeof(short) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(long *buffer);
                                // Reads sizeof(long) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(float *buffer);
                                // Reads sizeof(float) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(double *buffer);
                                // Reads sizeof(double) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(unsigned char *buffer);
                                // Reads sizeof(unsigned char) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(char *buffer);
                                // Reads sizeof(char) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(bool *buffer);
                                // Reads sizeof(bool) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(unsigned char *buffer, size_t size);
                                // Reads "size" bytes from the file descriptor
                                // into "buffer".
                ssize_t read(char *buffer, size_t size);
                                // Reads "size" bytes from the file descriptor
                                // into "buffer".
                ssize_t read(void *buf, size_t size);
                                // Reads "size" bytes from the file descriptor
                                // into "buffer".
                ssize_t read(char **buffer, char *terminator);
                                // Reads from the file desciptor into "buffer"
                                // until "terminator" is encountered.  Note
                                // that "buffer" is allocated internally and
                                // must be freed by the calling program.


                // Read methods - read data from the file descriptor with a
                // timeout of "sec" seconds and "usec" microseconds.
                // These methods return the number of bytes that were
                // successfully read, RESULT_ERROR if an error occurred or
                // RESULT_TIMEOUT if a timeout occurred.
                ssize_t read(unsigned short *buffer, long sec, long usec);
                                // Reads sizeof(unsigned short) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(unsigned long *buffer, long sec, long usec);
                                // Reads sizeof(unsigned long) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(short *buffer, long sec, long usec);
                                // Reads sizeof(short) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(long *buffer, long sec, long usec);
                                // Reads sizeof(long) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(float *buffer, long sec, long usec);
                                // Reads sizeof(float) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(double *buffer, long sec, long usec);
                                // Reads sizeof(double) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(unsigned char *buffer, long sec, long usec);
                                // Reads sizeof(unsigned char) bytes
                                // from the file descriptor into "buffer".
                ssize_t read(char *buffer, long sec, long usec);
                                // Reads sizeof(char) bytes from the file
                                // descriptor into "buffer".
                ssize_t read(bool *buffer, long sec, long usec);
                                // Reads sizeof(bool) bytes from the
                                // file descriptor into "buffer".
                ssize_t read(unsigned char *buffer, size_t size,
                                                        long sec, long usec);
                                // Reads "size" bytes from the file descriptor
                                // into "buffer".
                ssize_t read(char *buffer, size_t size, long sec, long usec);
                                // Reads "size" bytes from the file descriptor
                                // into "buffer".
                ssize_t read(void *buf, size_t size, long sec, long usec);
                                // Reads "size" bytes from the file descriptor
                                // into "buffer".
                ssize_t read(char **buffer, char *terminator,
                                                        long sec, long usec);
                                // Reads from the file desciptor into "buffer"
                                // until "terminator" is encountered.  Note
                                // that "buffer" is allocated internally and
                                // must be freed by the calling program.


                // Wait methods.
                int     waitForNonBlockingRead(long sec, long usec) const;
                                // Causes the application to wait until a read()
                                // will proceed without blocking or until "sec"
                                // seconds and "usec" microseconds have elapsed.
                                //
                                // Entering -1 for either parameter causes the
                                // method to wait indefinitely.  
                                //
                                // Entering 0 for both parameters causes the
                                // method to fall through immediately unless a
                                // data is immediately available.
                                //
                                // Returns RESULT_ERROR on error, RESULT_TIMEOUT
                                // on timeout and otherwise returns the number
                                // of file descriptors that are ready to be
                                // read from.
                                //
                                // This will usually be 1, indicating that the
                                // file descriptor represented by the class is
                                // ready to be read from.  However, if
                                // useListener() has been called, it may be
                                // greater than 1, indicating that a set of
                                // file descriptors that the listener is
                                // listening on are all ready to be read from.
                int     waitForNonBlockingWrite(long sec, long usec) const;
                                // Causes the application to wait until a
                                // write() will proceed without blocking or
                                // until "sec" seconds and "usec" microseconds
                                // have elapsed.
                                //
                                // Entering -1 for either parameter causes the
                                // method to wait indefinitely.  
                                //
                                // Entering 0 for both parameters causes the
                                // method to fall through immediately unless a
                                // data is immediately available.
                                //
                                // Returns RESULT_ERROR on error, RESULT_TIMEOUT
                                // on timeout and otherwise returns the number
                                // of file descriptors that are ready to be
                                // written to.
                                //
                                // This will usually be 1, indicating that the
                                // file descriptor represented by the class is
                                // ready to be written to.  However, if
                                // useListener() has been called, it may be
                                // greater than 1, indicating that a set of
                                // file descriptors that the listener is
                                // listening on are all ready to be written to.


                // By default, if a read or write is occurring and a signal
                // interrupts it, the read or write returns with errno set to
                // EINTR and must be retried.  These methods override that
                // behavior.
                void    retryInterruptedReads();
                        // Causes reads to automatically retry if interrupted
                        // by a signal.
                void    dontRetryInterruptedReads();
                        // Causes reads not to automatically retry if
                        // interrupted by a signal.
                void    retryInterruptedWrites();
                        // Causes writes to automatically retry if
                        // interrupted by a signal.  This is the default.
                void    dontRetryInterruptedWrites();
                        // Causes writes not to automatically retry if
                        // interrupted by a signal.
                void    retryInterruptedWaits();
                        // Causes waits to automatically retry if
                        // interrupted by a signal.  This is the default.
                void    dontRetryInterruptedWaits();
                        // Causes waits not to automatically retry if
                        // interrupted by a signal.
                void    retryInterruptedFcntl();
                        // Causes fcntl() to automatically retry if
                        // interrupted by a signal.  This is the default.
                void    dontRetryInterruptedFcntl();
                        // Causes fcntl() not to automatically retry if
                        // interrupted by a signal.
                void    retryInterruptedIoctl();
                        // Causes ioctl() to automatically retry if
                        // interrupted by a signal.  This is the default.
                void    dontRetryInterruptedIoctl();
                        // Causes ioctl() not to automatically retry if
                        // interrupted by a signal.


                // By default, read() will attempt to read the specified number
                // of bytes from the file descriptor, in several passes if
                // necessary.  No single pass will try to read more than
                // SSIZE_MAX bytes.  These methods override that behavior.
                void    allowShortReads();
                        // Causes a read to return the number of bytes that
                        // were read in a single pass from the file descriptor.
                        // Note that reads longer than SSIZE_MAX will always
                        // return SSIZE_MAX or fewer bytes.  This is useful,
                        // for example, when reading from devices which block
                        // rather than returning 0 for EOF.
                void    dontAllowShortReads();
                        // Causes a read to attempt to read the specified
                        // number of bytes from the file descriptor, in several
                        // passes if necessary.


                // By default, calls to waitForNonBlockingRead() and
                // waitForNonBlockingWrite() will wait using the select()
                // system call.  These methods override that behavior.
                void    useListener(listener *lstnr);
                        // Causes calls to waitForNonBlockingRead() and
                        // waitForNonBlockingWrite() to in turn call
                        // lstnr->waitForNonBlockingRead() or
                        // lstnr->waitForNonBlockingWrite().
                void    dontUseListener();
                        // Causes calls to waitForNonBlockingRead() and
                        // waitForNonBlockingWrite() to use select().
                        // This is the default.
                listener        *getListener();
                        // Returns the listener set previously by useListener() 
                        // or NULL if none has been set.


                virtual bool    passFileDescriptor(int descriptor);
                virtual bool    receiveFileDescriptor(int *descriptor);

                void    translateByteOrder();
                void    dontTranslateByteOrder();

                int     fcntl(int command, long arg) const;
                int     ioctl(int command, void *arg) const;
                        // Interfaces for performing varions miscellaneous
                        // operations on the file descriptor.

        #include <rudiments/private/filedescriptor.h>
};

#endif