1 | // Copyright (C) 2011-2012 Denis Shienkov <denis.shienkov@gmail.com> |
---|---|
2 | // Copyright (C) 2011 Sergey Belyashov <Sergey.Belyashov@gmail.com> |
3 | // Copyright (C) 2012 Laszlo Papp <lpapp@kde.org> |
4 | // Copyright (C) 2012 Andre Hartmann <aha_1980@gmx.de> |
5 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only |
6 | |
7 | #include "qserialport.h" |
8 | #include "qserialportinfo.h" |
9 | #include "qserialportinfo_p.h" |
10 | |
11 | #include "qserialport_p.h" |
12 | |
13 | #include <QtCore/qdebug.h> |
14 | |
15 | QT_BEGIN_NAMESPACE |
16 | |
17 | QSerialPortErrorInfo::QSerialPortErrorInfo(QSerialPort::SerialPortError newErrorCode, |
18 | const QString &newErrorString) |
19 | : errorCode(newErrorCode) |
20 | , errorString(newErrorString) |
21 | { |
22 | if (errorString.isNull()) { |
23 | switch (errorCode) { |
24 | case QSerialPort::NoError: |
25 | errorString = QSerialPort::tr(s: "No error"); |
26 | break; |
27 | case QSerialPort::OpenError: |
28 | errorString = QSerialPort::tr(s: "Device is already open"); |
29 | break; |
30 | case QSerialPort::NotOpenError: |
31 | errorString = QSerialPort::tr(s: "Device is not open"); |
32 | break; |
33 | case QSerialPort::TimeoutError: |
34 | errorString = QSerialPort::tr(s: "Operation timed out"); |
35 | break; |
36 | case QSerialPort::ReadError: |
37 | errorString = QSerialPort::tr(s: "Error reading from device"); |
38 | break; |
39 | case QSerialPort::WriteError: |
40 | errorString = QSerialPort::tr(s: "Error writing to device"); |
41 | break; |
42 | case QSerialPort::ResourceError: |
43 | errorString = QSerialPort::tr(s: "Device disappeared from the system"); |
44 | break; |
45 | default: |
46 | // an empty string will be interpreted as "Unknown error" |
47 | // from the QIODevice::errorString() |
48 | break; |
49 | } |
50 | } |
51 | } |
52 | |
53 | QSerialPortPrivate::QSerialPortPrivate() |
54 | #if defined(Q_OS_WIN32) |
55 | : readChunkBuffer(QSERIALPORT_BUFFERSIZE, 0) |
56 | #endif |
57 | { |
58 | writeBufferChunkSize = QSERIALPORT_BUFFERSIZE; |
59 | readBufferChunkSize = QSERIALPORT_BUFFERSIZE; |
60 | } |
61 | |
62 | void QSerialPortPrivate::setError(const QSerialPortErrorInfo &errorInfo) |
63 | { |
64 | Q_Q(QSerialPort); |
65 | |
66 | q->setErrorString(errorInfo.errorString); |
67 | error.setValue(errorInfo.errorCode); |
68 | error.notify(); |
69 | emit q->errorOccurred(error); |
70 | } |
71 | |
72 | /*! |
73 | \class QSerialPort |
74 | |
75 | \brief Provides functions to access serial ports. |
76 | |
77 | \reentrant |
78 | \ingroup serialport-main |
79 | \inmodule QtSerialPort |
80 | \since 5.1 |
81 | |
82 | You can get information about the available serial ports using the |
83 | QSerialPortInfo helper class, which allows an enumeration of all the serial |
84 | ports in the system. This is useful to obtain the correct name of the |
85 | serial port you want to use. You can pass an object |
86 | of the helper class as an argument to the setPort() or setPortName() |
87 | methods to assign the desired serial device. |
88 | |
89 | After setting the port, you can open it in read-only (r/o), write-only |
90 | (w/o), or read-write (r/w) mode using the open() method. |
91 | |
92 | \note The serial port is always opened with exclusive access |
93 | (that is, no other process or thread can access an already opened serial port). |
94 | |
95 | Use the close() method to close the port and cancel the I/O operations. |
96 | |
97 | Having successfully opened, QSerialPort tries to determine the current |
98 | configuration of the port and initializes itself. You can reconfigure the |
99 | port to the desired setting using the setBaudRate(), setDataBits(), |
100 | setParity(), setStopBits(), and setFlowControl() methods. |
101 | |
102 | There are a couple of properties to work with the pinout signals namely: |
103 | QSerialPort::dataTerminalReady, QSerialPort::requestToSend. It is also |
104 | possible to use the pinoutSignals() method to query the current pinout |
105 | signals set. |
106 | |
107 | Once you know that the ports are ready to read or write, you can |
108 | use the read() or write() methods. Alternatively the |
109 | readLine() and readAll() convenience methods can also be invoked. |
110 | If not all the data is read at once, the remaining data will |
111 | be available for later as new incoming data is appended to the |
112 | QSerialPort's internal read buffer. You can limit the size of the read |
113 | buffer using setReadBufferSize(). |
114 | |
115 | QSerialPort provides a set of functions that suspend the |
116 | calling thread until certain signals are emitted. These functions |
117 | can be used to implement blocking serial ports: |
118 | |
119 | \list |
120 | |
121 | \li waitForReadyRead() blocks calls until new data is available for |
122 | reading. |
123 | |
124 | \li waitForBytesWritten() blocks calls until one payload of data has |
125 | been written to the serial port. |
126 | |
127 | \endlist |
128 | |
129 | See the following example: |
130 | |
131 | \code |
132 | qint64 numReadTotal = 0; |
133 | char buffer[50]; |
134 | |
135 | for (;;) { |
136 | const qint64 numRead = serial.read(buffer, 50); |
137 | |
138 | // Do whatever with the array |
139 | |
140 | numReadTotal += numRead; |
141 | if (numRead == 0 && !serial.waitForReadyRead()) |
142 | break; |
143 | } |
144 | \endcode |
145 | |
146 | If \l{QIODevice::}{waitForReadyRead()} returns \c false, the |
147 | connection has been closed or an error has occurred. |
148 | |
149 | If an error occurs at any point in time, QSerialPort will emit the |
150 | errorOccurred() signal. You can also call error() to find the type of |
151 | error that occurred last. |
152 | |
153 | Programming with a blocking serial port is radically different from |
154 | programming with a non-blocking serial port. A blocking serial port |
155 | does not require an event loop and typically leads to simpler code. |
156 | However, in a GUI application, blocking serial port should only be |
157 | used in non-GUI threads, to avoid freezing the user interface. |
158 | |
159 | For more details about these approaches, refer to the |
160 | \l {Qt Serial Port Examples}{example} applications. |
161 | |
162 | The QSerialPort class can also be used with QTextStream and QDataStream's |
163 | stream operators (operator<<() and operator>>()). There is one issue to be |
164 | aware of, though: make sure that enough data is available before attempting |
165 | to read by using the operator>>() overloaded operator. |
166 | |
167 | \sa QSerialPortInfo |
168 | */ |
169 | |
170 | /*! |
171 | \enum QSerialPort::Direction |
172 | |
173 | This enum describes the possible directions of the data transmission. |
174 | |
175 | \note This enumeration is used for setting the baud rate of the device |
176 | separately for each direction on some operating systems (for example, |
177 | POSIX-like). |
178 | |
179 | \value Input Input direction. |
180 | \value Output Output direction. |
181 | \value AllDirections Simultaneously in two directions. |
182 | */ |
183 | |
184 | /*! |
185 | \enum QSerialPort::BaudRate |
186 | |
187 | This enum describes the baud rate which the communication device operates |
188 | with. |
189 | |
190 | \note Only the most common standard baud rates are listed in this enum. |
191 | |
192 | \value Baud1200 1200 baud. |
193 | \value Baud2400 2400 baud. |
194 | \value Baud4800 4800 baud. |
195 | \value Baud9600 9600 baud. |
196 | \value Baud19200 19200 baud. |
197 | \value Baud38400 38400 baud. |
198 | \value Baud57600 57600 baud. |
199 | \value Baud115200 115200 baud. |
200 | |
201 | \sa QSerialPort::baudRate |
202 | */ |
203 | |
204 | /*! |
205 | \enum QSerialPort::DataBits |
206 | |
207 | This enum describes the number of data bits used. |
208 | |
209 | \value Data5 The number of data bits in each character is 5. It |
210 | is used for Baudot code. It generally only makes |
211 | sense with older equipment such as teleprinters. |
212 | \value Data6 The number of data bits in each character is 6. It |
213 | is rarely used. |
214 | \value Data7 The number of data bits in each character is 7. It |
215 | is used for true ASCII. It generally only makes |
216 | sense with older equipment such as teleprinters. |
217 | \value Data8 The number of data bits in each character is 8. It |
218 | is used for most kinds of data, as this size matches |
219 | the size of a byte. It is almost universally used in |
220 | newer applications. |
221 | |
222 | \sa QSerialPort::dataBits |
223 | */ |
224 | |
225 | /*! |
226 | \enum QSerialPort::Parity |
227 | |
228 | This enum describes the parity scheme used. |
229 | |
230 | \value NoParity No parity bit it sent. This is the most common |
231 | parity setting. Error detection is handled by the |
232 | communication protocol. |
233 | \value EvenParity The number of 1 bits in each character, including |
234 | the parity bit, is always even. |
235 | \value OddParity The number of 1 bits in each character, including |
236 | the parity bit, is always odd. It ensures that at |
237 | least one state transition occurs in each character. |
238 | \value SpaceParity Space parity. The parity bit is sent in the space |
239 | signal condition. It does not provide error |
240 | detection information. |
241 | \value MarkParity Mark parity. The parity bit is always set to the |
242 | mark signal condition (logical 1). It does not |
243 | provide error detection information. |
244 | |
245 | \sa QSerialPort::parity |
246 | */ |
247 | |
248 | /*! |
249 | \enum QSerialPort::StopBits |
250 | |
251 | This enum describes the number of stop bits used. |
252 | |
253 | \value OneStop 1 stop bit. |
254 | \value OneAndHalfStop 1.5 stop bits. This is only for the Windows platform. |
255 | \value TwoStop 2 stop bits. |
256 | |
257 | \sa QSerialPort::stopBits |
258 | */ |
259 | |
260 | /*! |
261 | \enum QSerialPort::FlowControl |
262 | |
263 | This enum describes the flow control used. |
264 | |
265 | \value NoFlowControl No flow control. |
266 | \value HardwareControl Hardware flow control (RTS/CTS). |
267 | \value SoftwareControl Software flow control (XON/XOFF). |
268 | |
269 | \sa QSerialPort::flowControl |
270 | */ |
271 | |
272 | /*! |
273 | \enum QSerialPort::PinoutSignal |
274 | |
275 | This enum describes the possible RS-232 pinout signals. |
276 | |
277 | \value NoSignal No line active |
278 | \value DataTerminalReadySignal DTR (Data Terminal Ready). |
279 | \value DataCarrierDetectSignal DCD (Data Carrier Detect). |
280 | \value DataSetReadySignal DSR (Data Set Ready). |
281 | \value RingIndicatorSignal RNG (Ring Indicator). |
282 | \value RequestToSendSignal RTS (Request To Send). |
283 | \value ClearToSendSignal CTS (Clear To Send). |
284 | \value SecondaryTransmittedDataSignal STD (Secondary Transmitted Data). |
285 | \value SecondaryReceivedDataSignal SRD (Secondary Received Data). |
286 | |
287 | \sa pinoutSignals(), QSerialPort::dataTerminalReady, |
288 | QSerialPort::requestToSend |
289 | */ |
290 | |
291 | /*! |
292 | \enum QSerialPort::SerialPortError |
293 | |
294 | This enum describes the errors that may be contained by the |
295 | QSerialPort::error property. |
296 | |
297 | \value NoError No error occurred. |
298 | |
299 | \value DeviceNotFoundError An error occurred while attempting to |
300 | open an non-existing device. |
301 | |
302 | \value PermissionError An error occurred while attempting to |
303 | open an already opened device by another |
304 | process or a user not having enough permission |
305 | and credentials to open. |
306 | |
307 | \value OpenError An error occurred while attempting to open an |
308 | already opened device in this object. |
309 | |
310 | \value NotOpenError This error occurs when an operation is executed |
311 | that can only be successfully performed if the |
312 | device is open. This value was introduced in |
313 | QtSerialPort 5.2. |
314 | |
315 | \value WriteError An I/O error occurred while writing the data. |
316 | |
317 | \value ReadError An I/O error occurred while reading the data. |
318 | |
319 | \value ResourceError An I/O error occurred when a resource becomes |
320 | unavailable, e.g. when the device is |
321 | unexpectedly removed from the system. |
322 | |
323 | \value UnsupportedOperationError The requested device operation is not |
324 | supported or prohibited by the running operating |
325 | system. |
326 | |
327 | \value TimeoutError A timeout error occurred. This value was |
328 | introduced in QtSerialPort 5.2. |
329 | |
330 | \value UnknownError An unidentified error occurred. |
331 | \sa QSerialPort::error |
332 | */ |
333 | |
334 | |
335 | |
336 | /*! |
337 | Constructs a new serial port object with the given \a parent. |
338 | */ |
339 | QSerialPort::QSerialPort(QObject *parent) |
340 | : QIODevice(*new QSerialPortPrivate, parent) |
341 | { |
342 | } |
343 | |
344 | /*! |
345 | Constructs a new serial port object with the given \a parent |
346 | to represent the serial port with the specified \a name. |
347 | |
348 | The name should have a specific format; see the setPort() method. |
349 | */ |
350 | QSerialPort::QSerialPort(const QString &name, QObject *parent) |
351 | : QIODevice(*new QSerialPortPrivate, parent) |
352 | { |
353 | setPortName(name); |
354 | } |
355 | |
356 | /*! |
357 | Constructs a new serial port object with the given \a parent |
358 | to represent the serial port with the specified helper class |
359 | \a serialPortInfo. |
360 | */ |
361 | QSerialPort::QSerialPort(const QSerialPortInfo &serialPortInfo, QObject *parent) |
362 | : QIODevice(*new QSerialPortPrivate, parent) |
363 | { |
364 | setPort(serialPortInfo); |
365 | } |
366 | |
367 | /*! |
368 | Closes the serial port, if necessary, and then destroys object. |
369 | */ |
370 | QSerialPort::~QSerialPort() |
371 | { |
372 | /**/ |
373 | if (isOpen()) |
374 | close(); |
375 | } |
376 | |
377 | /*! |
378 | Sets the \a name of the serial port. |
379 | |
380 | The name of the serial port can be passed as either a short name or |
381 | the long system location if necessary. |
382 | |
383 | \sa portName(), QSerialPortInfo |
384 | */ |
385 | void QSerialPort::setPortName(const QString &name) |
386 | { |
387 | Q_D(QSerialPort); |
388 | d->systemLocation = QSerialPortInfoPrivate::portNameToSystemLocation(source: name); |
389 | } |
390 | |
391 | /*! |
392 | Sets the port stored in the serial port info instance \a serialPortInfo. |
393 | |
394 | \sa portName(), QSerialPortInfo |
395 | */ |
396 | void QSerialPort::setPort(const QSerialPortInfo &serialPortInfo) |
397 | { |
398 | Q_D(QSerialPort); |
399 | d->systemLocation = serialPortInfo.systemLocation(); |
400 | } |
401 | |
402 | /*! |
403 | Returns the name set by setPort() or passed to the QSerialPort constructor. |
404 | This name is short, i.e. it is extracted and converted from the internal |
405 | variable system location of the device. The conversion algorithm is |
406 | platform specific: |
407 | \table |
408 | \header |
409 | \li Platform |
410 | \li Brief Description |
411 | \row |
412 | \li Windows |
413 | \li Removes the prefix "\\\\.\\" or "//./" from the system location |
414 | and returns the remainder of the string. |
415 | \row |
416 | \li Unix, BSD |
417 | \li Removes the prefix "/dev/" from the system location |
418 | and returns the remainder of the string. |
419 | \endtable |
420 | |
421 | \sa setPort(), QSerialPortInfo::portName() |
422 | */ |
423 | QString QSerialPort::portName() const |
424 | { |
425 | Q_D(const QSerialPort); |
426 | return QSerialPortInfoPrivate::portNameFromSystemLocation(source: d->systemLocation); |
427 | } |
428 | |
429 | /*! |
430 | \reimp |
431 | |
432 | Opens the serial port using OpenMode \a mode, and then returns \c true if |
433 | successful; otherwise returns \c false and sets an error code which can be |
434 | obtained by calling the error() method. |
435 | |
436 | If the port is opened, but setting the desired port parameters fails, the |
437 | method returns \c false and closes the port automatically. |
438 | |
439 | \warning The \a mode has to be QIODeviceBase::ReadOnly, QIODeviceBase::WriteOnly, |
440 | or QIODeviceBase::ReadWrite. Other modes are unsupported. |
441 | |
442 | \note Due to historical reasons, upon a successful open the |
443 | \l errorOccurred() signal is emitted with the \l {QSerialPort::}{NoError} |
444 | error code. This behavior is preserved to keep backwards compatibility. |
445 | |
446 | \sa QIODeviceBase::OpenMode, setPort() |
447 | */ |
448 | bool QSerialPort::open(OpenMode mode) |
449 | { |
450 | Q_D(QSerialPort); |
451 | |
452 | if (isOpen()) { |
453 | d->setError(QSerialPortErrorInfo(QSerialPort::OpenError)); |
454 | return false; |
455 | } |
456 | |
457 | // Define while not supported modes. |
458 | static const OpenMode unsupportedModes = Append | Truncate | Text | Unbuffered; |
459 | if ((mode & unsupportedModes) || mode == NotOpen) { |
460 | d->setError(QSerialPortErrorInfo(QSerialPort::UnsupportedOperationError, tr(s: "Unsupported open mode"))); |
461 | return false; |
462 | } |
463 | |
464 | clearError(); |
465 | if (!d->open(mode)) |
466 | return false; |
467 | |
468 | QIODevice::open(mode); |
469 | return true; |
470 | } |
471 | |
472 | /*! |
473 | \reimp |
474 | |
475 | \note The serial port has to be open before trying to close it; otherwise |
476 | sets the NotOpenError error code. |
477 | |
478 | \sa QIODevice::close() |
479 | */ |
480 | void QSerialPort::close() |
481 | { |
482 | Q_D(QSerialPort); |
483 | if (!isOpen()) { |
484 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
485 | return; |
486 | } |
487 | |
488 | d->close(); |
489 | d->isBreakEnabled.setValue(false); |
490 | QIODevice::close(); |
491 | } |
492 | |
493 | /*! |
494 | \property QSerialPort::baudRate |
495 | \brief the data baud rate for the desired direction |
496 | |
497 | If the setting is successful or set before opening the port, returns \c true; |
498 | otherwise returns \c false and sets an error code which can be obtained by |
499 | accessing the value of the QSerialPort::error property. To set the baud |
500 | rate, use the enumeration QSerialPort::BaudRate or any positive qint32 |
501 | value. |
502 | |
503 | \note If the setting is set before opening the port, the actual serial port |
504 | setting is done automatically in the \l{QSerialPort::open()} method right |
505 | after that the opening of the port succeeds. |
506 | |
507 | \warning Setting the AllDirections flag is supported on all platforms. |
508 | Windows supports only this mode. |
509 | |
510 | \warning Returns equal baud rate in any direction on Windows. |
511 | |
512 | The default value is Baud9600, i.e. 9600 bits per second. |
513 | */ |
514 | bool QSerialPort::setBaudRate(qint32 baudRate, Directions directions) |
515 | { |
516 | Q_D(QSerialPort); |
517 | |
518 | if (!isOpen() || d->setBaudRate(baudRate, directions)) { |
519 | if (directions & QSerialPort::Input) { |
520 | if (d->inputBaudRate != baudRate) |
521 | d->inputBaudRate = baudRate; |
522 | else |
523 | directions &= ~QSerialPort::Input; |
524 | } |
525 | |
526 | if (directions & QSerialPort::Output) { |
527 | if (d->outputBaudRate != baudRate) |
528 | d->outputBaudRate = baudRate; |
529 | else |
530 | directions &= ~QSerialPort::Output; |
531 | } |
532 | |
533 | if (directions) |
534 | emit baudRateChanged(baudRate, directions); |
535 | |
536 | return true; |
537 | } |
538 | |
539 | return false; |
540 | } |
541 | |
542 | qint32 QSerialPort::baudRate(Directions directions) const |
543 | { |
544 | Q_D(const QSerialPort); |
545 | if (directions == QSerialPort::AllDirections) |
546 | return d->inputBaudRate == d->outputBaudRate ? |
547 | d->inputBaudRate : -1; |
548 | return directions & QSerialPort::Input ? d->inputBaudRate : d->outputBaudRate; |
549 | } |
550 | |
551 | /*! |
552 | \fn void QSerialPort::baudRateChanged(qint32 baudRate, Directions directions) |
553 | |
554 | This signal is emitted after the baud rate has been changed. The new baud |
555 | rate is passed as \a baudRate and directions as \a directions. |
556 | |
557 | \sa QSerialPort::baudRate |
558 | */ |
559 | |
560 | /*! |
561 | \property QSerialPort::dataBits |
562 | \brief the data bits in a frame |
563 | |
564 | If the setting is successful or set before opening the port, returns |
565 | \c true; otherwise returns \c false and sets an error code which can be obtained |
566 | by accessing the value of the QSerialPort::error property. |
567 | |
568 | \note If the setting is set before opening the port, the actual serial port |
569 | setting is done automatically in the \l{QSerialPort::open()} method right |
570 | after that the opening of the port succeeds. |
571 | |
572 | The default value is Data8, i.e. 8 data bits. |
573 | */ |
574 | bool QSerialPort::setDataBits(DataBits dataBits) |
575 | { |
576 | Q_D(QSerialPort); |
577 | d->dataBits.removeBindingUnlessInWrapper(); |
578 | const auto currentDataBits = d->dataBits.valueBypassingBindings(); |
579 | if (!isOpen() || d->setDataBits(dataBits)) { |
580 | d->dataBits.setValueBypassingBindings(dataBits); |
581 | if (currentDataBits != dataBits) { |
582 | d->dataBits.notify(); |
583 | emit dataBitsChanged(dataBits); |
584 | } |
585 | return true; |
586 | } |
587 | return false; |
588 | } |
589 | |
590 | QSerialPort::DataBits QSerialPort::dataBits() const |
591 | { |
592 | Q_D(const QSerialPort); |
593 | return d->dataBits; |
594 | } |
595 | |
596 | QBindable<QSerialPort::DataBits> QSerialPort::bindableDataBits() |
597 | { |
598 | return &d_func()->dataBits; |
599 | } |
600 | |
601 | /*! |
602 | \fn void QSerialPort::dataBitsChanged(DataBits dataBits) |
603 | |
604 | This signal is emitted after the data bits in a frame has been changed. The |
605 | new data bits in a frame is passed as \a dataBits. |
606 | |
607 | \sa QSerialPort::dataBits |
608 | */ |
609 | |
610 | |
611 | /*! |
612 | \property QSerialPort::parity |
613 | \brief the parity checking mode |
614 | |
615 | If the setting is successful or set before opening the port, returns \c true; |
616 | otherwise returns \c false and sets an error code which can be obtained by |
617 | accessing the value of the QSerialPort::error property. |
618 | |
619 | \note If the setting is set before opening the port, the actual serial port |
620 | setting is done automatically in the \l{QSerialPort::open()} method right |
621 | after that the opening of the port succeeds. |
622 | |
623 | The default value is NoParity, i.e. no parity. |
624 | */ |
625 | bool QSerialPort::setParity(Parity parity) |
626 | { |
627 | Q_D(QSerialPort); |
628 | d->parity.removeBindingUnlessInWrapper(); |
629 | const auto currentParity = d->parity.valueBypassingBindings(); |
630 | if (!isOpen() || d->setParity(parity)) { |
631 | d->parity.setValueBypassingBindings(parity); |
632 | if (currentParity != parity) { |
633 | d->parity.notify(); |
634 | emit parityChanged(parity); |
635 | } |
636 | return true; |
637 | } |
638 | return false; |
639 | } |
640 | |
641 | QSerialPort::Parity QSerialPort::parity() const |
642 | { |
643 | Q_D(const QSerialPort); |
644 | return d->parity; |
645 | } |
646 | |
647 | QBindable<QSerialPort::Parity> QSerialPort::bindableParity() |
648 | { |
649 | return &d_func()->parity; |
650 | } |
651 | |
652 | /*! |
653 | \fn void QSerialPort::parityChanged(Parity parity) |
654 | |
655 | This signal is emitted after the parity checking mode has been changed. The |
656 | new parity checking mode is passed as \a parity. |
657 | |
658 | \sa QSerialPort::parity |
659 | */ |
660 | |
661 | /*! |
662 | \property QSerialPort::stopBits |
663 | \brief the number of stop bits in a frame |
664 | |
665 | If the setting is successful or set before opening the port, returns \c true; |
666 | otherwise returns \c false and sets an error code which can be obtained by |
667 | accessing the value of the QSerialPort::error property. |
668 | |
669 | \note If the setting is set before opening the port, the actual serial port |
670 | setting is done automatically in the \l{QSerialPort::open()} method right |
671 | after that the opening of the port succeeds. |
672 | |
673 | The default value is OneStop, i.e. 1 stop bit. |
674 | */ |
675 | bool QSerialPort::setStopBits(StopBits stopBits) |
676 | { |
677 | Q_D(QSerialPort); |
678 | d->stopBits.removeBindingUnlessInWrapper(); |
679 | const auto currentStopBits = d->stopBits.valueBypassingBindings(); |
680 | if (!isOpen() || d->setStopBits(stopBits)) { |
681 | d->stopBits.setValueBypassingBindings(stopBits); |
682 | if (currentStopBits != stopBits) { |
683 | d->stopBits.notify(); |
684 | emit stopBitsChanged(stopBits); |
685 | } |
686 | return true; |
687 | } |
688 | return false; |
689 | } |
690 | |
691 | QSerialPort::StopBits QSerialPort::stopBits() const |
692 | { |
693 | Q_D(const QSerialPort); |
694 | return d->stopBits; |
695 | } |
696 | |
697 | QBindable<QSerialPort::StopBits> QSerialPort::bindableStopBits(QT6_IMPL_NEW_OVERLOAD) |
698 | { |
699 | return &d_func()->stopBits; |
700 | } |
701 | |
702 | /*! |
703 | \fn void QSerialPort::stopBitsChanged(StopBits stopBits) |
704 | |
705 | This signal is emitted after the number of stop bits in a frame has been |
706 | changed. The new number of stop bits in a frame is passed as \a stopBits. |
707 | |
708 | \sa QSerialPort::stopBits |
709 | */ |
710 | |
711 | /*! |
712 | \property QSerialPort::flowControl |
713 | \brief the desired flow control mode |
714 | |
715 | If the setting is successful or set before opening the port, returns \c true; |
716 | otherwise returns \c false and sets an error code which can be obtained by |
717 | accessing the value of the QSerialPort::error property. |
718 | |
719 | \note If the setting is set before opening the port, the actual serial port |
720 | setting is done automatically in the \l{QSerialPort::open()} method right |
721 | after that the opening of the port succeeds. |
722 | |
723 | The default value is NoFlowControl, i.e. no flow control. |
724 | */ |
725 | bool QSerialPort::setFlowControl(FlowControl flowControl) |
726 | { |
727 | Q_D(QSerialPort); |
728 | d->flowControl.removeBindingUnlessInWrapper(); |
729 | const auto currentFlowControl = d->flowControl.valueBypassingBindings(); |
730 | if (!isOpen() || d->setFlowControl(flowControl)) { |
731 | d->flowControl.setValueBypassingBindings(flowControl); |
732 | if (currentFlowControl != flowControl) { |
733 | d->flowControl.notify(); |
734 | emit flowControlChanged(flowControl); |
735 | } |
736 | return true; |
737 | } |
738 | return false; |
739 | } |
740 | |
741 | QSerialPort::FlowControl QSerialPort::flowControl() const |
742 | { |
743 | Q_D(const QSerialPort); |
744 | return d->flowControl; |
745 | } |
746 | |
747 | QBindable<QSerialPort::FlowControl> QSerialPort::bindableFlowControl() |
748 | { |
749 | return &d_func()->flowControl; |
750 | } |
751 | |
752 | /*! |
753 | \fn void QSerialPort::flowControlChanged(FlowControl flow) |
754 | |
755 | This signal is emitted after the flow control mode has been changed. The |
756 | new flow control mode is passed as \a flow. |
757 | |
758 | \sa QSerialPort::flowControl |
759 | */ |
760 | |
761 | /*! |
762 | \property QSerialPort::dataTerminalReady |
763 | \brief the state (high or low) of the line signal DTR |
764 | |
765 | Returns \c true on success, \c false otherwise. |
766 | If the flag is \c true then the DTR signal is set to high; otherwise low. |
767 | |
768 | \note The serial port has to be open before trying to set or get this |
769 | property; otherwise \c false is returned and the error code is set to |
770 | NotOpenError. |
771 | |
772 | \sa pinoutSignals() |
773 | */ |
774 | bool QSerialPort::setDataTerminalReady(bool set) |
775 | { |
776 | Q_D(QSerialPort); |
777 | |
778 | if (!isOpen()) { |
779 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
780 | qWarning(msg: "%s: device not open", Q_FUNC_INFO); |
781 | return false; |
782 | } |
783 | |
784 | const bool dataTerminalReady = isDataTerminalReady(); |
785 | const bool retval = d->setDataTerminalReady(set); |
786 | if (retval && (dataTerminalReady != set)) |
787 | emit dataTerminalReadyChanged(set); |
788 | |
789 | return retval; |
790 | } |
791 | |
792 | bool QSerialPort::isDataTerminalReady() |
793 | { |
794 | Q_D(QSerialPort); |
795 | return d->pinoutSignals() & QSerialPort::DataTerminalReadySignal; |
796 | } |
797 | |
798 | /*! |
799 | \fn void QSerialPort::dataTerminalReadyChanged(bool set) |
800 | |
801 | This signal is emitted after the state (high or low) of the line signal DTR |
802 | has been changed. The new the state (high or low) of the line signal DTR is |
803 | passed as \a set. |
804 | |
805 | \sa QSerialPort::dataTerminalReady |
806 | */ |
807 | |
808 | /*! |
809 | \property QSerialPort::requestToSend |
810 | \brief the state (high or low) of the line signal RTS |
811 | |
812 | Returns \c true on success, \c false otherwise. |
813 | If the flag is \c true then the RTS signal is set to high; otherwise low. |
814 | |
815 | \note The serial port has to be open before trying to set or get this |
816 | property; otherwise \c false is returned and the error code is set to |
817 | NotOpenError. |
818 | |
819 | \note An attempt to control the RTS signal in the HardwareControl mode |
820 | will fail with error code set to UnsupportedOperationError, because |
821 | the signal is automatically controlled by the driver. |
822 | |
823 | \sa pinoutSignals() |
824 | */ |
825 | bool QSerialPort::setRequestToSend(bool set) |
826 | { |
827 | Q_D(QSerialPort); |
828 | |
829 | if (!isOpen()) { |
830 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
831 | qWarning(msg: "%s: device not open", Q_FUNC_INFO); |
832 | return false; |
833 | } |
834 | |
835 | if (d->flowControl == QSerialPort::HardwareControl) { |
836 | d->setError(QSerialPortErrorInfo(QSerialPort::UnsupportedOperationError)); |
837 | return false; |
838 | } |
839 | |
840 | const bool requestToSend = isRequestToSend(); |
841 | const bool retval = d->setRequestToSend(set); |
842 | if (retval && (requestToSend != set)) |
843 | emit requestToSendChanged(set); |
844 | |
845 | return retval; |
846 | } |
847 | |
848 | bool QSerialPort::isRequestToSend() |
849 | { |
850 | Q_D(QSerialPort); |
851 | return d->pinoutSignals() & QSerialPort::RequestToSendSignal; |
852 | } |
853 | |
854 | /*! |
855 | \fn void QSerialPort::requestToSendChanged(bool set) |
856 | |
857 | This signal is emitted after the state (high or low) of the line signal RTS |
858 | has been changed. The new the state (high or low) of the line signal RTS is |
859 | passed as \a set. |
860 | |
861 | \sa QSerialPort::requestToSend |
862 | */ |
863 | |
864 | /*! |
865 | Returns the state of the line signals in a bitmap format. |
866 | |
867 | From this result, it is possible to allocate the state of the |
868 | desired signal by applying a mask "AND", where the mask is |
869 | the desired enumeration value from QSerialPort::PinoutSignals. |
870 | |
871 | \note This method performs a system call, thus ensuring that the line signal |
872 | states are returned properly. This is necessary when the underlying |
873 | operating systems cannot provide proper notifications about the changes. |
874 | |
875 | \note The serial port has to be open before trying to get the pinout |
876 | signals; otherwise returns NoSignal and sets the NotOpenError error code. |
877 | |
878 | \sa QSerialPort::dataTerminalReady, QSerialPort::requestToSend |
879 | */ |
880 | QSerialPort::PinoutSignals QSerialPort::pinoutSignals() |
881 | { |
882 | Q_D(QSerialPort); |
883 | |
884 | if (!isOpen()) { |
885 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
886 | qWarning(msg: "%s: device not open", Q_FUNC_INFO); |
887 | return QSerialPort::NoSignal; |
888 | } |
889 | |
890 | return d->pinoutSignals(); |
891 | } |
892 | |
893 | /*! |
894 | This function writes as much as possible from the internal write |
895 | buffer to the underlying serial port without blocking. If any data |
896 | was written, this function returns \c true; otherwise returns \c false. |
897 | |
898 | Call this function for sending the buffered data immediately to the serial |
899 | port. The number of bytes successfully written depends on the operating |
900 | system. In most cases, this function does not need to be called, because the |
901 | QSerialPort class will start sending data automatically once control is |
902 | returned to the event loop. In the absence of an event loop, call |
903 | waitForBytesWritten() instead. |
904 | |
905 | \note The serial port has to be open before trying to flush any buffered |
906 | data; otherwise returns \c false and sets the NotOpenError error code. |
907 | |
908 | \sa write(), waitForBytesWritten() |
909 | */ |
910 | bool QSerialPort::flush() |
911 | { |
912 | Q_D(QSerialPort); |
913 | |
914 | if (!isOpen()) { |
915 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
916 | qWarning(msg: "%s: device not open", Q_FUNC_INFO); |
917 | return false; |
918 | } |
919 | |
920 | return d->flush(); |
921 | } |
922 | |
923 | /*! |
924 | Discards all characters from the output or input buffer, depending on |
925 | given directions \a directions. This includes clearing the internal class buffers and |
926 | the UART (driver) buffers. Also terminate pending read or write operations. |
927 | If successful, returns \c true; otherwise returns \c false. |
928 | |
929 | \note The serial port has to be open before trying to clear any buffered |
930 | data; otherwise returns \c false and sets the NotOpenError error code. |
931 | */ |
932 | bool QSerialPort::clear(Directions directions) |
933 | { |
934 | Q_D(QSerialPort); |
935 | |
936 | if (!isOpen()) { |
937 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
938 | qWarning(msg: "%s: device not open", Q_FUNC_INFO); |
939 | return false; |
940 | } |
941 | |
942 | if (directions & Input) |
943 | d->buffer.clear(); |
944 | if (directions & Output) |
945 | d->writeBuffer.clear(); |
946 | return d->clear(directions); |
947 | } |
948 | |
949 | /*! |
950 | \property QSerialPort::error |
951 | \brief the error status of the serial port |
952 | |
953 | The I/O device status returns an error code. For example, if open() |
954 | returns \c false, or a read/write operation returns \c -1, this property can |
955 | be used to figure out the reason why the operation failed. |
956 | |
957 | The error code is set to the default QSerialPort::NoError after a call to |
958 | clearError() |
959 | */ |
960 | QSerialPort::SerialPortError QSerialPort::error() const |
961 | { |
962 | Q_D(const QSerialPort); |
963 | return d->error; |
964 | } |
965 | |
966 | void QSerialPort::clearError() |
967 | { |
968 | Q_D(QSerialPort); |
969 | d->setError(QSerialPortErrorInfo(QSerialPort::NoError)); |
970 | } |
971 | |
972 | QBindable<QSerialPort::SerialPortError> QSerialPort::bindableError() const |
973 | { |
974 | return &d_func()->error; |
975 | } |
976 | |
977 | /*! |
978 | \fn void QSerialPort::errorOccurred(SerialPortError error) |
979 | \since 5.8 |
980 | |
981 | This signal is emitted when an error occurs in the serial port. |
982 | The specified \a error describes the type of error that occurred. |
983 | |
984 | \sa QSerialPort::error |
985 | */ |
986 | |
987 | /*! |
988 | Returns the size of the internal read buffer. This limits the |
989 | amount of data that the client can receive before calling the read() |
990 | or readAll() methods. |
991 | |
992 | A read buffer size of \c 0 (the default) means that the buffer has |
993 | no size limit, ensuring that no data is lost. |
994 | |
995 | \sa setReadBufferSize(), read() |
996 | */ |
997 | qint64 QSerialPort::readBufferSize() const |
998 | { |
999 | Q_D(const QSerialPort); |
1000 | return d->readBufferMaxSize; |
1001 | } |
1002 | |
1003 | /*! |
1004 | Sets the size of QSerialPort's internal read buffer to be \a |
1005 | size bytes. |
1006 | |
1007 | If the buffer size is limited to a certain size, QSerialPort |
1008 | will not buffer more than this size of data. The special case of a buffer |
1009 | size of \c 0 means that the read buffer is unlimited and all |
1010 | incoming data is buffered. This is the default. |
1011 | |
1012 | This option is useful if the data is only read at certain points |
1013 | in time (for instance in a real-time streaming application) or if the serial |
1014 | port should be protected against receiving too much data, which may |
1015 | eventually cause the application to run out of memory. |
1016 | |
1017 | \sa readBufferSize(), read() |
1018 | */ |
1019 | void QSerialPort::setReadBufferSize(qint64 size) |
1020 | { |
1021 | Q_D(QSerialPort); |
1022 | d->readBufferMaxSize = size; |
1023 | if (isReadable()) |
1024 | d->startAsyncRead(); |
1025 | } |
1026 | |
1027 | /*! |
1028 | \reimp |
1029 | |
1030 | Always returns \c true. The serial port is a sequential device. |
1031 | */ |
1032 | bool QSerialPort::isSequential() const |
1033 | { |
1034 | return true; |
1035 | } |
1036 | |
1037 | /*! |
1038 | \reimp |
1039 | |
1040 | Returns the number of incoming bytes that are waiting to be read. |
1041 | |
1042 | \sa bytesToWrite(), read() |
1043 | */ |
1044 | qint64 QSerialPort::bytesAvailable() const |
1045 | { |
1046 | return QIODevice::bytesAvailable(); |
1047 | } |
1048 | |
1049 | /*! |
1050 | \reimp |
1051 | |
1052 | Returns the number of bytes that are waiting to be written. The |
1053 | bytes are written when control goes back to the event loop or |
1054 | when flush() is called. |
1055 | |
1056 | \sa bytesAvailable(), flush() |
1057 | */ |
1058 | qint64 QSerialPort::bytesToWrite() const |
1059 | { |
1060 | qint64 pendingBytes = QIODevice::bytesToWrite(); |
1061 | #if defined(Q_OS_WIN32) |
1062 | pendingBytes += d_func()->writeChunkBuffer.size(); |
1063 | #endif |
1064 | return pendingBytes; |
1065 | } |
1066 | |
1067 | /*! |
1068 | \reimp |
1069 | |
1070 | Returns \c true if a line of data can be read from the serial port; |
1071 | otherwise returns \c false. |
1072 | |
1073 | \sa readLine() |
1074 | */ |
1075 | bool QSerialPort::canReadLine() const |
1076 | { |
1077 | return QIODevice::canReadLine(); |
1078 | } |
1079 | |
1080 | /*! |
1081 | \reimp |
1082 | |
1083 | This function blocks until new data is available for reading and the |
1084 | \l{QIODevice::}{readyRead()} signal has been emitted. The function |
1085 | will timeout after \a msecs milliseconds; the default timeout is |
1086 | 30000 milliseconds. If \a msecs is -1, this function will not time out. |
1087 | |
1088 | The function returns \c true if the readyRead() signal is emitted and |
1089 | there is new data available for reading; otherwise it returns \c false |
1090 | (if an error occurred or the operation timed out). |
1091 | |
1092 | \sa waitForBytesWritten() |
1093 | */ |
1094 | bool QSerialPort::waitForReadyRead(int msecs) |
1095 | { |
1096 | Q_D(QSerialPort); |
1097 | return d->waitForReadyRead(msec: msecs); |
1098 | } |
1099 | |
1100 | /*! |
1101 | \fn Handle QSerialPort::handle() const |
1102 | \since 5.2 |
1103 | |
1104 | If the platform is supported and the serial port is open, returns the native |
1105 | serial port handle; otherwise returns \c -1. |
1106 | |
1107 | \warning This function is for expert use only; use it at your own risk. |
1108 | Furthermore, this function carries no compatibility promise between minor |
1109 | Qt releases. |
1110 | */ |
1111 | |
1112 | /*! |
1113 | \reimp |
1114 | |
1115 | This function blocks until at least one byte has been written to the serial |
1116 | port and the \l{QIODevice::}{bytesWritten()} signal has been emitted. The |
1117 | function will timeout after \a msecs milliseconds; the default timeout is |
1118 | 30000 milliseconds. If \a msecs is -1, this function will not time out. |
1119 | |
1120 | The function returns \c true if the bytesWritten() signal is emitted; otherwise |
1121 | it returns \c false (if an error occurred or the operation timed out). |
1122 | */ |
1123 | bool QSerialPort::waitForBytesWritten(int msecs) |
1124 | { |
1125 | Q_D(QSerialPort); |
1126 | return d->waitForBytesWritten(msec: msecs); |
1127 | } |
1128 | |
1129 | /*! |
1130 | \property QSerialPort::breakEnabled |
1131 | \since 5.5 |
1132 | \brief the state of the transmission line in break |
1133 | |
1134 | Returns \c true on success, \c false otherwise. |
1135 | If the flag is \c true then the transmission line is in break state; |
1136 | otherwise is in non-break state. |
1137 | |
1138 | \note The serial port has to be open before trying to set or get this |
1139 | property; otherwise returns \c false and sets the NotOpenError error code. |
1140 | This is a bit unusual as opposed to the regular Qt property settings of |
1141 | a class. However, this is a special use case since the property is set |
1142 | through the interaction with the kernel and hardware. Hence, the two |
1143 | scenarios cannot be completely compared to each other. |
1144 | */ |
1145 | bool QSerialPort::setBreakEnabled(bool set) |
1146 | { |
1147 | Q_D(QSerialPort); |
1148 | d->isBreakEnabled.removeBindingUnlessInWrapper(); |
1149 | const auto currentSet = d->isBreakEnabled.valueBypassingBindings(); |
1150 | if (isOpen()) { |
1151 | if (d->setBreakEnabled(set)) { |
1152 | d->isBreakEnabled.setValueBypassingBindings(set); |
1153 | if (currentSet != set) { |
1154 | d->isBreakEnabled.notify(); |
1155 | emit breakEnabledChanged(set); |
1156 | } |
1157 | return true; |
1158 | } |
1159 | } else { |
1160 | d->setError(QSerialPortErrorInfo(QSerialPort::NotOpenError)); |
1161 | qWarning(msg: "%s: device not open", Q_FUNC_INFO); |
1162 | } |
1163 | return false; |
1164 | } |
1165 | |
1166 | bool QSerialPort::isBreakEnabled() const |
1167 | { |
1168 | Q_D(const QSerialPort); |
1169 | return d->isBreakEnabled; |
1170 | } |
1171 | |
1172 | QBindable<bool> QSerialPort::bindableIsBreakEnabled() |
1173 | { |
1174 | return &d_func()->isBreakEnabled; |
1175 | } |
1176 | |
1177 | /*! |
1178 | \reimp |
1179 | |
1180 | \omit |
1181 | This function does not really read anything, as we use QIODevicePrivate's |
1182 | buffer. The buffer will be read inside of QIODevice before this |
1183 | method will be called. |
1184 | \endomit |
1185 | */ |
1186 | qint64 QSerialPort::readData(char *data, qint64 maxSize) |
1187 | { |
1188 | Q_UNUSED(data); |
1189 | Q_UNUSED(maxSize); |
1190 | |
1191 | // In any case we need to start the notifications if they were |
1192 | // disabled by the read handler. If enabled, next call does nothing. |
1193 | d_func()->startAsyncRead(); |
1194 | |
1195 | // return 0 indicating there may be more data in the future |
1196 | return qint64(0); |
1197 | } |
1198 | |
1199 | /*! |
1200 | \reimp |
1201 | */ |
1202 | qint64 QSerialPort::readLineData(char *data, qint64 maxSize) |
1203 | { |
1204 | return QIODevice::readLineData(data, maxlen: maxSize); |
1205 | } |
1206 | |
1207 | /*! |
1208 | \reimp |
1209 | */ |
1210 | qint64 QSerialPort::writeData(const char *data, qint64 maxSize) |
1211 | { |
1212 | Q_D(QSerialPort); |
1213 | return d->writeData(data, maxSize); |
1214 | } |
1215 | |
1216 | QT_END_NAMESPACE |
1217 | |
1218 | #include "moc_qserialport.cpp" |
1219 |
Definitions
- QSerialPortErrorInfo
- QSerialPortPrivate
- setError
- QSerialPort
- QSerialPort
- QSerialPort
- ~QSerialPort
- setPortName
- setPort
- portName
- open
- close
- setBaudRate
- baudRate
- setDataBits
- dataBits
- bindableDataBits
- setParity
- parity
- bindableParity
- setStopBits
- stopBits
- bindableStopBits
- setFlowControl
- flowControl
- bindableFlowControl
- setDataTerminalReady
- isDataTerminalReady
- setRequestToSend
- isRequestToSend
- pinoutSignals
- flush
- clear
- error
- clearError
- bindableError
- readBufferSize
- setReadBufferSize
- isSequential
- bytesAvailable
- bytesToWrite
- canReadLine
- waitForReadyRead
- waitForBytesWritten
- setBreakEnabled
- isBreakEnabled
- bindableIsBreakEnabled
- readData
- readLineData
Learn to use CMake with our Intro Training
Find out more