• Skip to content
  • Skip to link menu
KDE 4.1 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KDECore

KNetwork::KSocketBase

KNetwork::KSocketBase Class Reference

#include <k3socketbase.h>

Inheritance diagram for KNetwork::KSocketBase:

Inheritance graph
[legend]

List of all members.


Detailed Description

Basic socket functionality.

This class provides the basic socket functionlity for descended classes. Socket classes are thread-safe and provide a recursive mutex should it be needed.

Note:
This class is abstract.
Author:
Thiago Macieira <thiago@kde.org>

Definition at line 84 of file k3socketbase.h.


Public Types

enum  SocketError {
  NoError = 0, LookupFailure, AddressInUse, AlreadyCreated,
  AlreadyBound, AlreadyConnected, NotConnected, NotBound,
  NotCreated, WouldBlock, ConnectionRefused, ConnectionTimedOut,
  InProgress, NetFailure, NotSupported, Timeout,
  UnknownError, RemotelyDisconnected
}
enum  SocketOptions {
  Blocking = 0x01, AddressReuseable = 0x02, IPv6Only = 0x04, Keepalive = 0x08,
  Broadcast = 0x10, NoDelay = 0x20
}

Public Member Functions

bool addressReuseable () const
bool blocking () const
bool broadcast () const
SocketError error () const
QString errorString () const
bool isIPv6Only () const
 KSocketBase ()
QMutex * mutex () const
bool noDelay () const
virtual bool setAddressReuseable (bool enable)
virtual bool setBlocking (bool enable)
virtual bool setBroadcast (bool enable)
virtual bool setIPv6Only (bool enable)
virtual bool setNoDelay (bool enable)
int setRequestedCapabilities (int add, int remove=0)
virtual void setSocketDevice (KSocketDevice *device)
KSocketDevice * socketDevice () const
virtual ~KSocketBase ()

Static Public Member Functions

static QString errorString (SocketError code)
static bool isFatalError (int code)

Protected Member Functions

bool hasDevice () const
void resetError ()
void setError (SocketError error)
virtual bool setSocketOptions (int opts)
virtual int socketOptions () const

Member Enumeration Documentation

enum KNetwork::KSocketBase::SocketError

Possible socket error codes.

This is a list of possible error conditions that socket classes may be expected to find.

  • NoError: no error has been detected
  • LookupFailure: if a name lookup has failed
  • AddressInUse: address is already in use
  • AlreadyBound: cannot bind again
  • AlreadyCreated: cannot recreate the socket
  • NotBound: operation required socket to be bound and it isn't
  • NotCreated: operation required socket to exist and it doesn't
  • WouldBlock: requested I/O operation would block
  • ConnectionRefused: connection actively refused
  • ConnectionTimedOut: connection timed out
  • InProgress: operation (connection) is already in progress
  • NetFailure: a network failure occurred (no route, host down, host unreachable or similar)
  • NotSupported: requested operation is not supported
  • Timeout: a timed operation timed out
  • UnknownError: an unknown/unexpected error has happened
  • RemotelyDisconnected: when a connection is disconnected by the other end (since 3.4)

See also:
error, errorString
Enumerator:
NoError 
LookupFailure 
AddressInUse 
AlreadyCreated 
AlreadyBound 
AlreadyConnected 
NotConnected 
NotBound 
NotCreated 
WouldBlock 
ConnectionRefused 
ConnectionTimedOut 
InProgress 
NetFailure 
NotSupported 
Timeout 
UnknownError 
RemotelyDisconnected 

Definition at line 142 of file k3socketbase.h.

enum KNetwork::KSocketBase::SocketOptions

Possible socket options.

These are the options that may be set on a socket:

  • Blocking: whether the socket shall operate in blocking or non-blocking mode. This flag defaults to on. See setBlocking.
  • AddressReusable: whether the address used by this socket will be available for reuse by other sockets. This flag defaults to off. See setAddressReuseable.
  • IPv6Only: whether an IPv6 socket will accept IPv4 connections through a mapped address. This flag defaults to off. See setIPv6Only.
  • KeepAlive: whether TCP should send keepalive probes when a connection has gone idle for far too long.
  • Broadcast: whether this socket is allowed to send broadcast packets and will receive packets sent to broadcast.
  • NoDelay: disable the Nagle algorithm for socket types that support it.
Enumerator:
Blocking 
AddressReuseable 
IPv6Only 
Keepalive 
Broadcast 
NoDelay 

