host

KExtendedSocket(3)         Library Functions Manual         KExtendedSocket(3)



NAME
       KExtendedSocket - The extended socket class. an extended socket.


SYNOPSIS
       #include <kextsock.h>

       Inherits KBufferedIO.

   Public Types
       enum Flags { anySocket =  0x00, knownSocket =  0x01, unixSocket =
           knownSocket | 0x02, inetSocket =  knownSocket | 0x04, ipv4Socket =
           inetSocket | 0x100, ipv6Socket =  inetSocket | 0x200, passiveSocket
           =  0x1000, canonName =  0x2000, noResolve =  0x4000, streamSocket =
           0x8000, datagramSocket =  0x10000, rawSocket =  0x20000,
           inputBufferedSocket =  0x200000, outputBufferedSocket =  0x400000,
           bufferedSocket =  0x600000 }
           flags that can be passed down to the member functions
       enum SockStatus { error =  -1, nothing =  0, lookupInProgress =  50,
           lookupDone =  70, created =  100, bound =  140, connecting =  200,
           connected =  220, listening =  200, accepting =  220, closing =
           350, done =  400 }
           status of the class The status are sequential.

   Signals
       void lookupFinished (int count)
           This signal is emitted whenever an asynchronous lookup process is
           done.
       void connectionSuccess ()
           This signal is emitted whenever we connected asynchronously to a
           host.
       void connectionFailed (int error)
           This signal is emitted whenever our asynchronous connection attempt
           failed to all hosts listed.
       void readyAccept ()
           This signal is emitted whenever this socket is ready to accept
           another socket.

   Public Member Functions
       KExtendedSocket ()
           Creates an empty KExtendedSocket.
       KExtendedSocket (const  QString &host, int port, int flags=0)
           Creates a socket with the given hostname and port.
       KExtendedSocket (const  QString &host, const  QString &service, int
           flags=0)
           Creates a socket with the given hostname and service.
       virtual ~KExtendedSocket ()
           Destroys the socket, disconnecting if still connected and freeing
           any related resources still being kept.
       void reset ()
           Resets the socket, disconnecting if still connected and freeing any
           related resources still being kept.
       int socketStatus () const
           Returns the class status.
       int systemError () const
           Returns the related system error code Except for IO_LookupError
           errors, these are codes found in errno.
       int setSocketFlags (int flags)
           Sets the given flags.
       int socketFlags () const
           Returns the current flags.
       bool setHost (const  QString &host)
           Sets the hostname to the given value.
       QString host () const
           Returns the hostname.
       bool setPort (int port)
           Sets the port/service.
       bool setPort (const  QString &service)
           Sets the port/service.
       QString port () const
           Returns the port/service.
       bool setAddress (const  QString &host, int port)
           Sets the address where we will connect to.
       bool setAddress (const  QString &host, const  QString &serv)
           Sets the address where we will connect to.
       bool setBindHost (const  QString &host)
           Sets the hostname to which we will bind locally before connecting.
       bool unsetBindHost ()
           Unsets the bind hostname.
       QString bindHost () const
           Returns the hostname to which the socket will be/is bound.
       bool setBindPort (int port)
           Sets the port/service to which we will bind before connecting.
       bool setBindPort (const  QString &service)
           Sets the port/service to which we will bind before connecting.
       bool unsetBindPort ()
           Unsets the bind port/service.
       QString bindPort () const
           Returns the service to which the socket will be/is bound.
       bool setBindAddress (const  QString &host, int port)
           Sets both host and port to which we will bind the socket.
       bool setBindAddress (const  QString &host, const  QString &service)
           Sets both host and service to which we will bind the socket.
       bool unsetBindAddress ()
           Unsets the bind address for the socket.
       bool setTimeout (int secs, int usecs=0)
           Sets the timeout value for the connection (if this is not
           passiveSocket) or acception (if it is).
       timeval timeout () const
           Returns the timeout value for the connection.
       bool setBlockingMode (bool enable)
           Sets/unsets blocking mode for the socket.
       bool blockingMode ()
           Returns the current blocking mode for this socket.
       bool setAddressReusable (bool enable)
           Sets/unsets address reusing flag for this socket.
       bool addressReusable ()
           Returns whether this socket's address can be reused.
       bool setIPv6Only (bool enable)
           Sets/unsets the v6-only flag for IPv6 sockets.
       bool isIPv6Only ()
           Returns the status of the v6-only flag for IPv6 sockets.
       virtual bool setBufferSize (int rsize, int wsize=-2)
           Sets the buffer sizes for this socket.
       const  KSocketAddress * localAddress ()
           Returns the local socket address.
       const  KSocketAddress * peerAddress ()
           Returns the peer socket address.
       int fd () const
           Returns the file descriptor.
       virtual int lookup ()
           Performs lookup on the addresses we were given before.
       virtual int startAsyncLookup ()
           Starts an asynchronous lookup for the addresses given.
       virtual void cancelAsyncLookup ()
           Cancels any on-going asynchronous lookups.
       virtual int listen (int N=5)
           Place the socket in listen mode.
       virtual int accept (KExtendedSocket *&sock)
           Accepts an incoming connection from the socket.
       virtual int connect ()
           Attempts to connect to the remote host.
       virtual int startAsyncConnect ()
           Starts an asynchronous connect.
       virtual void cancelAsyncConnect ()
           Cancels any on-going asynchronous connection attempt.
       virtual bool open (int mode=IO_Raw|IO_ReadWrite)
           Implementation of QIODevice::open() pure virtual function.
       virtual void close ()
           Closes the socket.
       virtual void closeNow ()
           Closes the socket now, discarding the contents of the write buffer,
           if any.
       virtual void release ()
           Releases the socket and anything we have holding on it.
       virtual void flush ()
           Flushes the socket buffer.
       virtual Q_ULONG size () const
           Returns length of this socket.
       virtual Q_ULONG at () const
           Returns relative position from start.
       virtual bool at (int i)
           Returns true if we are at position.
       virtual bool atEnd () const
           Returns true if we are at the end.
       virtual Q_LONG readBlock (char *data, Q_ULONG maxlen)
           Reads a block of data from the socket.
       virtual Q_LONG writeBlock (const  char *data, Q_ULONG len)
           Writes a block of data to the socket.
       virtual int peekBlock (char *data, uint maxlen)
           Peeks at a block of data from the socket.
       virtual int unreadBlock (const  char *data, uint len)
           Reimplementation of unreadBlock() method.
       virtual int bytesAvailable () const
           Returns the number of available bytes yet to be read via readBlock
           and family of functions.
       virtual int waitForMore (int msec)
           Waits msec milliseconds for more data to be available (use 0 to
           wait forever).
       virtual int getch ()
           Gets a single character (unsigned char) from the stream.
       virtual int putch (int ch)
           Writes a single character (unsigned char) to the stream.
       virtual int ungetch (int)
           Unreads one character from the stream.
       virtual void enableRead (bool enable)
           Toggles the emission of the readyRead signal.
       virtual void enableWrite (bool enable)
           Toggles the emission of the readyWrite signal.

   Static Public Member Functions
       int resolve (sockaddr *sock, ksocklen_t len, QString &host, QString
           &port, int flags=0)
           Performs resolution on the given socket address.
       int resolve (KSocketAddress *sock, QString &host, QString &port, int
           flags=0)
           Performs resolution on the given socket address.
       QPtrList< KAddressInfo > lookup (const  QString &host, const  QString
           &port, int flags=0, int *error=0)
           Performs lookup on the given hostname/port combination and returns
           a list of matching addresses.
       KSocketAddress * localAddress (int fd)
           Returns the local socket address Remember to delete the returned
           object when it is no longer needed.
       KSocketAddress * peerAddress (int fd)
           Returns the peer socket address.
       QString strError (int code, int syserr)
           Returns the representing text of this error code.
       bool setAddressReusable (int fd, bool enable)
           Sets/unsets address reusing flag for this socket.

   Protected Slots
       void socketActivityRead ()
       void socketActivityWrite ()
       void dnsResultsReady ()
       void startAsyncConnectSlot ()
       void connectionEvent ()

   Protected Member Functions
       QSocketNotifier * readNotifier ()
       QSocketNotifier * writeNotifier ()
       void setError (int errorkind, int error)
           Sets the error code.
       void cleanError ()
       void setSocketStatus (int status)
           Sets the socket status.
       virtual void virtual_hook (int id, void *data)

   Protected Attributes
       int sockfd

   Friends
       class KSocket
       class KServerSocket

