QSocketNotifier(3qt)QSocketNotifier(3qt)NAME
QSocketNotifier - Support for socket callbacks
#include <qsocketnotifier.h>
Inherits QObject.
Public Members
enum Type { Read, Write, Exception }
QSocketNotifier ( int socket, Type, QObject * parent=0,
const char * name=0 )
~QSocketNotifier ()
int socket () const
Type type () const
bool isEnabled () const
virtual void setEnabled ( bool )
Signals
void activated ( int socket )
DESCRIPTION
The QSocketNotifer class provides support for socket
callbacks.
This class makes it possible to write e.g. asynchronous
TCP/IP socket-based code in Qt. Using synchronous socket
operations blocks the program, which is clearly not
acceptable for an event-based GUI program.
Once you have opened a non-blocking socket (either for
TCP, UDP, a unix-domain socket, or any other protocol
family your operating system supports), you can create a
socket notifier to monitor the socket. Then connect the
activated() signal to the slot you want to be called when
a socket event occurs.
There are three types of socket notifiers (read, write and
exception) and you must specify one of these in the
constructor.
The type specifies when the activated() signal is to be
emitted:
1 QSocketNotifier::Read: There is data to be read
(socket read event).
2 QSocketNotifier::Write: Data can be written (socket
write event).
3 QSocketNofifier::Exception: An exception has
occurred (socket exception event). We recommend
against using this.
Trolltech AS 13 June 2001 1
QSocketNotifier(3qt)QSocketNotifier(3qt)
For example, if you need to monitor both reads and writes
for the same socket, you must create two socket notifiers.
Example:
int sockfd; // socket identifier
struct sockaddr_in sa; // should contain host address
sockfd = socket( AF_INET, SOCK_STREAM, 0 ); // create TCP socket
// make the socket non-blocking here, usually using fcntl( O_NONBLOCK )
::connect( sockfd, (struct sockaddr*)&sa, // connect to host
sizeof(sa) ); // NOT QObject::connect()!
QSocketNotifier *sn;
sn = new QSocketNotifier( sockfd, QSocketNotifier::Read, parent );
QObject::connect( sn, SIGNAL(activated(int)),
myObject, SLOT(dataReceived()) );
The optional parent argument can be set to make the socket
notifier a child of some widget and therefore be
automatically destroyed when the widget is destroyed.
For read notifiers, it makes little sense to connect the
activated() signal to more than one slot, because the data
can be read from the socket only once.
Also observe that if you do not read all the available
data when the read notifier fires, it fires again and
again.
If you disable the read notifier, your program may
deadlock. Avoid it if you do not know what you are doing.
(The same applies to exception notifiers if you have to
use that, for instance if you have to use TCP urgent
data.)
For write notifiers, after the activated() signal has been
received and you have sent the data to be written on the
socket, immediately disable the notifier. When you have
more data to be written, enable it again to get a new
activated() signal. The exception is if the socket data
writing operation (send() or equivalent) fails with a"
Would block" error, meaning that some buffer is full and
you must wait before sending more data. In this case, you
do not need to disable and re-enable the write notifier,
it will fire again as soon as the system allows more data
may be sent.
The behaviour of a write notifier that is left in enabled
state after having emitting the first activated() signal
(and no "would block" error has occurred) is undefined.
Depending on the operating system, it may fire on every
pass of the event loop, or not at all.
If you need a time-out for your sockets, you can use
either timer events or the QTimer class.
Trolltech AS 13 June 2001 2
QSocketNotifier(3qt)QSocketNotifier(3qt)
Socket action is detected in the main event loop of Qt.
The X11 version of Qt has has a single UNIX select() call
which incorporates all socket notifiers and the X socket.
Note that on XFree86 for OS/2, select() only works in the
thread in which main() is running, therefore you should
use that thread for GUI operations.
See also QSocket, QServerSocket and QSocketDevice.
MEMBER FUNCTION DOCUMENTATIONQSocketNotifier::QSocketNotifier ( int socket, Type type, QObject
* parent=0, const char * name=0 )
Constructs a socket notifier with a parent and a name.
Arguments:
socket is the socket to be monitored.
type specifies the socket operation to be detected;
QSocketNotifier::Read, QSocketNotifier::Write or
QSocketNotifier::Exception. The parent and name arguments
are sent to the QObject constructor.
The socket notifier is initially enabled. It is generally
advisable to explicitly enable or disable it, especially
for write notifiers.
See also setEnabled() and isEnabled().
QSocketNotifier::~QSocketNotifier ()
Destructs the socket notifier.
void QSocketNotifier::activated ( int socket ) [signal]
This signal is emitted under certain conditions, specified
by the notifier type:
1 QSocketNotifier::Read: There is data to be read
(socket read event).
2 QSocketNotifier::Write: Data can be written (socket
write event).
3 QSocketNofifier::Exception: An exception has
occurred (socket exception event).
The socket argument is the socket identifier.
See also type() and socket().
bool QSocketNotifier::event ( QEvent * e ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Trolltech AS 13 June 2001 3
QSocketNotifier(3qt)QSocketNotifier(3qt)
Reimplemented from QObject.
bool QSocketNotifier::isEnabled () const
Returns TRUE if the notifier is enabled, or FALSE if it is
disabled.
See also setEnabled().
void QSocketNotifier::setEnabled ( bool enable ) [virtual]
Enables the notifier if enable is TRUE, or disables it if
enable is FALSE.
The notifier is by default enabled.
If the notifier is enabled, it emits the activated()
signal whenever a socket event corresponding to its type
occurs. If it is disabled, it ignores socket events (the
same effect as not creating the socket notifier).
Write notifiers should normally be disabled immediately
after the activated() signal has been emitted; see
discussion of write notifiers in the class description
above.
See also isEnabled() and activated().
int QSocketNotifier::socket () const
Returns the socket identifier specified to the
constructor.
See also type().
Type QSocketNotifier::type () const
Returns the socket event type specified to the
constructor; QSocketNotifier::Read, QSocketNotifier::Write
or QSocketNotifier::Exception.
See also socket().
SEE ALSO
http://doc.trolltech.com/qsocketnotifier.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
Trolltech AS 13 June 2001 4
QSocketNotifier(3qt)QSocketNotifier(3qt)
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page
(qsocketnotifier.3qt) and the Qt version (2.3.1).
Trolltech AS 13 June 2001 5
