class KExtendedSocket

an extended socket. More...

List of all Methods
Definition	`#include <kextsock.h>`
Inherits	QIODevice (qt), QObject (qt)


	Annotated List
	Files
	Globals
	Hierarchy
	Index

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, unixSocketKeep = 0x100000 }
enum SockStatus {error = -1, nothing = 0, lookupDone = 1, created = 2, bound = 3, connecting = 4, connected = 5, listening = 4, accepting = 5, closed = 6 }

Public Methods

KExtendedSocket ()
KExtendedSocket (const QString& host, int port, int flags = 0)
KExtendedSocket (const QString& host, const QString& service, int flags = 0)
virtual ~ KExtendedSocket ()
inline int socketStatus () const
inline int systemError () const
int setSocketFlags (int flags)
inline int socketFlags () const
bool setHost (const QString& host)
QString host () const
bool setPort (int port)
bool setPort (const QString& service)
QString port () const
bool setAddress (const QString& host, int port)
bool setAddress (const QString& host, const QString& serv)
bool setBindHost (const QString& host)
bool unsetBindHost ()
inline QString bindHost () const
bool setBindPort (int port)
bool setBindPort (const QString& service)
bool unsetBindPort ()
QString bindPort () const
bool setBindAddress (const QString& host, int port)
bool setBindAddress (const QString& host, const QString& service)
bool unsetBindAddress ()
bool setTimeout (int secs, int usecs = 0)
timeval timeout () const
bool setBlockingMode (bool enable)
bool blockingMode ()
KSocketAddress * localAddress ()
KSocketAddress * peerAddress ()
inline int fd () const
virtual int lookup ()
virtual int listen (int N = 5)
virtual int accept (KExtendedSocket *&sock)
virtual int connect ()
virtual bool open (int mode = IO_Raw | IO_ReadWrite)
virtual void close ()
virtual void release ()
virtual inline void flush ()
virtual inline uint size () const
virtual inline int at () const
virtual inline bool at (int)
virtual inline bool atEnd () const
virtual int readBlock (char *data, uint maxlen)
virtual int writeBlock (const char *data, uint len)
virtual int getch ()
virtual int putch (int ch)
virtual int ungetch (int)

Public Static Methods

static int resolve (sockaddr* sock, ksocklen_t len, QString& host, QString& port, int flags = 0)
static int resolve (KSocketAddress* sock, QString& host, QString& port, int flags = 0)
static QList<KAddressInfo> lookup (const QString& host, const QString& port, int flags = 0, int *error = 0)
static KSocketAddress * localAddress (int fd)
static KSocketAddress * peerAddress (int fd)
static QString strError (int code, int syserr)

Protected Methods

void setError (int errorkind, int error)
inline void cleanError ()

Protected Static Methods

static int doLookup (const QString& host, const QString& serv, addrinfo& hint, addrinfo** result)

Protected Members

int m_flags
int m_status
int m_syserror
int sockfd

Detailed Description

The extended socket class.

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.

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, unixSocketKeep = 0x100000 }

flags that can be passed down to the member functions

enum SockStatus {error = -1, nothing = 0, lookupDone = 1, created = 2, bound = 3, connecting = 4, connected = 5, listening = 4, accepting = 5, closed = 6 }

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

KExtendedSocket ()

Creates an empty 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

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

~ KExtendedSocket ()

[virtual]

Destroys the socket, disconnecting if still connected and freeing any related resources still being kept.

inline int socketStatus ()

[const]

Returns the class status

inline 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. Will return the new flags status, or -1 if flags can no longer be set.

Parameters:

flags the flags to be set

inline int socketFlags ()

[const]

Returns the current flags

bool setHost (const QString& host)

Sets the hostname to the given value Returns true on success, false on error

Parameters:

host the hostname

QString host ()

[const]

Returns the hostname

bool setPort (int port)

Sets the port/service

Parameters:

port the port

QString port ()

[const]

Returns the port/service

bool setAddress (const QString& host, int port)

Sets the address where we will connect to

Parameters:

host the hostname

port port number

bool setAddress (const QString& host, const QString& serv)

Sets the address where we will connect to

Parameters:

host the hostname

serv the service

bool setBindHost (const QString& host)

Sets the hostname to which we will bind locally before connecting. Returns false if this is a passiveSocket, otherwise true.

Parameters:

host the hostname

bool unsetBindHost ()

Unsets the bind hostname. That is, don't request a binding host.

inline 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

Parameters:

port the port number

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. Will return -1 if this is a passiveSocket

Parameters:

host the hostname

port the port number

bool setBindAddress (const QString& host, const QString& service)

Sets both host and service to which we will bind the socket. Will return -1 if this is a passiveSocket

Parameters:

host the hostname

serv the service

bool unsetBindAddress ()

Unsets the bind address for the socket. That means that we won't attempt to bind to an address before connecting

bool setTimeout (int secs, int usecs = 0)

Sets the timeout value for the connection, if this is not passiveSocket, or acception, if this is a passiveSocket. 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. Returns false if setting timeout makes no sense in the context.

Parameters:

secs the timeout length, in seconds

usecs the timeout complement, in microseconds

timeval timeout ()

[const]

Returns the timeout value for the connection

bool 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 signals. Returns false on error.

Parameters:

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

bool blockingMode ()

Returns the current blocking mode for this socket

KSocketAddress * localAddress ()

Returns the local socket address

KSocketAddress * peerAddress ()

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

inline int fd ()

[const]

Returns the file descriptor

int lookup ()

[virtual]

Performs lookup on the addresses we were given before Returns 0 or an error. Codes are the same as for <em>getaddrinfo</em> This will perform lookups on the bind addresses if they were given

int listen (int N = 5)

[virtual]

Place the socket in listen mode. The parameters are the same as for the system listen() call. Returns 0 on success, -1 on system error (errno available) and -2 if this is not a passiveSocket.

Parameters:

N the queue length for pending connections

int 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. 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)

Parameters:

sock a pointer to an KExtendedSocket variable

int connect ()

[virtual]

Attempts to connect to the remote host. 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 -3: connection timed out

Reimplemented from QObject

bool open (int mode = IO_Raw | IO_ReadWrite)

[virtual]

Implementation of QIODevice's 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, this is like connect().

Parameters:

mode the open mode. Must be IO_Raw | IO_ReadWrite

Reimplemented from QIODevice

void close ()

[virtual]

Closes the socket

Reimplemented from QIODevice

void 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 close(), 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.

inline void flush ()

[virtual]

Flushes the socket buffer. This socket is not buffered, so this does nothing

Reimplemented from QIODevice

inline uint size ()

[const virtual]

Returns length of this socket. This call is not supported on sockets

Reimplemented from QIODevice

inline int at ()

[const virtual]

Returns relative position from start. This call is not supported on sockets

Reimplemented from QIODevice

inline bool at (int)

[virtual]

Returns true if we are at position. This is not supported on sockets

Reimplemented from QIODevice

inline bool atEnd ()

[const 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...

Reimplemented from QIODevice

int readBlock (char *data, uint maxlen)

[virtual]

reads a block of data from the socket

Parameters:

data where we will write the read data to

maxlen maximum length of data to be read

Reimplemented from QIODevice

int writeBlock (const char *data, uint len)

[virtual]

writes a block of data to the socket

Parameters:

data the data to write

len the length of data to write

Reimplemented from QIODevice

int getch ()

[virtual]

gets a single character from the stream

Reimplemented from QIODevice

int putch (int ch)

[virtual]

writes a single character to the stream

Parameters:

ch character to write, converted to char

Reimplemented from QIODevice

int ungetch (int)

[virtual]

unreads one character from the stream. This is not possible on sockets

Reimplemented from QIODevice

void setError (int errorkind, int error)

[protected]

Sets the error code

int doLookup (const QString& host, const QString& serv, addrinfo& hint, addrinfo** result)

[protected static]

This is actually a wrapper around getaddrinfo()

int resolve (sockaddr* sock, ksocklen_t len, QString& host, QString& port, int flags = 0)

[static]

Performs resolution on the given socket address

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()

QList<KAddressInfo> 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

Parameters:

host the hostname to look up

port the port/service to look up

flags flags to be used when looking up

error pointer to a variable holding the error code

KSocketAddress * localAddress (int fd)

[static]

Returns the local socket address

Parameters:

fd the file descriptor

KSocketAddress * peerAddress (int fd)

[static]

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

Parameters:

fd the file descriptor

QString 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()

Version: $Id: kextsock.h,v 1.3 2001/03/26 22:17:31 thiago Exp $
Author: Thiago Macieira <thiagom@mail.com>
Generated: ssk@tauon.ph.unimelb.EDU.AU on Wed May 23 04:05:18 2001, using kdoc 2.0a35.

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

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

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()

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

code	the error code, as seen in status()
syserr	the system error, as from systemError()