Detailed Description
       The extended socket class. an extended socket.

       This class should be used instead of KSocket whenever the user needs
       fine-grained control over the socket being created. Unlike KSocket,
       which does everything at once, without much intervention,
       KExtendedSocket allows intervention at every step of the process and
       the setting of parameters.

       This class allows for the creation of both server and client sockets.
       The only difference is that the passiveSocket flag must be passed
       either to the constructor or to setSocketFlags(). If passiveSocket is
       used, the class will enable functions listen() and accept() and related
       signals, and will also disable readBlock() and writeBlock().

       To create a Unix socket, one would pass flag unixSocket to the
       constructor or setSocketFlags(). The hostname and service/port can be
       set to whatever is necessary. If no hostname is given, but a
       service/port is, the socket created will be implementation dependant
       (usually in /tmp). In any other case, the fields will be concatenated.

       To create an Internet socket, inetSocket flag can be used. If, on the
       other hand a specific IP protocol is desired, ipv4Socket and/or
       ipv6Socket can be used.

       Note that the socket type selection flags are cumulative. One could
       select Unix and Internet sockets by using unixSocket | inetSocket. Or,
       for instance, to make sure only IPv4 and IPv6 sockets are selected,
       even if future implementations support newer IP protocols, ipv4Socket |
       ipv6Socket is your guy.

       Author:
           Thiago Macieira <thiagom@mail.com>

       Version:
           Id.RS 4 kextsock.h,v 1.30.2.2 2003/05/29 18:12:23 thiago Exp

       Definition at line 83 of file kextsock.h.

Member Enumeration Documentation
   enum KExtendedSocket::Flags
       flags that can be passed down to the member functions Definition at
       line 91 of file kextsock.h.

   enum KExtendedSocket::SockStatus
       status of the class The status are sequential. If a change to one
       status is requested, all the prior status will be passed and their
       actions, performed Definition at line 123 of file kextsock.h.

