QSocketNotifier(3qt)QSocketNotifier(3qt)NAME
QSocketNotifier - Support for socket callbacks
SYNOPSIS
#include <qsocketnotifier.h>
Inherits QObject.
Public Members
enum Type { Read, Write, Exception }
QSocketNotifier ( int socket, Type type, QObject * parent = 0, const
char * name = 0 )
~QSocketNotifier ()
int socket () const
Type type () const
bool isEnabled () const
virtual void setEnabled ( bool enable )
Signals
void activated ( int socket )
DESCRIPTION
The QSocketNotifier class provides support for socket callbacks.
This class makes it possible to write asynchronous socket-based code in
Qt. Using synchronous socket operations blocks the program, which is
clearly not acceptable for an event-driven GUI program.
Once you have opened a non-blocking socket (whether 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
you connect the activated() signal to the slot you want to be called
when a socket event occurs.
Note for Windows users: the socket passed to QSocketNotifier will
become non-blocking, even if it was created as a blocking socket.
There are three types of socket notifiers (read, write and exception);
you must specify one of these in the constructor.
The type specifies when the activated() signal is to be emitted: <ol
type=1>
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.
For example, if you need to monitor both reads and writes for the same
socket you must create two socket notifiers.
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.
For write notifiers, immediately disable the notifier after the
activated() signal has been received and you have sent the data to be
written on the socket. 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, which means that some buffer is full and you must wait
before sending more data. In that 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 to be sent.
The behavior 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.
Socket action is detected in the main event loop of Qt. The X11 version
of Qt has a single UNIX select() call that incorporates all socket
notifiers and the X socket.
Note that on XFree86 for OS/2, select() works only in the thread in
which main() is running; you should therefore use that thread for GUI
operations.
See also QSocket, QServerSocket, QSocketDevice, QFile::handle(), and
Input/Output and Networking.
Member Type Documentation
QSocketNotifier::Type
QSocketNotifier::Read
QSocketNotifier::Write
QSocketNotifier::Exception
MEMBER FUNCTION DOCUMENTATIONQSocketNotifier::QSocketNotifier ( int socket, Type type, QObject * parent =
0, const char * name = 0 )
Constructs a socket notifier called name, with the parent, parent. It
watches socket for type events, and enables it.
It is generally advisable to explicitly enable or disable the socket
notifier, especially for write notifiers.
See also setEnabled() and isEnabled().
QSocketNotifier::~QSocketNotifier ()
Destroys the socket notifier.
void QSocketNotifier::activated ( int socket ) [signal]
This signal is emitted under certain conditions specified by the
notifier type(): <ol type=1>
QSocketNotifier::Read - There is data to be read (socket read event).
QSocketNotifier::Write - Data can be written (socket write event).
QSocketNofifier::Exception - An exception has occurred (socket
exception event).
The socket argument is the socket identifier.
See also type() and socket().
bool QSocketNotifier::isEnabled () const
Returns TRUE if the notifier is enabled; otherwise returns FALSE.
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 enabled by default.
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-2007 Trolltech ASA, 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 help us to
help you. Thank you.
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with a
web browser. This man page is provided as a convenience for those users
who prefer man pages, although this format is not officially supported
by Trolltech.
If you find errors in 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 (3.3.8).
Trolltech AS 2 February 2007 QSocketNotifier(3qt)