Definition at line 107 of file k3socketbase.h.


Constructor & Destructor Documentation

KSocketBase::KSocketBase (  ) 

Default constructor.

Definition at line 68 of file k3socketbase.cpp.

KSocketBase::~KSocketBase (  )  [virtual]

Destructor.

Definition at line 80 of file k3socketbase.cpp.


Member Function Documentation

bool KSocketBase::addressReuseable (  )  const

Retrieves this socket's address reuseability flag.

Returns:
true if this socket's address can be reused, false if it can't.

Definition at line 112 of file k3socketbase.cpp.

bool KSocketBase::blocking (  )  const

Retrieves this socket's blocking mode.

Returns:
true if this socket is/will be operated in blocking mode, false if non-blocking.

Definition at line 102 of file k3socketbase.cpp.

bool KSocketBase::broadcast (  )  const

Retrieves this socket's Broadcast flag.

Returns:
true if this socket can send and receive broadcast packets, false if it can't.

Definition at line 132 of file k3socketbase.cpp.

KSocketBase::SocketError KSocketBase::error (  )  const

Retrieves the socket error code.

See also:
errorString

Definition at line 197 of file k3socketbase.cpp.

QString KSocketBase::errorString ( KSocketBase::SocketError  code  )  [static]

Returns the string describing the given error code, i18n'ed.

Parameters:
code the error code

Definition at line 208 of file k3socketbase.cpp.

QString KSocketBase::errorString (  )  const

Returns the error string corresponding to this error condition.

Reimplemented in KNetwork::KActiveSocketBase.

Definition at line 202 of file k3socketbase.cpp.

bool KSocketBase::hasDevice (  )  const [protected]

Returns true if the socket device has been initialised in this object, either by calling socketDevice() or setSocketDevice.

Definition at line 182 of file k3socketbase.cpp.

bool KSocketBase::isFatalError ( int  code  )  [static]

Returns true if the given error code is a fatal one, false otherwise.

The parameter here is of type int so that casting isn't necessary when using the parameter to signal QClientSocketBase::gotError.

Parameters:
code the code to test

Definition at line 301 of file k3socketbase.cpp.

bool KSocketBase::isIPv6Only (  )  const

Retrieves this socket's IPv6 Only flag.

Returns:
true if this socket will ignore IPv4-compatible and IPv4-mapped addresses, false if it will accept them.

Definition at line 122 of file k3socketbase.cpp.

QMutex * KSocketBase::mutex (  )  const

Returns the internal mutex for this class.

Note on multithreaded use of sockets: the socket classes are thread-safe by design, but you should be aware of problems regarding socket creation, connection and destruction in multi-threaded programs. The classes are guaranteed to work while the socket exists, but it's not wise to call connect in multiple threads.

Also, this mutex must be unlocked before the object is destroyed, which means you cannot use it to guard against other threads accessing the object while destroying it. You must ensure there are no further references to this object when deleting it.

Definition at line 320 of file k3socketbase.cpp.

bool KSocketBase::noDelay (  )  const

Retrieves this socket's NoDelay flag.

Returns:
true if this socket's Nagle algorithm is disabled.

Definition at line 142 of file k3socketbase.cpp.

void KSocketBase::resetError (  )  [protected]

Resets the socket error code and the I/O Device's status.

Reimplemented in KNetwork::KActiveSocketBase.

Definition at line 192 of file k3socketbase.cpp.

bool KSocketBase::setAddressReuseable ( bool  enable  )  [virtual]

Sets this socket's address reuseable flag.

When the address reuseable flag is active, the address used by this socket is left reuseable for other sockets to bind. If the flag is not active, no other sockets may reuse the same address.

The default implementation toggles the AddressReuseable flag with the current socket options and calls setSocketOptions.

Parameters:
enable whether to set the flag on or off
Returns:
true if setting this flag was successful

Definition at line 107 of file k3socketbase.cpp.

bool KSocketBase::setBlocking ( bool  enable  )  [virtual]

Sets this socket's blocking mode.

In blocking operation, all I/O functions are susceptible to blocking -- i.e., will not return unless the I/O can be satisfied. In non-blocking operation, if the I/O would block, the function will return an error and set the corresponding error code.

The default implementation toggles the Blocking flag with the current socket options and calls setSocketOptions.

Parameters:
enable whether to set this socket to blocking mode
Returns:
whether setting this value was successful; it is NOT the final blocking mode.

Definition at line 97 of file k3socketbase.cpp.

