/*
* This file is part of the KDE libraries
* Copyright (C) 2000,2001 Thiago Macieira
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#ifndef KEXTSOCK_H
#define KEXTSOCK_H
#include
#include
#include
#include
#include
#include
#include "kbufferedio.h"
#include "ksockaddr.h"
/* External reference to netdb.h */
struct addrinfo;
struct kde_addrinfo;
class KAddressInfo; /* our abstraction of it */
/*
* This is extending QIODevice's error codes
*
* According to qiodevice.h, the last error is IO_UnspecifiedError
* These errors will never occur in functions declared in QIODevice
* (except open, but you shouldn't call open)
*/
#define IO_ListenError (IO_UnspecifiedError+1)
#define IO_AcceptError (IO_UnspecifiedError+2)
#define IO_LookupError (IO_UnspecifiedError+3)
/**
* The extended socket class.
*
* This class should be used instead of @ref 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 @ref setSocketFlags(). If passiveSocket is used, the class will
* enable functions @ref listen() and @ref accept() and related signals, and will
* also disable @ref readBlock() and @ref writeBlock().
*
* To create a Unix socket, one would pass flag unixSocket to the constructor
* or @ref 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
* @version $Id: kextsock_h.html 132191 2002-01-17 21:32:13Z dfaure $
* @short an extended socket
*/
class KExtendedSocket: public KBufferedIO // public QObject, public QIODevice
{
Q_OBJECT
public:
/**
* flags that can be passed down to the member functions
*/
enum Flags
{
/* socket address families */
/*
* NOTE: if you change this, you have to change function valid_socket() as well
* These values are hard coded!
*/
anySocket = 0x00,
knownSocket = 0x01,
unixSocket = knownSocket | 0x02,
inetSocket = knownSocket | 0x04,
ipv4Socket = inetSocket | 0x100,
ipv6Socket = inetSocket | 0x200,
passiveSocket = 0x1000, /* passive socket (i.e., one that accepts connections) */
canonName = 0x2000, /* request that the canon name be found */
noResolve = 0x4000, /* do not attempt to resolve, treat as numeric host */
streamSocket = 0x8000, /* request a streaming socket (e.g., TCP) */
datagramSocket = 0x10000, /* request a datagram socket (e.g., UDP) */
rawSocket = 0x20000, /* request a raw socket. This probably requires privileges */
inputBufferedSocket = 0x200000, /* buffer input in this socket */
outputBufferedSocket = 0x400000, /* buffer output in this socket */
bufferedSocket = 0x600000 /* make this a fully buffered socket */
};
/**
* 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
*/
enum SockStatus
{
// the numbers are scattered so that we leave room for future expansion
error = -1, // invalid status!
nothing = 0, // no status, the class has just been created
lookupInProgress = 4, // lookup is in progress. Signals will be sent
lookupDone = 5, // lookup has been done. Flags cannot be changed
// from this point on
created = 10, // ::socket() has been called, a socket exists
bound = 11, // socket has been bound
connecting = 20, // socket is connecting (not passiveSocket)
connected = 21, // socket has connected (not passiveSocket)
listening = 20, // socket is listening (passiveSocket)
accepting = 21, // socket is accepting (passiveSocket)
closing = 35, // socket is closing (delayed close)
done = 40 // socket has been closed
};
public:
/**
* Creates an empty KExtendedSocket
*/
KExtendedSocket();
/**
* Creates a socket with the given hostname and port
* @param host the hostname
* @param port the port number
* @param flags flags
*/
KExtendedSocket(const QString& host, int port, int flags = 0);
/**
* Creates a socket with the given hostname and service
* @param host the hostname
* @param serv the service
* @param flags flags
*/
KExtendedSocket(const QString& host, const QString& service, int flags = 0);
/**
* Destroys the socket, disconnecting if still connected and
* freeing any related resources still being kept.
*/
virtual ~KExtendedSocket();
/*
* --- status, flags and internal variables --- *
*/
/**
* Returns the class status
*/
inline int socketStatus() const
{ return m_status; }
/**
* Returns the related system error code
* Except for IO_LookupError errors, these are codes found in
* errno
*/
inline int systemError() const
{ return m_syserror; }
/**
* Sets the given flags. Will return the new flags status, or
* -1 if flags can no longer be set.
* @param flags the flags to be set
*/
int setSocketFlags(int flags);
/**
* Returns the current flags
*/
inline int socketFlags() const
{ return m_flags; }
/**
* Sets the hostname to the given value
* Returns true on success, false on error
* @param host the hostname
*/
bool setHost(const QString& host);
/**
* Returns the hostname
*/
QString host() const;
/**
* Sets the port/service
* @param port the port
*/
bool setPort(int port);
bool setPort(const QString& service);
/**
* Returns the port/service
*/
QString port() const;
/**
* Sets the address where we will connect to
* @param host the hostname
* @param port port number
*/
bool setAddress(const QString& host, int port);
/**
* Sets the address where we will connect to
* @param host the hostname
* @param serv the service
*/
bool setAddress(const QString& host, const QString& serv);
/**
* Sets the hostname to which we will bind locally before connecting.
* Returns false if this is a passiveSocket, otherwise true.
* @param host the hostname
*/
bool setBindHost(const QString& host);
/**
* Unsets the bind hostname. That is, don't request a binding host.
*/
bool unsetBindHost();
/**
* Returns the hostname to which the socket will be/is bound
*/
inline QString bindHost() const;
/**
* Sets the port/service to which we will bind before connecting
* @param port the port number
*/
bool setBindPort(int port);
bool setBindPort(const QString& service);
/**
* Unsets the bind port/service.
*/
bool unsetBindPort();
/**
* Returns the service to which the socket will be/is bound.
*/
QString bindPort() const;
/**
* Sets both host and port to which we will bind the socket. Will return
* -1 if this is a passiveSocket
* @param host the hostname
* @param port the port number
*/
bool setBindAddress(const QString& host, int port);
/**
* Sets both host and service to which we will bind the socket. Will return
* -1 if this is a passiveSocket
* @param host the hostname
* @param serv the service
*/
bool setBindAddress(const QString& host, const QString& service);
/**
* Unsets the bind address for the socket. That means that we won't
* attempt to bind to an address before connecting
*/
bool unsetBindAddress();
/**
* 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.
* @param secs the timeout length, in seconds
* @param usecs the timeout complement, in microseconds
*/
bool setTimeout(int secs, int usecs = 0);
/**
* Returns the timeout value for the connection
*/
timeval timeout() const;
/**
* 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.
* @param enable if true, set blocking mode. False, non-blocking mode.
*/
bool setBlockingMode(bool enable);
/**
* Returns the current blocking mode for this socket
*/
bool blockingMode();
/**
* 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.
* @param enable if true, set address reusable
*/
bool setAddressReusable(bool enable);
/**
* Returns whether this socket can be reused
*/
bool addressReusable();
/**
* 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 functions will stop buffering. The value of -1 will be
* interpreted as "unlimited" size.
*
* 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: if we are not doing input buffering, the #ref closed signal will
* not be emitted for remote connection closing. That happens because we aren't
* reading from the connection, so we don't know when it closed.
* @param rsize read buffer size
* @param wsize write buffer size
*/
virtual bool setBufferSize(int rsize, int wsize = -2);
/**
* Returns the local socket address
*/
const KSocketAddress *localAddress();
/**
* Returns the peer socket address. Use KExtendedSocket::resolve() to
* resolve this to a human-readable hostname/service or port.
*/
const KSocketAddress *peerAddress();
/**
* Returns the file descriptor
*/
inline int fd() const
{ return sockfd; }
/*
* -- socket creation -- *
*/
/**
* Performs lookup on the addresses we were given before
* Returns 0 or an error. Codes are the same as for getaddrinfo
* This will perform lookups on the bind addresses if they were given
*/
virtual int lookup();
/**
* Starts an asynchronous lookup for the addresses given
* This function 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.
* 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 were able to determine the results without queueing
* and we found an error during lookup, this function will return -1.
*/
virtual int startAsyncLookup();
/**
* Cancels any on-going asynchronous lookups
*/
virtual void cancelAsyncLookup();
/**
* 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.
* @param N the queue length for pending connections
*/
virtual int listen(int N = 5); // 5 is arbitrary
/**
* 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)
* @param sock a pointer to an KExtendedSocket variable
*/
virtual int accept(KExtendedSocket *&sock);
/**
* 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 or that an asynchronous connection attempt is already
* in progress.
* -3: connection timed out
*/
virtual int connect();
/**
* Starts an asynchronous connect. This works exactly the same as @ref connect,
* except that the connection result won't be returned. This function will
* return either 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.
* Note that those signals might be emitted before this function returns, so your
* code should be prepared for that condition.
*/
virtual int startAsyncConnect();
/**
* Cancels any on-going asynchronous connection attempt.
*/
virtual void cancelAsyncConnect();
/**
* 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 and no connection attempt is in progress, this
* is like connect(). If one is in progress, this function will fail.
* @param mode the open mode. Must be IO_Raw | IO_ReadWrite
*/
virtual bool open(int mode = IO_Raw | IO_ReadWrite);
/**
* 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 @ref flush first,
* and then @ref closeNow.
*/
virtual void close();
/**
* 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.
*/
virtual void closeNow();
/**
* 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. And usage of this
* method is discouraged, because the socket created might be such that
* normal library routines can't handle (read, write, close, etc.)
*/
virtual void release();
/*
* -- I/O --
*/
/**
* 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
* @ref readBlock with a null destination buffer.
*/
virtual void flush();
/**
* Returns length of this socket. This call is not supported on sockets
*/
virtual inline uint size() const
{ return 0; }
/**
* Returns relative position from start. This call is not supported on sockets
*/
virtual inline int at() const
{ return 0; }
/**
* Returns true if we are at position. This is not supported on sockets
*/
virtual inline bool at(int)
{ return true; }
/**
* Returns true if we are at the end. This is not supported on sockets, but
* we always are at the end in a socket...
*/
virtual inline bool atEnd() const
{ return false; }
/**
* 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 @ref 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.
*
* The return value for this function is the number of bytes effectively
* read. If the @p data param is not null, then this is also the number
* of bytes copied into that buffer. If the return value is different than
* @p 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:
* - block, if we are not buffering and we are not in non-blocking mode
* - return an error, with EWOULDBLOCK system error, if we buffering
* or we are in non-blocking mode
* This function returns 0, if the function detected end-of-file condition
* (socket was closed)
*
* @param data where we will write the read data to
* @param maxlen maximum length of data to be read
*/
virtual int readBlock(char *data, uint maxlen);
/**
* 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 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.
*
* The function returns the number of bytes written from @p data buffer.
* The return value might be less than @p len if the output buffers cannot
* accomodate that many bytes.
*
* @param data the data to write
* @param len the length of data to write
*/
virtual int writeBlock(const char *data, uint len);
/**
* 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.
* The return value of 0 does not mean end-of-file condition.
* @param data where to store the data
* @param maxlen how many bytes to copy, at most
*/
virtual int peekBlock(char *data, uint maxlen);
/**
* 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.
*/
virtual int unreadBlock(const char *data, uint len);
/**
* Waits @p msec milliseconds for more data to be available, or 0 to
* wait forever. The return value is the amount of data available for
* read in the read buffer.
* This function returns -1 in case of system error and -2 in case of
* invalid socket state
* @param msec milliseconds to wait
*/
virtual int waitForMore(int msec);
/**
* gets a single character from the stream
*/
virtual int getch();
/**
* writes a single character to the stream
* @param ch character to write, converted to char
*/
virtual int putch(int ch);
/**
* unreads one character from the stream. This is not possible on sockets
*/
virtual int ungetch(int)
{ return -1; }
/**
* 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.
* @param enable if true, the signal will be emitted
*/
virtual void enableRead(bool enable);
/**
* 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.
* @param enable if true, the signal will be emitted
*/
virtual void enableWrite(bool enable);
signals:
/**
* This signal is emitted whenever an asynchronous lookup process is done.
* The parameter @p count tells how many results were found.
*/
void lookupFinished(int count);
/**
* This signal is emitted whenever we connected asynchronously to a host.
*/
void connectionSuccess();
/**
* This signal is emitted whenever our asynchronous connection attempt
* failed to all hosts listed.
* @param error the errno code of the last connection attempt
*/
void connectionFailed(int error);
protected:
int m_flags; // current flags
int m_status; // status
int m_syserror; // the system error code
int sockfd; // file descriptor of the socket
protected slots:
void socketActivityRead();
void socketActivityWrite();
void dnsResultsReady();
void startAsyncConnectSlot();
void connectionEvent();
private:
class KExtendedSocketPrivate;
KExtendedSocketPrivate *d;
// protection against accidental use
KExtendedSocket(KExtendedSocket&);
KExtendedSocket& operator=(KExtendedSocket&);
protected:
/**
* Sets the error code
*/
void setError(int errorkind, int error);
inline void cleanError()
{ setError(IO_Ok, 0); }
/**
* This is actually a wrapper around getaddrinfo()
* @internal
*/
static int doLookup(const QString& host, const QString& serv, addrinfo& hint,
kde_addrinfo** result);
public:
/**
* Performs resolution on the given socket address
* That is, tries to resolve the raw form of the socket address into a textual
* representation.
* @param sockaddr the socket address
* @param host where the hostname will be written
* @param port where the service-port will be written
* @param flags the same flags as getnameinfo()
*/
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);
/**
* Performs lookup on the given hostname/port combination and returns a list
* of matching addresses.
* The error code can be transformed into string by @ref KExtendedSocket::strError
* with code of IO_LookupError.
*
* IMPORTANT: the result values of the QList 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.
*
* @param host the hostname to look up
* @param port the port/service to look up
* @param flags flags to be used when looking up, @see Flags
* @param error pointer to a variable holding the error code
*/
static QList lookup(const QString& host, const QString& port, int flags = 0, int *error = 0);
/**
* Returns the local socket address
* Remember to delete the returned object when it is no longer needed.
* @param fd the file descriptor
*/
static KSocketAddress *localAddress(int fd);
/**
* 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.
* @param fd the file descriptor
*/
static KSocketAddress *peerAddress(int fd);
/**
* Returns the representing text of this error code
* @param code the error code, as seen in status()
* @param syserr the system error, as from systemError()
*/
static QString strError(int code, int syserr);
};
class KAddressInfo
{
private:
addrinfo *ai;
KSocketAddress *addr;
inline KAddressInfo() : ai(0), addr(0)
{ }
KAddressInfo(addrinfo *ai);
KAddressInfo(KAddressInfo&) { }
KAddressInfo& operator=(KAddressInfo&) { return *this; }
public:
~KAddressInfo();
inline operator const KSocketAddress*() const
{ return addr; }
inline operator const addrinfo&() const
{ return *ai; }
inline operator const addrinfo*() const
{ return ai; }
inline const KSocketAddress* address() const
{ return addr; }
int flags() const;
int family() const;
int socktype() const;
int protocol() const;
const char* canonname() const;
inline int length() const
{ if (addr) return addr->size(); return 0; }
friend class KExtendedSocket;
};
#endif // KEXTSOCK_H
| Generated by: dfaure on kde.faure.org on Thu Jan 17 22:15:01 2002, using kdoc 2.0a53. |