QCanBusDevice 类是用于 CAN 总线的接口类。 更多...
| 头： | #include <QCanBusDevice> |
| qmake: | QT += serialbus |
| Since: | Qt 5.8 |
| 继承： | QObject |
| struct | Filter |
| enum | CanBusDeviceState { UnconnectedState, ConnectingState, ConnectedState, ClosingState } |
| enum | CanBusError { NoError, ReadError, WriteError, ConnectionError, ConfigurationError, …, TimeoutError } |
| enum class | CanBusStatus { Unknown, Good, Warning, Error, BusOff } |
| enum | ConfigurationKey { RawFilterKey, ErrorFilterKey, LoopbackKey, ReceiveOwnKey, BitRateKey, …, UserKey } |
| enum | Direction { Input, Output, AllDirections } |
| flags | Directions |
| QCanBusDevice (QObject * parent = nullptr) | |
| virtual QCanBusDevice::CanBusStatus | busStatus () |
| void | clear (QCanBusDevice::Directions direction = Direction::AllDirections) |
| QList<QCanBusDevice::ConfigurationKey> | configurationKeys () const |
| QVariant | configurationParameter (QCanBusDevice::ConfigurationKey key ) const |
| bool | connectDevice () |
| virtual QCanBusDeviceInfo | deviceInfo () const |
| void | disconnectDevice () |
| QCanBusDevice::CanBusError | error () const |
| QString | errorString () const |
| qint64 | framesAvailable () const |
| qint64 | framesToWrite () const |
| virtual bool | hasBusStatus () const |
| virtual QString | interpretErrorFrame (const QCanBusFrame & frame ) = 0 |
| QList<QCanBusFrame> | readAllFrames () |
| QCanBusFrame | readFrame () |
| virtual void | resetController () |
| virtual void | setConfigurationParameter (QCanBusDevice::ConfigurationKey key , const QVariant & value ) |
| QCanBusDevice::CanBusDeviceState | state () const |
| virtual bool | waitForFramesReceived (int msecs ) |
| virtual bool | waitForFramesWritten (int msecs ) |
| virtual bool | writeFrame (const QCanBusFrame & frame ) = 0 |
| void | errorOccurred (QCanBusDevice::CanBusError) |
| void | framesReceived () |
| void | framesWritten (qint64 framesCount ) |
| void | stateChanged (QCanBusDevice::CanBusDeviceState state ) |
| void | clearError () |
| virtual void | close () = 0 |
| QCanBusFrame | dequeueOutgoingFrame () |
| void | enqueueOutgoingFrame (const QCanBusFrame & newFrame ) |
| void | enqueueReceivedFrames (const QList<QCanBusFrame> & newFrames ) |
| bool | hasOutgoingFrames () const |
| virtual bool | open () = 0 |
| void | setError (const QString & errorText , QCanBusDevice::CanBusError errorId ) |
| void | setState (QCanBusDevice::CanBusDeviceState newState ) |
QCanBusDevice communicates with a CAN plugin providing users with a convenient API. The CAN plugin must be specified during the object creation.
此枚举描述所有可能的设备状态。
| 常量 | 值 | 描述 |
|---|---|---|
QCanBusDevice::UnconnectedState
|
0
|
设备已断开连接。 |
QCanBusDevice::ConnectingState
|
1
|
设备正在连接。 |
QCanBusDevice::ConnectedState
|
2
|
设备已连接到 CAN Bus。 |
QCanBusDevice::ClosingState
|
3
|
设备正在关闭。 |
此枚举描述所有可能的错误条件。
| 常量 | 值 | 描述 |
|---|---|---|
QCanBusDevice::NoError
|
0
|
没有出现错误。 |
QCanBusDevice::ReadError
|
1
|
An error occurred during a read operation. |
QCanBusDevice::WriteError
|
2
|
An error occurred during a write operation. |
QCanBusDevice::ConnectionError
|
3
|
An error occurred when attempting to open the plugin. |
QCanBusDevice::ConfigurationError
|
4
|
An error occurred when attempting to set a configuration parameter. |
QCanBusDevice::UnknownError
|
5
|
出现未知错误。 |
QCanBusDevice::OperationError
|
6
|
An operation was attempted while the device was in a state that did not permit it. This enum was introduced in Qt 5.14. |
QCanBusDevice::TimeoutError
|
7
|
An timeout occurred while waiting for frames written or received. This enum was introduced in Qt 5.14. |
[since 5.14]
enum class QCanBusDevice::
CanBusStatus
此枚举描述可能的 CAN Bus 状态值。
| 常量 | 值 | 描述 |
|---|---|---|
QCanBusDevice::CanBusStatus::Unknown
|
0
|
The CAN bus status is unknown (e.g. not supported by the CAN plugin). |
QCanBusDevice::CanBusStatus::Good
|
1
|
The CAN controller is fully operational |
QCanBusDevice::CanBusStatus::Warning
|
2
|
The CAN controller is in warning status |
QCanBusDevice::CanBusStatus::Error
|
3
|
The CAN controller is in error status (no longer sending CAN frames) |
QCanBusDevice::CanBusStatus::BusOff
|
4
|
The CAN controller is in bus off status (disconnected from the CAN bus) |
该枚举在 Qt 5.14 引入或被修改。
This enum describes the possible configuration options for the CAN bus connection.
| 常量 | 值 | 描述 |
|---|---|---|
QCanBusDevice::RawFilterKey
|
0
|
This configuration determines the type of CAN bus frames that the current device accepts. The expected value is
QList<QCanBusDevice::Filter>
. Passing an empty list clears all previously set filters including default filters. For more details see
QCanBusDevice::Filter
.
|
QCanBusDevice::ErrorFilterKey
|
1
|
This key defines the type of error that should be forwarded via the current connection. The associated value should be of type QCanBusFrame::FrameErrors . |
QCanBusDevice::LoopbackKey
|
2
|
This key defines whether the CAN bus device should operate in loopback mode. Loopback means, whenever a CAN frame is transmitted on the CAN bus, a local echo of this frame is sent to all applications connected to this CAN device. The expected value for this key is
bool
.
|
QCanBusDevice::ReceiveOwnKey
|
3
|
This key defines whether this CAN device receives its own send frames. This can be used to check if the transmission was successful. The expected value for this key is
bool
.
|
QCanBusDevice::BitRateKey
|
4
|
This key defines the CAN bitrate in bits per second. With CAN FD, the payload can be transmitted at a higher data bitrate, if
QCanBusFrame::hasBitrateSwitch
() is set. In this case,
QCanBusDevice::BitRateKey
is only used for the CAN ID arbitration phase. See also
QCanBusDevice::DataBitRateKey
|
QCanBusDevice::CanFdKey
|
5
|
This key defines whether sending and receiving of CAN FD frames should be enabled. The expected value for this key is
bool
.
|
QCanBusDevice::DataBitRateKey
|
6
|
This key defines the CAN FD payload bitrate in bits per second. CAN FD allows to transmit the payload of frames with
QCanBusFrame::hasBitrateSwitch
() flag at a higher data bitrate, after the arbitration phase at the nominal bitrate is finished. This enum value was introduced in Qt 5.9. See also
QCanBusDevice::BitRateKey
|
QCanBusDevice::ProtocolKey
|
7
|
This key allows to specify another protocol. For now, this parameter can only be set and used in the SocketCAN plugin. This enum value was introduced in Qt 5.14. |
QCanBusDevice::UserKey
|
30
|
This key defines the range where custom keys start. Its most common purpose is to permit platform-specific configuration options. |
另请参阅 configurationParameter ().
[since 5.12]
enum QCanBusDevice::
Direction
此枚举描述可能的数据传输方向。
| 常量 | 值 | 描述 |
|---|---|---|
QCanBusDevice::Input
|
1
|
输入方向。 |
QCanBusDevice::Output
|
2
|
输出方向。 |
QCanBusDevice::AllDirections
|
Input | Output
|
双向，输入和输出。 |
该枚举在 Qt 5.12 引入或被修改。
Directions 类型是 typedef 对于 QFlags <Direction>。它存储 Direction 值的 OR 组合。
构造串行总线设备采用指定 parent .
[signal]
void
QCanBusDevice::
errorOccurred
(
QCanBusDevice::CanBusError
)
此信号被发射，当出现错误时。
[signal]
void
QCanBusDevice::
framesReceived
()
This signal is emitted when one or more frames have been received. The frames should be read using readFrame () 和 framesAvailable ().
[signal]
void
QCanBusDevice::
framesWritten
(
qint64
framesCount
)
This signal is emitted every time a payload of frames has been written to the CAN bus. The framesCount argument is set to the number of frames that were written in this payload.
[signal]
void
QCanBusDevice::
stateChanged
(
QCanBusDevice::CanBusDeviceState
state
)
This signal is emitted every time the state of the device changes. The new state is represented by state .
[virtual, since 5.14]
QCanBusDevice::CanBusStatus
QCanBusDevice::
busStatus
()
Returns the current CAN bus status. If the status cannot be requested, QCanBusDevice::UnknownStatus is returned.
注意： This function may not be implemented in all CAN plugins. Please refer to the plugins help pages for more information. The function hasBusStatus () can be used at runtime to check if the used CAN plugin has support for requesting the CAN bus status.
该函数在 Qt 5.14 引入。
另请参阅 hasBusStatus () 和 resetController ().
[since 5.12]
void
QCanBusDevice::
clear
(
QCanBusDevice::Directions
direction
= Direction::AllDirections)
清零设备输入 (或输出) 缓冲，从属 direction .
This function only operates on QCanBusDevice buffers. Frames that are already written to the CAN driver or CAN hardware layer, or that are not yet read from these layers, are not cleared by this function.
注意： Clearing the output buffers is only possible for buffered devices.
该函数在 Qt 5.12 引入。
另请参阅 framesAvailable (), readFrame (), framesToWrite ()，和 writeFrame ().
[protected, since 5.14]
void
QCanBusDevice::
clearError
()
Clears the error id and the human readable description of the last device error.
CAN bus implementations must use this function to update the device's error state.
该函数在 Qt 5.14 引入。
另请参阅 error (), errorOccurred ()，和 setError ().
[pure virtual protected]
void
QCanBusDevice::
close
()
This function is responsible for closing the CAN bus connection. The implementation must ensure that the instance's state () 被设为 QCanBusDevice::UnconnectedState .
This function's most important task is to close the socket to the CAN device and to call QCanBusDevice::setState ().
另请参阅 disconnectDevice ().
Returns the list of keys used by the CAN bus connection.
The the meaning of the keys is equivalent to ConfigurationKey . If a key is not explicitly mentioned the platform's default setting for the relevant key is used.
Returns the current value assigned to the ConfigurationKey key ; otherwise an invalid QVariant .
另请参阅 setConfigurationParameter () 和 configurationKeys ().
将设备连接到 CAN (控制器局域网) 总线。返回
true
当成功时；否则
false
.
此函数调用 open () 作为其实现的一部分。
另请参阅 disconnectDevice ().
[protected]
QCanBusFrame
QCanBusDevice::
dequeueOutgoingFrame
()
返回下一 QCanBusFrame from the internal list of outgoing frames; otherwise returns an invalid QCanBusFrame . The returned frame is removed from the internal list.
[virtual, since 6.2]
QCanBusDeviceInfo
QCanBusDevice::
deviceInfo
() const
返回 QCanBusDeviceInfo for the current QCanBusDevice . If the function is not implemented by a sub-class of QCanBusDevice , a default constructed object is returned.
该函数在 Qt 6.2 引入。
从 CAN (控制器局域网) 总线断开设备连接。
此函数调用 close () 作为其实现的一部分。
注意：
This function should only be called, if
connectDevice
() 返回
true
.
另请参阅 connectDevice ().
[protected]
void
QCanBusDevice::
enqueueOutgoingFrame
(const
QCanBusFrame
&
newFrame
)
追加 newFrame to the internal list of outgoing frames which can be accessed by writeFrame ().
Subclasses must call this function when they write a new frame.
[protected]
void
QCanBusDevice::
enqueueReceivedFrames
(const
QList
<
QCanBusFrame
> &
newFrames
)
追加 newFrames to the internal list of frames which can be accessed using readFrame () and emits the framesReceived () 信号。
Subclasses must call this function when they receive frames.
Returns the last error that has occurred. The error value is always set to last error that occurred and it is never reset.
另请参阅 setError () 和 errorString ().
返回人类可读的最后发生的设备错误描述。
另请参阅 error ().
Returns the number of available frames. If no frames are available, this function returns 0.
另请参阅 clear (), readFrame ()，和 readAllFrames ().
For buffered devices, this function returns the number of frames waiting to be written. For unbuffered devices, this function always returns zero.
注意： There may be additional buffering in the CAN driver and CAN hardware layer. Therefore, if this function returns zero, that does not mean all CAN frames are already written to the CAN bus.
另请参阅 clear () 和 writeFrame ().
[virtual, since 5.14]
bool
QCanBusDevice::
hasBusStatus
() const
Return true, if the CAN plugin supports requesting the CAN bus status.
该函数在 Qt 5.14 引入。
另请参阅 busStatus ().
[protected]
bool
QCanBusDevice::
hasOutgoingFrames
() const
返回
true
if the internal list of outgoing frames is not empty; otherwise returns
false
.
[pure virtual]
QString
QCanBusDevice::
interpretErrorFrame
(const
QCanBusFrame
&
frame
)
Interprets frame as error frame and returns a human readable description of the error.
若 frame is not an error frame, the returned string is empty.
[pure virtual protected]
bool
QCanBusDevice::
open
()
此函数被调用通过
connectDevice
(). Subclasses must provide an implementation which returns
true
if the CAN bus connection could be established; otherwise
false
。
QCanBusDevice
implementation ensures upon entry of this function that the device's
state
() 被设为
QCanBusDevice::ConnectingState
already.
The implementation must ensure that upon success the instance's state () 被设为 QCanBusDevice::ConnectedState ；否则 QCanBusDevice::UnconnectedState . setState () must be used to set the new device state.
The custom implementation is responsible for opening the socket, instanciation of a potentially required QSocketNotifier and the application of custom and default QCanBusDevice::configurationParameter ().
另请参阅 connectDevice ().
[since 5.12]
QList
<
QCanBusFrame
> QCanBusDevice::
readAllFrames
()
Returns all QCanBusFrame s from the queue; otherwise returns an empty QList . The returned frames are removed from the queue.
The queue operates according to the FIFO principle.
该函数在 Qt 5.12 引入。
另请参阅 clear (), framesAvailable ()，和 readFrame ().
返回下一 QCanBusFrame from the queue; otherwise returns an empty QCanBusFrame . The returned frame is removed from the queue.
The queue operates according to the FIFO principle.
另请参阅 clear (), framesAvailable ()，和 readAllFrames ().
[virtual, since 5.14]
void
QCanBusDevice::
resetController
()
Performs a CAN controller reset to release the CAN controller from bus off state, if possible.
注意： CAN controller resets disturb the running communication and may take up to one second to complete. Only call this function to recover from bus errors.
注意： This function may not be implemented in all CAN plugins. Please refer to the plugins help pages for more information.
该函数在 Qt 5.14 引入。
另请参阅 busStatus ().
[虚拟]
void
QCanBusDevice::
setConfigurationParameter
(
QCanBusDevice::ConfigurationKey
key
, const
QVariant
&
value
)
Sets the configuration parameter key for the CAN bus connection to value . The potential keys are represented by ConfigurationKey .
A parameter can be unset by setting an invalid QVariant . Unsetting a parameter implies that the configuration is reset to its default setting.
注意： In most cases, configuration changes only take effect after a reconnect.
另请参阅 configurationParameter ().
[protected]
void
QCanBusDevice::
setError
(const
QString
&
errorText
,
QCanBusDevice::CanBusError
errorId
)
Sets the human readable description of the last device error to errorText . errorId categorizes the type of error.
CAN bus implementations must use this function to update the device's error state.
另请参阅 error (), errorOccurred ()，和 clearError ().
[protected]
void
QCanBusDevice::
setState
(
QCanBusDevice::CanBusDeviceState
newState
)
Sets the state of the device to newState . CAN bus implementations must use this function to update the device state.
另请参阅 state ().
返回设备的当前状态。
另请参阅 setState () 和 stateChanged ().
[虚拟]
bool
QCanBusDevice::
waitForFramesReceived
(
int
msecs
)
Blocks until new frames are available for reading and the
framesReceived
() 信号已发射，或直到
msecs
毫秒已过去。若
msecs
is
-1
，此函数不会超时。
返回
true
if new frames are available for reading and the
framesReceived
() signal is emitted; otherwise returns
false
(若操作超时或发生错误)。
注意： This function will start a local event loop. This may lead to scenarios whereby other application slots may be called while the execution of this function scope is blocking. To avoid problems, the signals for this class should not be connected to slots. Similarly this function must never be called in response to the framesReceived () 或 errorOccurred () 信号。
另请参阅 waitForFramesWritten ().
[虚拟]
bool
QCanBusDevice::
waitForFramesWritten
(
int
msecs
)
For buffered devices, this function waits until all buffered frames have been written to the device and the
framesWritten
() 信号已发射，或直到
msecs
毫秒已过去。若
msecs
is -1, this function will not time out. For unbuffered devices, it returns immediately with
false
as
writeFrame
() does not require a write buffer.
返回
true
若
framesWritten
() signal is emitted; otherwise returns
false
（即：若操作超时或发生错误)。
注意： This function will start a local event loop. This may lead to scenarios whereby other application slots may be called while the execution of this function scope is blocking. To avoid problems, the signals for this class should not be connected to slots. Similarly this function must never be called in response to the framesWritten () 或 errorOccurred () 信号。
另请参阅 waitForFramesReceived ().
[pure virtual]
bool
QCanBusDevice::
writeFrame
(const
QCanBusFrame
&
frame
)
写入
frame
到 CAN (控制器局域网) 总线并返回
true
当成功时；否则
false
.
On some platforms, the frame may be put into a queue and the return value may only indicate a successful insertion into the queue. The actual frame will be send later on. Therefore the framesWritten () signal is the final confirmation that the frame has been handed off to the transport layer. If an error occurs the errorOccurred () 被发射。
As per CAN bus specification, frames of type remote transfer request (RTR) do not have a payload, but a length from 0 to 8 (including). This length indicates the expected response payload length from the remote party. Therefore when sending a RTR frame using this function it may still be required to set an arbitrary payload on frame . The length of the arbitrary payload is what is set as size expectation for the RTR frame.
另请参阅 QCanBusFrame::setPayload ().