kdecore Library API Documentation

KExtendedSocket Class Reference

The extended socket class. an extended socket. More...

#include <kextsock.h>

Inheritance diagram for KExtendedSocket:

KBufferedIO KAsyncIO QObject QIODevice List of all members.

Public Types

enum  Flags
 flags that can be passed down to the member functions More...

enum  SockStatus
 status of the class The status are sequential. More...


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 Methods

 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.

virtual bool setBufferSize (int rsize, int wsize=-2)
 Sets the buffer sizes for this socket.

const KSocketAddresslocalAddress ()
 Returns the local socket address.

const KSocketAddresspeerAddress ()
 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 Methods

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< KAddressInfolookup (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.

KSocketAddresslocalAddress (int fd)
 Returns the local socket address Remember to delete the returned object when it is no longer needed.

KSocketAddresspeerAddress (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 Methods

void setError (int errorkind, int error)
 Sets the error code.

void setSocketStatus (int status)
 Sets the socket status.

virtual void virtual_hook (int id, void *data)

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:
kextsock.h,v 1.30.2.1 2003/01/03 00:14:05 malte 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 402 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 408 of file kextsock.cpp.

References QIODevice::flags(), port(), 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 416 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 424 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 444 of file kextsock.cpp.

References closeNow(), and release().

int KExtendedSocket::socketStatus  
 

Returns the class status.

Returns:
the class status
See also:
SockStatus

Definition at line 453 of file kextsock.cpp.

int KExtendedSocket::systemError  
 

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 469 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 478 of file kextsock.cpp.

References QIODevice::flags().

Referenced by KExtendedSocket().

int KExtendedSocket::socketFlags  
 

Returns the current flags.

Returns:
the current flags
See also:
Flags

Definition at line 486 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 495 of file kextsock.cpp.

Referenced by setAddress().

QString KExtendedSocket::host  
 

Returns the hostname.

Returns:
the hostname or QString::null if no host has been set

Definition at line 507 of file kextsock.cpp.

bool KExtendedSocket::setPort int    port
 

Sets the port/service.

Parameters:
port  the port

Definition at line 516 of file kextsock.cpp.

References QString::number(), and port().

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 521 of file kextsock.cpp.

QString KExtendedSocket::port  
 

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 533 of file kextsock.cpp.

Referenced by KExtendedSocket(), setAddress(), setBindAddress(), setBindPort(), and setPort().

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 541 of file kextsock.cpp.

References port(), 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 549 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 559 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 572 of file kextsock.cpp.

Referenced by unsetBindAddress().

QString KExtendedSocket::bindHost  
 

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 584 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 593 of file kextsock.cpp.

References QString::number(), and port().

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 598 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 610 of file kextsock.cpp.

Referenced by unsetBindAddress().

QString KExtendedSocket::bindPort  
 

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 622 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 630 of file kextsock.cpp.

References port(), 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 638 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 646 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 654 of file kextsock.cpp.

timeval KExtendedSocket::timeout  
 

Returns the timeout value for the connection.

Returns:
the timeout value. 0 if there is no timeout.

Definition at line 667 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 675 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 704 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 725 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 758 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 782 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 884 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 899 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 428 of file kextsock.h.

Referenced by localAddress(), peerAddress(), setAddressReusable(), and 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 912 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 958 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 1031 of file kextsock.cpp.

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 1054 of file kextsock.cpp.

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

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 1121 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:

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 1193 of file kextsock.cpp.

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

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 1403 of file kextsock.cpp.

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

void KExtendedSocket::cancelAsyncConnect   [virtual]
 

Cancels any on-going asynchronous connection attempt.

Definition at line 1438 of file kextsock.cpp.

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 1458 of file kextsock.cpp.

References connect(), listen(), and QIODevice::mode().

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 1471 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 1505 of file kextsock.cpp.

References 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 1525 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 1559 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

Definition at line 604 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

Definition at line 611 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 619 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.

Definition at line 627 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 1618 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 1661 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 1715 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 1730 of file kextsock.cpp.

References setError().

int KExtendedSocket::bytesAvailable   [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 1737 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 1750 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 1777 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 1788 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 749 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 1828 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 1843 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 463 of file kextsock.cpp.

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

void KExtendedSocket::setSocketStatus int    status [protected]
 

Sets the socket status.

For derived classes only.

Definition at line 458 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 2168 of file kextsock.cpp.

References QIODevice::flags(), and 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 2183 of file kextsock.cpp.

References KSocketAddress::data, KSocketAddress::datasize, QIODevice::flags(), 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 2189 of file kextsock.cpp.

References QPtrList::append(), and QIODevice::flags().

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 2230 of file kextsock.cpp.

References fd(), 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 2278 of file kextsock.cpp.

References fd(), 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 2324 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 743 of file kextsock.cpp.

References fd().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:20:45 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001