Constructor & Destructor Documentation
   KExtendedSocket::KExtendedSocket ()
       Creates an empty KExtendedSocket. Definition at line 407 of file
       kextsock.cpp.

   KExtendedSocket::KExtendedSocket (const QString & host, int port, int flags
       = 0)
       Creates a socket with the given hostname and port. Parameters:
           host the hostname
           port the port number
           flags flags

       Definition at line 413 of file kextsock.cpp.

       References QIODevice::flags(), setAddress(), and setSocketFlags().

   KExtendedSocket::KExtendedSocket (const QString & host, const QString &
       service, int flags = 0)
       Creates a socket with the given hostname and service. Parameters:
           host the hostname
           serv the service
           flags flags

       Definition at line 421 of file kextsock.cpp.

       References QIODevice::flags(), setAddress(), and setSocketFlags().

   KExtendedSocket::~KExtendedSocket () [virtual]
       Destroys the socket, disconnecting if still connected and freeing any
       related resources still being kept. Definition at line 429 of file
       kextsock.cpp.

       References closeNow().

Member Function Documentation
   void KExtendedSocket::reset ()
       Resets the socket, disconnecting if still connected and freeing any
       related resources still being kept. Since:
           3.1

       Reimplemented from QIODevice.

       Definition at line 449 of file kextsock.cpp.

       References closeNow(), and release().

   int KExtendedSocket::socketStatus () const
       Returns the class status. Returns:
           the class status

       See also:
           ::SockStatus

       Definition at line 458 of file kextsock.cpp.

   int KExtendedSocket::systemError () const
       Returns the related system error code Except for IO_LookupError errors,
       these are codes found in errno. Returns:
           the system error code

       Definition at line 474 of file kextsock.cpp.

   int KExtendedSocket::setSocketFlags (int flags)
       Sets the given flags. Parameters:
           flags the flags to be set

       Returns:
           the new flags status, or -1 if flags can no longer be set

       Definition at line 483 of file kextsock.cpp.

       Referenced by KExtendedSocket().

   int KExtendedSocket::socketFlags () const
       Returns the current flags. Returns:
           the current flags

       See also:
           ::Flags

       Definition at line 491 of file kextsock.cpp.

   bool KExtendedSocket::setHost (const QString & host)
       Sets the hostname to the given value. Parameters:
           host the hostname

       Returns:
           true on success, false on error

       Definition at line 500 of file kextsock.cpp.

       Referenced by setAddress().

   QString KExtendedSocket::host () const
       Returns the hostname. Returns:
           the hostname or QString::null if no host has been set

       Definition at line 512 of file kextsock.cpp.

   bool KExtendedSocket::setPort (int port)
       Sets the port/service. Parameters:
           port the port

       Definition at line 521 of file kextsock.cpp.

       References QString::number().

       Referenced by setAddress().

   bool KExtendedSocket::setPort (const QString & service)
       Sets the port/service. Parameters:
           port the port

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 526 of file kextsock.cpp.

   QString KExtendedSocket::port () const
       Returns the port/service. If it is a port, the string contains a
       number.

       Returns:
           the port or QString::null if it has not been set.

       Definition at line 538 of file kextsock.cpp.

   bool KExtendedSocket::setAddress (const QString & host, int port)
       Sets the address where we will connect to. Parameters:
           host the hostname
           port port number

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 546 of file kextsock.cpp.

       References setHost(), and setPort().

       Referenced by KExtendedSocket().

   bool KExtendedSocket::setAddress (const QString & host, const QString &
       serv)
       Sets the address where we will connect to. Parameters:
           host the hostname
           serv the service

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 554 of file kextsock.cpp.

       References setHost(), and setPort().

   bool KExtendedSocket::setBindHost (const QString & host)
       Sets the hostname to which we will bind locally before connecting.
       Parameters:
           host the hostname

       Returns:
           false if this is a passiveSocket, otherwise true.

       Definition at line 564 of file kextsock.cpp.

       Referenced by setBindAddress().

   bool KExtendedSocket::unsetBindHost ()
       Unsets the bind hostname. That is, don't request a binding host.

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 577 of file kextsock.cpp.

       Referenced by unsetBindAddress().

   QString KExtendedSocket::bindHost () const
       Returns the hostname to which the socket will be/is bound. Returns:
           the host or QString::null if it has not been set.

       Definition at line 589 of file kextsock.cpp.

   bool KExtendedSocket::setBindPort (int port)
       Sets the port/service to which we will bind before connecting.
       Parameters:
           port the port number

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 598 of file kextsock.cpp.

       References QString::number().

       Referenced by setBindAddress().

   bool KExtendedSocket::setBindPort (const QString & service)
       Sets the port/service to which we will bind before connecting.
       Parameters:
           service the port number or service name

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 603 of file kextsock.cpp.

   bool KExtendedSocket::unsetBindPort ()
       Unsets the bind port/service. Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 615 of file kextsock.cpp.

       Referenced by unsetBindAddress().

   QString KExtendedSocket::bindPort () const
       Returns the service to which the socket will be/is bound. Returns:
           the host or QString::null if it has not been set.

       Definition at line 627 of file kextsock.cpp.

   bool KExtendedSocket::setBindAddress (const QString & host, int port)
       Sets both host and port to which we will bind the socket. Will return
       false if this is a passiveSocket.

       Parameters:
           host the hostname
           port the port number

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 635 of file kextsock.cpp.

       References setBindHost(), and setBindPort().

   bool KExtendedSocket::setBindAddress (const QString & host, const QString &
       service)
       Sets both host and service to which we will bind the socket. Will
       return false if this is a passiveSocket.

       Parameters:
           host the hostname
           serv the service

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 643 of file kextsock.cpp.

       References setBindHost(), and setBindPort().

   bool KExtendedSocket::unsetBindAddress ()
       Unsets the bind address for the socket. That means that we won't
       attempt to bind to an address before connecting.

       Returns:
           true if successful, false on error (e.g. connection already
           established)

       Definition at line 651 of file kextsock.cpp.

       References unsetBindHost(), and unsetBindPort().

   bool KExtendedSocket::setTimeout (int secs, int usecs = 0)
       Sets the timeout value for the connection (if this is not
       passiveSocket) or acception (if it is). In the event the given function
       (connect or accept) returns due to time out, it's possible to call it
       again.

       Setting the timeout to 0 disables the timeout feature.

       Parameters:
           secs the timeout length, in seconds
           usecs the timeout complement, in microseconds

       Returns:
           false if setting timeout makes no sense in the context.

       Definition at line 659 of file kextsock.cpp.

   timeval KExtendedSocket::timeout () const
       Returns the timeout value for the connection. Returns:
           the timeout value. 0 if there is no timeout.

       Definition at line 672 of file kextsock.cpp.

   bool KExtendedSocket::setBlockingMode (bool enable)
       Sets/unsets blocking mode for the socket. When non-blocking mode is
       enabled, I/O operations might return error and set errno to
       EWOULDBLOCK. Also, it's not recommended to use this when using the
       class signals.

       Parameters:
           enable if true, set blocking mode. False, non-blocking mode.

       Returns:
           false on error.

       Definition at line 680 of file kextsock.cpp.

       References setError().

       Referenced by accept(), and connect().

   bool KExtendedSocket::blockingMode ()
       Returns the current blocking mode for this socket. Returns:
           true if in blocking mode

       Definition at line 709 of file kextsock.cpp.

       References setError().

       Referenced by accept().

   bool KExtendedSocket::setAddressReusable (bool enable)
       Sets/unsets address reusing flag for this socket. This function returns
       true if the value was set correctly. That is NOT the result of the set.

       Parameters:
           enable if true, set address reusable

       Returns:
           true on success, false on failure. If the socket was not yet
           created, the value is only remembered. In this case the return
           value is always true.

       Definition at line 730 of file kextsock.cpp.

       References setError().

       Referenced by connect(), and listen().

   bool KExtendedSocket::addressReusable ()
       Returns whether this socket's address can be reused. Returns:
           true if the address can be reused

       Definition at line 763 of file kextsock.cpp.

       References setError().

   bool KExtendedSocket::setIPv6Only (bool enable)
       Sets/unsets the v6-only flag for IPv6 sockets. When an IPv6 socket is
       in use, communication with IPv4 sockets is guaranteed by translating
       those IPv4 addresses into IPv6 ones (specifically, the v4-mapped
       addresses). This flag allows that behaviour to be turned on and off.

       Note that this does not have any effect on sockets that are not IPv6
       and the function will always return false in those cases. Also note
       that this flag defaults to off in order to accomodate existing
       applications.

       Parameters:
           enable if true, no IPv4 translation will be performed; this socket
           will be restricted to IPv6 communication

       Returns:
           true on success, false on failure.

       See also:
           localAddress to find out if this is an IPv6 socket

       Definition at line 786 of file kextsock.cpp.

       References setError().

       Referenced by connect(), and listen().

   bool KExtendedSocket::isIPv6Only ()
       Returns the status of the v6-only flag for IPv6 sockets. Returns:
           true if the flag is set to on; false if it is not. If this socket
           is not an IPv6 one, the return value is false.

       See also:
           setIPv6Only

       Definition at line 818 of file kextsock.cpp.

       References setError().

   bool KExtendedSocket::setBufferSize (int rsize, int wsize = -2) [virtual]
       Sets the buffer sizes for this socket. This implementation allows any
       size for both parameters. The value given will be interpreted as the
       maximum size allowed for the buffers, after which the I/O functions
       will stop buffering. The value of -1 will be interpreted as 'unlimited'
       size. The value of -2 means 'no change'.

       Note: changing the buffer size to 0 for any buffer will cause the given
       buffer's to be discarded. Likewise, setting the size to a value less
       than the current size will cause the buffer to be shrunk to the wanted
       value, as if the data had been read.

       Note 2: The closed() signal will only be emitted for a connection
       closed by the remote end if we are doing input buffering. That happens
       because if we aren't reading from the connection, we don't know when it
       closed.

       Parameters:
           rsize read buffer size
           wsize write buffer size

       Returns:
           true on success, false if this is not possible in this state (e.g.
           connection not established yet)

       Reimplemented from KBufferedIO.

       Definition at line 848 of file kextsock.cpp.

       References QObject::connect(), KBufferedIO::consumeReadBuffer(),
       KBufferedIO::consumeWriteBuffer(), QIODevice::mode(),
       KBufferedIO::readBufferSize(), and KBufferedIO::writeBufferSize().

       Referenced by accept(), and connect().

   const  KSocketAddress * KExtendedSocket::localAddress ()
       Returns the local socket address. Returns:
           the local socket address, can be 0 if the connection has not been
           established yet

       Definition at line 950 of file kextsock.cpp.

   const  KSocketAddress * KExtendedSocket::peerAddress ()
       Returns the peer socket address. Use KExtendedSocket::resolve() to
       resolve this to a human-readable hostname/service or port.

       Returns:
           the peer address, can be 0 if the connection has not been
           established yet or the socket is passive

       Definition at line 965 of file kextsock.cpp.

   int KExtendedSocket::fd () const [inline]
       Returns the file descriptor. Returns:
           the file descriptor. -1 if there is no fd yet.

       Definition at line 456 of file kextsock.h.

       Referenced by KServerSocket::slotAccept().

   int KExtendedSocket::lookup () [virtual]
       Performs lookup on the addresses we were given before. This will
       perform lookups on the bind addresses if they were given.

       Returns:
           0 or an error. Do not rely on the values returned by lookup as of
           now. They are not specified.

       Definition at line 978 of file kextsock.cpp.

       References setError().

       Referenced by connect(), and listen().

   int KExtendedSocket::startAsyncLookup () [virtual]
       Starts an asynchronous lookup for the addresses given. When the lookup
       is done, the lookupReady signal will be emitted.

       Note that, depending on the parameters for the lookup, this function
       might know the results without the need for blocking or queueing an
       asynchronous lookup. That means that the lookupReady signal might be
       emitted by this function, so your code should be prepared for that.

       One such case is when noResolve flag is set. If this function is able
       to determine the results without queueing and the lookup failed, this
       function will return -1.

       Returns:
           0 on success or -1 on error. Note that returning 0 means that
           either we are in the process of doing lookup or that it has
           finished already.

       Definition at line 1024 of file kextsock.cpp.

       References QObject::connect(), lookupFinished(), and setError().

       Referenced by startAsyncConnect().

   void KExtendedSocket::cancelAsyncLookup () [virtual]
       Cancels any on-going asynchronous lookups. Definition at line 1097 of
       file kextsock.cpp.

       Referenced by closeNow().

   int KExtendedSocket::listen (int N = 5) [virtual]
       Place the socket in listen mode. The parameters are the same as for the
       system listen() call.

       Parameters:
           N the queue length for pending connections

       Returns:
           0 on success, -1 on system error (errno available) and -2 if this
           is not a passiveSocket.

       Definition at line 1120 of file kextsock.cpp.

       References KSocks::bind(), QObject::connect(), KSocks::listen(),
       lookup(), KSocks::self(), setAddressReusable(), setError(), and
       setIPv6Only().

       Referenced by accept(), and open().

   int KExtendedSocket::accept (KExtendedSocket *& sock) [virtual]
       Accepts an incoming connection from the socket. If this socket is in
       blocking mode, this function will block until a connection is received.
       Otherwise, it might return with error. The sock parameter will be
       initialised with the newly created socket.

       Upon successful acception (i.e., this function returns 0), the newly
       created socket will be already connected. The socket will be unbuffered
       and readyRead() and readyWrite() signals will be disabled.

       Parameters:
           sock a pointer to an KExtendedSocket variable

       Returns:
           0 on success, -1 on system error (errno set) and -2 if this is not
           a passiveSocket and -3 if this took too long (time out)

       Definition at line 1189 of file kextsock.cpp.

       References KSocks::accept(), blockingMode(), d, listen(),
       KSocks::select(), KSocks::self(), setBlockingMode(), setBufferSize(),
       setError(), and sockfd.

   int KExtendedSocket::connect () [virtual]
       Attempts to connect to the remote host. After successful connection
       (return value 0), the socket will be ready for I/O operations. Note,
       however, that not all signals may be enabled for emission by this
       socket:

       · readyRead and readyWrite signals will be enabled only if enableRead
         or enableWrite were called. You can still enable them by calling
         those functions, of course.

       · closed() will only be sent if we are indeed reading from the input
         stream. That is, if this socket is buffering the input. See
         setBufferSize

       Note that, in general, functions inherited/overriden from KBufferedIO
       will only work on buffered sockets, like bytesAvailable and
       bytesToWrite.

       Returns:
           The return values are:

           · 0: success

           · -1: system error, errno was set accordingly

           · -2: this socket cannot connect(); this is a passiveSocket. It can
             also mean that the function was unable to make a connection with
             the given bind address or that an asynchronous connection attempt
             is already in progress.

           · -3: connection timed out

       Definition at line 1261 of file kextsock.cpp.

       References KSocks::bind(), KSocks::connect(), connectionFailed(),
       connectionSuccess(), KStdAccel::end(),
       KSocks::hasWorkingAsyncConnect(), lookup(), KSocks::select(),
       KSocks::self(), setAddressReusable(), setBlockingMode(),
       setBufferSize(), setError(), and setIPv6Only().

       Referenced by open().

   int KExtendedSocket::startAsyncConnect () [virtual]
       Starts an asynchronous connect. This works exactly the same as connect,
       except that the connection result won't be returned.

       Note that those signals might be emitted before this function returns,
       so your code should be prepared for that condition.

       Returns:
           0 on successful queueing of the connect or -1 on error. If this
           function returns 0, then the connectionSuccess() or the
           connectionFailed() signals will be emitted.

       Definition at line 1477 of file kextsock.cpp.

       References QObject::connect(), lookupFinished(), and
       startAsyncLookup().

   void KExtendedSocket::cancelAsyncConnect () [virtual]
       Cancels any on-going asynchronous connection attempt. Definition at
       line 1512 of file kextsock.cpp.

       Referenced by closeNow().

   bool KExtendedSocket::open (int mode = IO_Raw|IO_ReadWrite) [virtual]
       Implementation of QIODevice::open() pure virtual function. This depends
       on the target host address already being there. If this is a
       passiveSocket, this is identical to call listen(); else, if this is not
       a passiveSocket and no connection attempt is in progress, this is like
       connect(). If one is in progress, this function will fail.

       Parameters:
           mode the open mode. Must be IO_Raw | IO_ReadWrite

       Returns:
           true if successful, false when an error occurred or the most was
           not correct

       Reimplemented from QIODevice.

       Definition at line 1532 of file kextsock.cpp.

       References connect(), and listen().

   void KExtendedSocket::close () [virtual]
       Closes the socket. If we have data still in the write buffer yet to be
       sent, the socket won't be closed right now. It'll be closed after we
       managed to send everything out. If you want to close the socket now,
       you may want to call flush() first, and then closeNow(). Reimplemented
       from QIODevice.

       Definition at line 1545 of file kextsock.cpp.

       References KBufferedIO::closed(), KBufferedIO::readBufferSize(), and
       KBufferedIO::writeBufferSize().

   void KExtendedSocket::closeNow () [virtual]
       Closes the socket now, discarding the contents of the write buffer, if
       any. The read buffer's contents are kept until they are emptied by read
       operations or the class is destroyed. Implements KBufferedIO.

       Definition at line 1579 of file kextsock.cpp.

       References cancelAsyncConnect(), cancelAsyncLookup(),
       KBufferedIO::closed(), KBufferedIO::readBufferSize(), and
       KBufferedIO::writeBufferSize().

       Referenced by reset(), and ~KExtendedSocket().

   void KExtendedSocket::release () [virtual]
       Releases the socket and anything we have holding on it. The class
       cannot be used anymore. In other words, this is just like closeNow(),
       but it does not actually close the socket.

       This is useful if you just want to connect and don't need the rest of
       the class.

       Note that the buffers' contents will be discarded.

       Use of this method is discouraged, because the socket created might be
       such that normal library routines can't handle (read, write, close,
       etc.) Definition at line 1606 of file kextsock.cpp.

       References KBufferedIO::consumeReadBuffer(),
       KBufferedIO::consumeWriteBuffer(), KBufferedIO::readBufferSize(), and
       KBufferedIO::writeBufferSize().

       Referenced by reset(), and KServerSocket::slotAccept().

   void KExtendedSocket::flush () [virtual]
       Flushes the socket buffer. You need not call this method during normal
       operation as we will try and send everything as soon as possible.
       However, if you want to make sure that data in the buffer is being sent
       at this moment, you can call this function. It will try to send as much
       data as possible, but it will stop as soon as the kernel cannot receive
       any more data, and would possibly block.

       By repeatedly calling this function, the behaviour will be like that of
       a blocking socket. Indeed, if this function is called with the kernel
       not ready to receive data, it will block, unless this is a non-blocking
       socket.

       This function does not touch the read buffer. You can empty it by
       calling readBlock() with a null destination buffer. Reimplemented from
       QIODevice.

       Definition at line 1640 of file kextsock.cpp.

       References KBufferedIO::bytesWritten(),
       KBufferedIO::consumeWriteBuffer(), QPtrList< QByteArray >::first(),
       QPtrList< QByteArray >::next(), KBufferedIO::outBuf, KSocks::self(),
       setError(), KSocks::write(), and KBufferedIO::writeBufferSize().

   virtual Q_ULONG KExtendedSocket::size () const [inline, virtual]
       Returns length of this socket. This call is not supported on sockets.

       Returns:
           the length of this socket, or 0 if unsupported

       Reimplemented from QIODevice.

       Definition at line 632 of file kextsock.h.

   virtual Q_ULONG KExtendedSocket::at () const [inline, virtual]
       Returns relative position from start. This call is not supported on
       sockets.

       Returns:
           the relative position from the start, or 0 if unsupported

       Reimplemented from QIODevice.

       Definition at line 639 of file kextsock.h.

   virtual bool KExtendedSocket::at (int i) [inline, virtual]
       Returns true if we are at position. This is not supported on sockets.

       Parameters:
           i the position to check

       Returns:
           true if we art at the given position, or always true if
           unsupported.

       Definition at line 647 of file kextsock.h.

   virtual bool KExtendedSocket::atEnd () const [inline, virtual]
       Returns true if we are at the end. This is not supported on sockets,
       but we always are at the end in a socket...

       Returns:
           true if we are at the end. Always false if unsupported.

       Reimplemented from QIODevice.

       Definition at line 655 of file kextsock.h.

   Q_LONG KExtendedSocket::readBlock (char * data, Q_ULONG maxlen) [virtual]
       Reads a block of data from the socket. If the socket is not buffered,
       this function will simply call the underlying read method. This
       function will block if the socket is not on non-blocking mode (see
       setBlockingMode) and there is not enough data to be read in the
       Operating System yet. If we are in non-blocking operation, the call
       will fail in this case.

       However, if we are buffering, this function will instead read from the
       buffer while there is available data. This function will never block in
       buffering mode, which means that if you try to read while the buffers
       are empty, this function will always return -1 and set the system error
       to EWOULDBLOCK (aka EAGAIN), so as to mimic non-blocking operation.

       Parameters:
           data where we will write the read data to
           maxlen maximum length of data to be read

       Returns:
           the number of bytes effectively read, or a negative number in case
           or an error. If the data param is not null, then this is also the
           number of bytes copied into that buffer. If the return value is
           different than maxlen, then this function encountered a situation
           in which no more bytes were available. Subsequent calls might cause
           this function to one of these behaviours:

           · return an error, with EWOULDBLOCK system error, if we buffering
             or we are in non-blocking mode

           · otherwise, it'll block This function returns 0, if the function
             detected end-of-file condition (socket was closed)

       Reimplemented from QIODevice.

       Definition at line 1699 of file kextsock.cpp.

       References KBufferedIO::consumeReadBuffer(), KSocks::read(),
       KSocks::self(), and setError().

       Referenced by getch().

   Q_LONG KExtendedSocket::writeBlock (const char * data, Q_ULONG len)
       [virtual]
       Writes a block of data to the socket. If the socket is not buffered,
       this function will simply call the underlying write method. This means
       that the function might block if that method blocks as well. That
       situation is possible if we are not in non-blocking mode and the
       operating system buffers are full for this socket. If we are in non-
       blocking mode and the operating system buffers are full, this function
       will return -1 and the system error will be set to EWOULDBLOCK.

       If we are buffering, this function will simply transfer the data into
       the write buffer. This function will then always succeed, as long as
       there is enough room in the buffer. If the buffer size was limited and
       that limit is reached, this function will copy no more bytes than that
       limit. Trying to write with a full buffer will return -1 and set system
       error to EWOULDBLOCK.

       Parameters:
           data the data to write
           len the length of data to write

       Returns:
           the number of bytes written from data buffer. The return value
           might be less than len if the output buffers cannot accommodate
           that many bytes and -1 in the case of an errro.

       Reimplemented from QIODevice.

       Definition at line 1744 of file kextsock.cpp.

       References KBufferedIO::bytesWritten(), KBufferedIO::feedWriteBuffer(),
       KSocks::self(), setError(), KSocks::write(), and
       KBufferedIO::writeBufferSize().

       Referenced by putch().

   int KExtendedSocket::peekBlock (char * data, uint maxlen) [virtual]
       Peeks at a block of data from the socket. This is exactly like read,
       except that the data won't be flushed from the read buffer.

       If this socket is not buffered, this function will always return with 0
       bytes copied.

       Parameters:
           data where to store the data
           maxlen how many bytes to copy, at most

       Returns:
           the number of bytes copied. 0 does not mean end-of-file condition.

       Implements KBufferedIO.

       Definition at line 1798 of file kextsock.cpp.

       References KBufferedIO::consumeReadBuffer().

   int KExtendedSocket::unreadBlock (const char * data, uint len) [virtual]
       Reimplementation of unreadBlock() method. This is so because unreading
       in sockets doesn't make sense, so this function will always return -1
       (error) and set the system error to ENOSYS.

       Returns:
           always -1 (error)

       Reimplemented from KBufferedIO.

       Definition at line 1813 of file kextsock.cpp.

       References setError().

   int KExtendedSocket::bytesAvailable () const [virtual]
       Returns the number of available bytes yet to be read via readBlock and
       family of functions. Note: as of now, this only works on input-buffered
       sockets. This will change in the future

       Returns:
           The number of available bytes, or -1 on error or -2 if this call is
           invalid in the current state.

       Reimplemented from KBufferedIO.

       Definition at line 1820 of file kextsock.cpp.

       References KBufferedIO::bytesAvailable().

       Referenced by waitForMore().

   int KExtendedSocket::waitForMore (int msec) [virtual]
       Waits msec milliseconds for more data to be available (use 0 to wait
       forever). The return value is the amount of data available for read in
       the read buffer.

       Parameters:
           msec milliseconds to wait

       Returns:
           -1 in case of system error and -2 in case of invalid socket state

       Implements KBufferedIO.

       Definition at line 1833 of file kextsock.cpp.

       References bytesAvailable(), KSocks::select(), KSocks::self(), and
       setError().

   int KExtendedSocket::getch () [virtual]
       Gets a single character (unsigned char) from the stream. Returns:
           the value of the character. Negative if there was an error.

       Reimplemented from QIODevice.

       Definition at line 1860 of file kextsock.cpp.

       References readBlock().

   int KExtendedSocket::putch (int ch) [virtual]
       Writes a single character (unsigned char) to the stream. All other bits
       will be ignored.

       Parameters:
           ch character to write, converted to char

       Reimplemented from QIODevice.

       Definition at line 1871 of file kextsock.cpp.

       References writeBlock().

   virtual int KExtendedSocket::ungetch (int) [inline, virtual]
       Unreads one character from the stream. This is not possible on sockets.

       Returns:
           always returns -1 on sockets.

       Reimplemented from QIODevice.

       Definition at line 777 of file kextsock.h.

   void KExtendedSocket::enableRead (bool enable) [virtual]
       Toggles the emission of the readyRead signal. Note that this signal is
       emitted every time more data is available to be read, so you might get
       flooded with it being emitted every time, when in non-buffered mode.
       However, in buffered mode, this signal will be emitted only when there
       is data coming in from the wire. By default, this flag is set to false,
       i.e., signal not being emitted.

       Parameters:
           enable if true, the signal will be emitted

       Implements KAsyncIO.

       Definition at line 1911 of file kextsock.cpp.

   void KExtendedSocket::enableWrite (bool enable) [virtual]
       Toggles the emission of the readyWrite signal. Note that this signal is
       emitted only when the OS is ready to receive more data, which means
       that the write buffer is empty. And when that is reached, this signal
       will possibly be emitted on every loop, so you might want to disable
       it. By default, this flag is set to false.

       Parameters:
           enable if true, the signal will be emitted

       Implements KAsyncIO.

       Definition at line 1926 of file kextsock.cpp.

   void KExtendedSocket::lookupFinished (int count) [signal]
       This signal is emitted whenever an asynchronous lookup process is done.
       The parameter count tells

       Parameters:
           count the number of results

       Referenced by startAsyncConnect(), and startAsyncLookup().

   void KExtendedSocket::connectionSuccess () [signal]
       This signal is emitted whenever we connected asynchronously to a host.
       Referenced by connect().

   void KExtendedSocket::connectionFailed (int error) [signal]
       This signal is emitted whenever our asynchronous connection attempt
       failed to all hosts listed. Parameters:
           error the errno code of the last connection attempt

       Referenced by connect().

   void KExtendedSocket::readyAccept () [signal]
       This signal is emitted whenever this socket is ready to accept another
       socket. See also:
           accept()

   void KExtendedSocket::setError (int errorkind, int error) [protected]
       Sets the error code. Definition at line 468 of file kextsock.cpp.

       Referenced by accept(), addressReusable(), blockingMode(), connect(),
       flush(), isIPv6Only(), listen(), lookup(), readBlock(),
       setAddressReusable(), setBlockingMode(), setIPv6Only(),
       startAsyncLookup(), unreadBlock(), waitForMore(), and writeBlock().

   void KExtendedSocket::setSocketStatus (int status) [protected]
       Sets the socket status. For derived classes only. Definition at line
       463 of file kextsock.cpp.

   int KExtendedSocket::resolve (sockaddr * sock, ksocklen_t len, QString &
       host, QString & port, int flags = 0) [static]
       Performs resolution on the given socket address. That is, tries to
       resolve the raw form of the socket address into a textual
       representation.

       Parameters:
           sockaddr the socket address
           host where the hostname will be written
           port where the service-port will be written
           flags the same flags as getnameinfo()

       Returns:
           0 on success, nonzero otherwise.

       Definition at line 2258 of file kextsock.cpp.

       References QString::fromUtf8().

       Referenced by resolve().

   int KExtendedSocket::resolve (KSocketAddress * sock, QString & host,
       QString & port, int flags = 0) [static]
       Performs resolution on the given socket address. That is, tries to
       resolve the raw form of the socket address into a textual
       representation.

       Parameters:
           sockaddr the socket address
           host where the hostname will be written
           port where the service-port will be written
           flags the same flags as getnameinfo()

       Returns:
           0 on success, nonzero otherwise.

       Definition at line 2273 of file kextsock.cpp.

       References KSocketAddress::data, KSocketAddress::datasize, and
       resolve().

   QPtrList< KAddressInfo > KExtendedSocket::lookup (const QString & host,
       const QString & port, int flags = 0, int * error = 0) [static]
       Performs lookup on the given hostname/port combination and returns a
       list of matching addresses. The error code can be transformed into
       string by KExtendedSocket::strError() with code of IO_LookupError.

       IMPORTANT: the result values of the QPtrList must be deleted after use.
       So, if you don't copy the KAddressInfo objects, the best way to assure
       that is to call setAutoDelete(true) on the list right after this
       function returns. If you do copy the results out, you must assure that
       the objects get deleted when they are not needed any more.

       Parameters:
           host the hostname to look up
           port the port/service to look up
           flags flags to be used when looking up, Flags
           error pointer to a variable holding the error code

       Returns:
           a list of KAddressInfos

       Definition at line 2279 of file kextsock.cpp.

       References QPtrList::append().

   KSocketAddress * KExtendedSocket::localAddress (int fd) [static]
       Returns the local socket address Remember to delete the returned object
       when it is no longer needed. Parameters:
           fd the file descriptor

       Returns:
           the local socket address or 0 if an error occurred. Delete after
           use.

       Definition at line 2320 of file kextsock.cpp.

       References KSocks::getsockname(), KSocketAddress::newAddress(), and
       KSocks::self().

   KSocketAddress * KExtendedSocket::peerAddress (int fd) [static]
       Returns the peer socket address. Use KExtendedSocket::resolve() to
       resolve this to a human-readable hostname/service or port. Remember to
       delete the returned object when it is no longer needed.

       Parameters:
           fd the file descriptor

       Returns:
           the peer socket address or 0 if an error occurred. Delete after
           use.

       Definition at line 2368 of file kextsock.cpp.

       References KSocks::getpeername(), KSocketAddress::newAddress(), and
       KSocks::self().

   QString KExtendedSocket::strError (int code, int syserr) [static]
       Returns the representing text of this error code. Parameters:
           code the error code, as seen in status()
           syserr the system error, as from systemError()

       Returns:
           the text for the given error code

       Definition at line 2414 of file kextsock.cpp.

       References QString::fromLocal8Bit().

   bool KExtendedSocket::setAddressReusable (int fd, bool enable) [static]
       Sets/unsets address reusing flag for this socket. This function returns
       true if the value was set correctly. That is NOT the result of the set.

       Parameters:
           fd the file descriptor
           enable if true, set address reusable

       Returns:
           true on success, false on failure.

       Definition at line 748 of file kextsock.cpp.


Author
       Generated automatically by Doxygen for kdecore Library from the source
       code.




kdecore Library                   28 Jan 2004               KExtendedSocket(3)