You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
437 lines
14 KiB
437 lines
14 KiB
/* -*- C++ -*-
|
|
* Copyright (C) 2003 Thiago Macieira <thiago@kde.org>
|
|
*
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining
|
|
* a copy of this software and associated documentation files (the
|
|
* "Software"), to deal in the Software without restriction, including
|
|
* without limitation the rights to use, copy, modify, merge, publish,
|
|
* distribute, sublicense, and/or sell copies of the Software, and to
|
|
* permit persons to whom the Software is furnished to do so, subject to
|
|
* the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included
|
|
* in all copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
*/
|
|
|
|
#ifndef KSERVERSOCKET_H
|
|
#define KSERVERSOCKET_H
|
|
|
|
#include <tqobject.h>
|
|
#include "ksocketbase.h"
|
|
|
|
namespace KNetwork {
|
|
|
|
class KSocketDevice;
|
|
class KStreamSocket;
|
|
class KResolver;
|
|
class KResolverResults;
|
|
|
|
class KServerSocketPrivate;
|
|
/**
|
|
* @class KServerSocket kserversocket.h kserversocket.h
|
|
* @brief A server socket for accepting connections.
|
|
*
|
|
* This class provides functionality for creating a socket to
|
|
* listen for incoming connections and subsequently accept them.
|
|
*
|
|
* To use this class, you must first set the parameters for the listening
|
|
* socket's address, then place it in listening mode.
|
|
*
|
|
* A typical example would look like:
|
|
* \code
|
|
* TQString service = "http";
|
|
* KServerSocket *ss = new KServerSocket(service);
|
|
* connect(ss, TQT_SIGNAL(readyAccept()), this, TQT_SLOT(slotReadyAccept()));
|
|
* connect(ss, TQT_SIGNAL(gotError(int)), this, TQT_SLOT(slotSocketError(int)));
|
|
* ss->listen();
|
|
* \endcode
|
|
*
|
|
* In this case, this class will place the socket into listening mode on the
|
|
* service pointed to by @p service and will emit the @ref readyAccept signal
|
|
* when a connection is ready for accepting. The called slot is responsible for
|
|
* calling @ref accept.
|
|
*
|
|
* The location of the services file (where @p service is looked up)
|
|
* is defined by _PATH_SERVICES in /usr/include/netdb.h. This is
|
|
* usually set to /etc/services.
|
|
* See RFC 1700 for more information on services.
|
|
* You can specify @p service as a port number directly, rather than as a service
|
|
* name. This is discouraged as it prevents the end user from easily modifying
|
|
* the port number.
|
|
*
|
|
* For another example of usage, this below code attempts to make a connection on any port within a range:
|
|
* \code
|
|
* KServerSocket *ss = new KServerSocket();
|
|
* ss->setFamily(KResolver::InetFamily);
|
|
* bool found = false;
|
|
* for( unsigned int port = firstport; port <= lastport; ++port) {
|
|
* ss->setAddress( TQString::number( port ) );
|
|
* bool success = ss->listen();
|
|
* if( found = ( success && ss->error() ==
|
|
* KSocketBase::NoError ) )
|
|
* break;
|
|
* ss->close();
|
|
* }
|
|
* if( !found ) {
|
|
* // Couldn't connect to any port.
|
|
* } else {
|
|
* connect(ss, TQT_SIGNAL(readyAccept()), this, TQT_SLOT(slotReadyAccept()));
|
|
* connect(ss, TQT_SIGNAL(gotError(int)), this, TQT_SLOT(slotSocketError(int)));
|
|
* ss->listen();
|
|
* }
|
|
* \endcode
|
|
*
|
|
* The called slot slotReadyAccept() is responsible for calling
|
|
* @ref accept.
|
|
*
|
|
* It is important to note that @ref accept can return either an
|
|
* object of type KNetwork::KStreamSocket or
|
|
* KNetwork::KBufferedSocket (default). If you want to accept a
|
|
* non-buffered socket, you must first call setAcceptBuffered.
|
|
*
|
|
* @warning If you use KServerSocket in an auxiliary (non-GUI) thread,
|
|
* you need to accept only KNetwork::KStreamSocket objects.
|
|
*
|
|
* @see KNetwork::KStreamSocket, KNetwork::KBufferedSocket
|
|
* @author Thiago Macieira <thiago@kde.org>
|
|
*/
|
|
class KDECORE_EXPORT KServerSocket: public TQObject, public KPassiveSocketBase
|
|
{
|
|
Q_OBJECT
|
|
TQ_OBJECT
|
|
public:
|
|
/**
|
|
* Default constructor.
|
|
*
|
|
* If the binding address isn't changed by setAddress, this socket will
|
|
* bind to all interfaces on this node and the port will be selected by the
|
|
* operating system.
|
|
*
|
|
* @param parent the parent TQObject object
|
|
* @param name the name of this object
|
|
*/
|
|
KServerSocket(TQObject* parent = 0L, const char *name = 0L);
|
|
|
|
/**
|
|
* Construct this object specifying the service to listen on.
|
|
*
|
|
* If the binding address isn't changed by setAddress, this socket will
|
|
* bind to all interfaces and will listen on the port specified by
|
|
* @p service. This is either a service name (e.g. 'www') or a port
|
|
* number (e.g. '80').
|
|
*
|
|
* The location of the services file (where @p service is looked up)
|
|
* is defined by _PATH_SERVICES in /usr/include/netdb.h. This is
|
|
* usually set to /etc/services.
|
|
* See RFC 1700 for more information on services.
|
|
*
|
|
* @param service the service name to listen on
|
|
* @param parent the parent TQObject object
|
|
* @param name the name of this object
|
|
*/
|
|
KServerSocket(const TQString& service, TQObject* parent = 0L, const char *name = 0L);
|
|
|
|
/**
|
|
* Construct this object specifying the node and service names to listen on.
|
|
*
|
|
* If the binding address isn't changed by setAddress, this socket will
|
|
* bind to the interface specified by @p node and the port specified by
|
|
* @p service. This is either a service name (e.g. 'www') or a port
|
|
* number (e.g. '80').
|
|
*
|
|
* The location of the services file (where @p service is looked up)
|
|
* is defined by _PATH_SERVICES in /usr/include/netdb.h. This is
|
|
* usually set to /etc/services.
|
|
* See RFC 1700 for more information on services.
|
|
*
|
|
* @param node the node to bind to
|
|
* @param service the service port to listen on
|
|
* @param parent the parent TQObject object
|
|
* @param name the name of this object
|
|
*/
|
|
KServerSocket(const TQString& node, const TQString& service,
|
|
TQObject* parent = 0L, const char *name = 0L);
|
|
|
|
/**
|
|
* Destructor. This will close the socket, if open.
|
|
*
|
|
* Note, however, that accepted sockets do not get closed when this
|
|
* object closes.
|
|
*/
|
|
~KServerSocket();
|
|
|
|
protected:
|
|
/**
|
|
* Sets the socket options. Reimplemented from KSocketBase.
|
|
*/
|
|
virtual bool setSocketOptions(int opts);
|
|
|
|
public:
|
|
/**
|
|
* Returns the internal KResolver object used for
|
|
* looking up the host name and service.
|
|
*
|
|
* This can be used to set extra options to the
|
|
* lookup process other than the default values, as well
|
|
* as obtaining the error codes in case of lookup failure.
|
|
*/
|
|
KResolver& resolver() const;
|
|
|
|
/**
|
|
* Returns the internal list of resolved results for the binding address.
|
|
*/
|
|
const KResolverResults& resolverResults() const;
|
|
|
|
/**
|
|
* Enables or disables name resolution. If this flag is set to true,
|
|
* the @ref bind operation will trigger name lookup
|
|
* operations (i.e., converting a hostname into its binary form).
|
|
* If the flag is set to false, those operations will instead
|
|
* try to convert a string representation of an address without
|
|
* attempting name resolution.
|
|
*
|
|
* This is useful, for instance, when IP addresses are in
|
|
* their string representation (such as "1.2.3.4") or come
|
|
* from other sources like @ref KSocketAddress.
|
|
*
|
|
* @param enable whether to enable
|
|
*/
|
|
void setResolutionEnabled(bool enable);
|
|
|
|
/**
|
|
* Sets the allowed families for the resolutions.
|
|
*
|
|
* @param families the families that we want/accept
|
|
* @see KResolver::SocketFamilies for possible values
|
|
*/
|
|
void setFamily(int families);
|
|
|
|
/**
|
|
* Sets the address on which we will listen. The port to listen on is given by
|
|
* @p service, and we will bind to all interfaces. To let the operating system choose a
|
|
* port, set the service to "0". @p service can either be a service name
|
|
* (e.g. 'www') or a port number (e.g. '80').
|
|
*
|
|
* The location of the services file (where @p service is looked up)
|
|
* is defined by _PATH_SERVICES in /usr/include/netdb.h. This is
|
|
* usually set to /etc/services.
|
|
* See RFC 1700 for more information on services.
|
|
*
|
|
* @param service the service name to listen on
|
|
*/
|
|
void setAddress(const TQString& service);
|
|
|
|
/**
|
|
* @overload
|
|
* Sets the address on which we will listen. This will cause the socket to listen
|
|
* only on the interface given by @p node and on the port given by @p service.
|
|
* @p service can either be a service name (e.g. 'www') or a port number
|
|
* (e.g. '80').
|
|
*
|
|
* The location of the services file (where @p service is looked up)
|
|
* is defined by _PATH_SERVICES in /usr/include/netdb.h. This is
|
|
* usually set to /etc/services.
|
|
* See RFC 1700 for more information on services.
|
|
*
|
|
* @param node the node to bind to
|
|
* @param service the service port to listen on
|
|
*/
|
|
void setAddress(const TQString& node, const TQString& service);
|
|
|
|
/**
|
|
* Sets the timeout for accepting. When you call @ref accept,
|
|
* it will wait at most @p msecs milliseconds or return with an error
|
|
* (returning a NULL object).
|
|
*
|
|
* @param msecs the time in milliseconds to wait, 0 to wait forever
|
|
*/
|
|
void setTimeout(int msecs);
|
|
|
|
/**
|
|
* Starts the lookup for peer and local hostnames as
|
|
* well as their services.
|
|
*
|
|
* If the blocking mode for this object is on, this function will
|
|
* wait for the lookup results to be available (by calling the
|
|
* @ref KResolver::wait method on the resolver objects).
|
|
*
|
|
* When the lookup is done, the signal @ref hostFound will be
|
|
* emitted (only once, even if we're doing a double lookup).
|
|
* If the lookup failed (for any of the two lookups) the
|
|
* @ref gotError signal will be emitted with the appropriate
|
|
* error condition (see @ref KSocketBase::SocketError).
|
|
*
|
|
* This function returns true on success and false on error. Note that
|
|
* this is not the lookup result!
|
|
*/
|
|
virtual bool lookup();
|
|
|
|
/**
|
|
* Binds this socket to the given nodename and service,
|
|
* or use the default ones if none are given.
|
|
*
|
|
* Upon successful binding, the @ref bound signal will be
|
|
* emitted. If an error is found, the @ref gotError
|
|
* signal will be emitted.
|
|
*
|
|
* This function returns true on success.
|
|
*
|
|
* @param node the nodename
|
|
* @param service the service
|
|
*/
|
|
virtual bool bind(const TQString& node, const TQString& service);
|
|
|
|
/**
|
|
* Binds the socket to the given service name.
|
|
* @overload
|
|
*
|
|
* @param service the service
|
|
*/
|
|
virtual bool bind(const TQString& service);
|
|
|
|
/**
|
|
* Binds the socket to the addresses previously set with @ref setAddress.
|
|
* @overload
|
|
*
|
|
*/
|
|
virtual bool bind();
|
|
|
|
/**
|
|
* Connect this socket to this specific address. Reimplemented from KSocketBase.
|
|
*
|
|
* Unlike @ref bind(const TQString&, const TQString&) above, this function
|
|
* really does bind the socket. No lookup is performed. The @ref bound signal
|
|
* will be emitted.
|
|
*/
|
|
virtual bool bind(const KResolverEntry& address);
|
|
|
|
/**
|
|
* Puts this socket into listening mode. Reimplemented from @ref KPassiveSocketBase.
|
|
*
|
|
* Placing a socket into listening mode means it will be able to receive incoming
|
|
* connections through the @ref accept method.
|
|
*
|
|
* If you do not call this method but call @ref accept directly, the socket will
|
|
* be placed into listening mode automatically.
|
|
*
|
|
* @param backlog the number of connection the system is to
|
|
* queue without @ref accept being called
|
|
* @returns true if the socket is now in listening mode.
|
|
*/
|
|
virtual bool listen(int backlog = 5); // 5 is arbitrary
|
|
|
|
/**
|
|
* Closes this socket.
|
|
*/
|
|
virtual void close();
|
|
|
|
/**
|
|
* Toggles whether the accepted socket will be buffered or not.
|
|
* That is, the @ref accept function will always return a KStreamSocket
|
|
* object or descended from it. If buffering is enabled, the class
|
|
* to be returned will be KBufferedSocket.
|
|
*
|
|
* By default, this flag is set to true.
|
|
*
|
|
* @param enable whether to set the accepted socket to
|
|
* buffered mode
|
|
*/
|
|
void setAcceptBuffered(bool enable);
|
|
|
|
/**
|
|
* Accepts one incoming connection and return the associated, open
|
|
* socket.
|
|
*
|
|
* If this function cannot accept a new connection, it will return NULL.
|
|
* The specific object class returned by this function may vary according
|
|
* to the implementation: derived classes may return specialised objects
|
|
* descended from KStreamSocket.
|
|
*
|
|
* @note This function should return a KStreamSocket object, but compiler
|
|
* deficiencies prevent such an adjustment. Therefore, we return
|
|
* the base class for active sockets, but it is guaranteed
|
|
* that the object will be a KStreamSocket or derived from it.
|
|
*
|
|
* @sa KBufferedSocket
|
|
* @sa setAcceptBuffered
|
|
*/
|
|
virtual KActiveSocketBase* accept();
|
|
|
|
/**
|
|
* Returns this socket's local address.
|
|
*/
|
|
virtual KSocketAddress localAddress() const;
|
|
|
|
/**
|
|
* Returns this socket's externally-visible address if know.
|
|
*/
|
|
virtual KSocketAddress externalAddress() const;
|
|
|
|
private slots:
|
|
void lookupFinishedSlot();
|
|
|
|
signals:
|
|
/**
|
|
* This signal is emitted when this object finds an error.
|
|
* The @p code parameter contains the error code that can
|
|
* also be found by calling @ref error.
|
|
*/
|
|
void gotError(int code);
|
|
|
|
/**
|
|
* This signal is emitted when the lookup is successfully completed.
|
|
*/
|
|
void hostFound();
|
|
|
|
/**
|
|
* This signal is emitted when the socket successfully binds
|
|
* to an address.
|
|
*
|
|
* @param local the local address we bound to
|
|
*/
|
|
void bound(const KResolverEntry& local);
|
|
|
|
/**
|
|
* This signal is emitted when the socket completes the
|
|
* closing/shut down process.
|
|
*/
|
|
void closed();
|
|
|
|
/**
|
|
* This signal is emitted whenever the socket is ready for
|
|
* accepting -- i.e., there is at least one connection waiting to
|
|
* be accepted.
|
|
*/
|
|
void readyAccept();
|
|
|
|
protected:
|
|
/**
|
|
* Convenience function to set this object's error code to match
|
|
* that of the socket device.
|
|
*/
|
|
void copyError();
|
|
|
|
private:
|
|
bool doBind();
|
|
bool doListen();
|
|
|
|
private:
|
|
KServerSocket(const KServerSocket&);
|
|
KServerSocket& operator=(const KServerSocket&);
|
|
|
|
KServerSocketPrivate *d;
|
|
};
|
|
|
|
} // namespace KNetwork
|
|
|
|
#endif
|