qsocketnotifier(3qt)

1QSocketNotifier(3qt)                                      QSocketNotifier(3qt)
2
3
4

NAME

6       QSocketNotifier - Support for socket callbacks
7

SYNOPSIS

9       #include <qsocketnotifier.h>
10
11       Inherits QObject.
12
13   Public Members
14       enum Type { Read, Write, Exception }
15       QSocketNotifier ( int socket, Type type, QObject * parent = 0, const
16           char * name = 0 )
17       ~QSocketNotifier ()
18       int socket () const
19       Type type () const
20       bool isEnabled () const
21       virtual void setEnabled ( bool enable )
22
23   Signals
24       void activated ( int socket )
25

DESCRIPTION

27       The QSocketNotifier class provides support for socket callbacks.
28
29       This class makes it possible to write asynchronous socket-based code in
30       Qt. Using synchronous socket operations blocks the program, which is
31       clearly not acceptable for an event-driven GUI program.
32
33       Once you have opened a non-blocking socket (whether for TCP, UDP, a
34       UNIX-domain socket, or any other protocol family your operating system
35       supports), you can create a socket notifier to monitor the socket. Then
36       you connect the activated() signal to the slot you want to be called
37       when a socket event occurs.
38
39       Note for Windows users: the socket passed to QSocketNotifier will
40       become non-blocking, even if it was created as a blocking socket.
41
42       There are three types of socket notifiers (read, write and exception);
43       you must specify one of these in the constructor.
44
45       The type specifies when the activated() signal is to be emitted: <ol
46       type=1>
47
48       1      QSocketNotifier::Read - There is data to be read (socket read
49              event).
50
51       2      QSocketNotifier::Write - Data can be written (socket write
52              event).
53
54       3      QSocketNofifier::Exception - An exception has occurred (socket
55              exception event). We recommend against using this.
56
57       For example, if you need to monitor both reads and writes for the same
58       socket you must create two socket notifiers.
59
60       For read notifiers it makes little sense to connect the activated()
61       signal to more than one slot because the data can be read from the
62       socket only once.
63
64       Also observe that if you do not read all the available data when the
65       read notifier fires, it fires again and again.
66
67       For write notifiers, immediately disable the notifier after the
68       activated() signal has been received and you have sent the data to be
69       written on the socket. When you have more data to be written, enable it
70       again to get a new activated() signal. The exception is if the socket
71       data writing operation (send() or equivalent) fails with a "would
72       block" error, which means that some buffer is full and you must wait
73       before sending more data. In that case you do not need to disable and
74       re-enable the write notifier; it will fire again as soon as the system
75       allows more data to be sent.
76
77       The behavior of a write notifier that is left in enabled state after
78       having emitting the first activated() signal (and no "would block"
79       error has occurred) is undefined. Depending on the operating system, it
80       may fire on every pass of the event loop or not at all.
81
82       If you need a time-out for your sockets you can use either timer events
83       or the QTimer class.
84
85       Socket action is detected in the main event loop of Qt. The X11 version
86       of Qt has a single UNIX select() call that incorporates all socket
87       notifiers and the X socket.
88
89       Note that on XFree86 for OS/2, select() works only in the thread in
90       which main() is running; you should therefore use that thread for GUI
91       operations.
92
93       See also QSocket, QServerSocket, QSocketDevice, QFile::handle(), and
94       Input/Output and Networking.
95
96   Member Type Documentation

QSocketNotifier::Type

98       QSocketNotifier::Read
99
100       QSocketNotifier::Write
101
102       QSocketNotifier::Exception
103

MEMBER FUNCTION DOCUMENTATION

QSocketNotifier::QSocketNotifier ( int socket, Type type, QObject * parent =

106       0, const char * name = 0 )
107       Constructs a socket notifier called name, with the parent, parent. It
108       watches socket for type events, and enables it.
109
110       It is generally advisable to explicitly enable or disable the socket
111       notifier, especially for write notifiers.
112
113       See also setEnabled() and isEnabled().
114

QSocketNotifier::~QSocketNotifier ()

116       Destroys the socket notifier.
117

void QSocketNotifier::activated ( int socket ) [signal]

119       This signal is emitted under certain conditions specified by the
120       notifier type(): <ol type=1>
121
122       QSocketNotifier::Read - There is data to be read (socket read event).
123
124       QSocketNotifier::Write - Data can be written (socket write event).
125
126       QSocketNofifier::Exception - An exception has occurred (socket
127       exception event).
128
129       The socket argument is the socket identifier.
130
131       See also type() and socket().
132

bool QSocketNotifier::isEnabled () const

134       Returns TRUE if the notifier is enabled; otherwise returns FALSE.
135
136       See also setEnabled().
137

void QSocketNotifier::setEnabled ( bool enable ) [virtual]

139       Enables the notifier if enable is TRUE or disables it if enable is
140       FALSE.
141
142       The notifier is enabled by default.
143
144       If the notifier is enabled, it emits the activated() signal whenever a
145       socket event corresponding to its type occurs. If it is disabled, it
146       ignores socket events (the same effect as not creating the socket
147       notifier).
148
149       Write notifiers should normally be disabled immediately after the
150       activated() signal has been emitted; see discussion of write notifiers
151       in the class description above.
152
153       See also isEnabled() and activated().
154

int QSocketNotifier::socket () const

156       Returns the socket identifier specified to the constructor.
157
158       See also type().
159

Type QSocketNotifier::type () const

161       Returns the socket event type specified to the constructor:
162       QSocketNotifier::Read, QSocketNotifier::Write, or
163       QSocketNotifier::Exception.
164
165       See also socket().
166
167

COPYRIGHT

173       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
174       license file included in the distribution for a complete license
175       statement.
176

AUTHOR

178       Generated automatically from the source code.
179

BUGS

181       If you find a bug in Qt, please report it as described in
182       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
183       help you. Thank you.
184
185       The definitive Qt documentation is provided in HTML format; it is
186       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
187       web browser. This man page is provided as a convenience for those users
188       who prefer man pages, although this format is not officially supported
189       by Trolltech.
190
191       If you find errors in this manual page, please report them to qt-
192       bugs@trolltech.com.  Please include the name of the manual page
193       (qsocketnotifier.3qt) and the Qt version (3.3.8).
194
195
196
197Trolltech AS                    2 February 2007           QSocketNotifier(3qt)