bool KSocketBase::setBroadcast ( bool  enable  )  [virtual]

Sets this socket Broadcast flag.

Datagram-oriented sockets cannot normally send packets to broadcast addresses, nor will they receive packets that were sent to a broadcast address. To do so, you need to enable the Broadcast flag.

This option has no effect on stream-oriented sockets.

Returns:
true if setting this flag was successful.

Definition at line 127 of file k3socketbase.cpp.

void KSocketBase::setError ( SocketError  error  )  [protected]

Sets the socket's error code.

Parameters:
error the error code

Reimplemented in KNetwork::KActiveSocketBase.

Definition at line 187 of file k3socketbase.cpp.

bool KSocketBase::setIPv6Only ( bool  enable  )  [virtual]

Sets this socket's IPv6 Only flag.

When this flag is on, an IPv6 socket will only accept, connect, send to or receive from IPv6 addresses. When it is off, it will also talk to IPv4 addresses through v4-mapped addresses.

This option has no effect on non-IPv6 sockets.

The default implementation toggles the IPv6Only flag with the current socket options and calls setSocketOptions.

Parameters:
enable whether to set the flag on or off
Returns:
true if setting this flag was successful

Definition at line 117 of file k3socketbase.cpp.

bool KSocketBase::setNoDelay ( bool  enable  )  [virtual]

Sets this socket's NoDelay flag.

Stream-oriented protocols, like TCP, have an internal algorithm (called Nagle's algorithm) that collects data in a buffer so that the transmission doesn't occur after every single write operation. The side-effect is that the transmission of short messages is delayed.

Setting NoDelay to 'true' will disable this algorithm.

Returns:
true if setting this flag was successful.

Definition at line 137 of file k3socketbase.cpp.

int KSocketBase::setRequestedCapabilities ( int  add,
int  remove = 0 
)

Sets the internally requested capabilities for a socket device.

Most socket classes can use any back-end implementation. However, a few may require specific capabilities not provided in the default implementation. By using this function, derived classes can request that a backend with those capabilities be created when necessary.

For the possible flags, see KSocketDevice::Capabilities. However, note that only the Can* flags make sense in this context.

Note:
Since socketDevice must always return a valid backend object, it is is possible that the created device does not conform to all requirements requested. Implementations sensitive to this fact should test the object returned by socketDevice (through KSocketDevice::capabilities, for instance) the availability.
Parameters:
add mask of KSocketDevice::Capabilities to add
remove mask of bits to remove from the requirements
Returns:
the current mask of requested capabilities

Definition at line 175 of file k3socketbase.cpp.

void KSocketBase::setSocketDevice ( KSocketDevice *  device  )  [virtual]

Sets the socket implementation to be used on this socket.

Note: it is an error to set this if the socket device has already been set once.

This function is provided virtual so that derived classes can catch the setting of a device and properly set their own states and internal variables. The parent class must be called.

This function is called by socketDevice above when the socket is first created.

Reimplemented in KNetwork::KBufferedSocket, and KNetwork::KActiveSocketBase.

Definition at line 168 of file k3socketbase.cpp.

bool KSocketBase::setSocketOptions ( int  opts  )  [protected, virtual]

Set the given socket options.

The default implementation does nothing but store the mask internally. Descended classes must override this function to achieve functionality and must also call this implementation.

Parameters:
opts a mask of SocketOptions or-ed bits of options to set or unset
Returns:
true on success
Note:
this function sets the options corresponding to the bits enabled in opts but will also unset the optiosn corresponding to the bits not set.

Reimplemented in KNetwork::KBufferedSocket, KNetwork::KClientSocketBase, KNetwork::KServerSocket, and KNetwork::KSocketDevice.

Definition at line 86 of file k3socketbase.cpp.

KSocketDevice * KSocketBase::socketDevice (  )  const

Retrieves the socket implementation used on this socket.

This function creates the device if none has been set using the default factory.

Definition at line 148 of file k3socketbase.cpp.

int KSocketBase::socketOptions (  )  const [protected, virtual]

Retrieves the socket options that have been set.

The default implementation just retrieves the mask from an internal variable. Descended classes may choose to override this function to read the values from the operating system.

Returns:
the mask of the options set

Definition at line 92 of file k3socketbase.cpp.


The documentation for this class was generated from the following files:
  • k3socketbase.h
  • k3socketbase.cpp

KDECore

Skip menu "KDECore"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • KIO
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal