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

source code of qtserialport/src/serialport/qserialport.cpp