ChibiOS/HAL  6.1.0
hal_streams.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_streams.h
19  * @brief Data streams.
20  * @details This header defines abstract interfaces useful to access generic
21  * data streams in a standardized way.
22  *
23  * @addtogroup HAL_STREAMS
24  * @details This module define an abstract interface for generic data streams.
25  * Note that no code is present, just abstract interfaces-like
26  * structures, you should look at the system as to a set of
27  * abstract C++ classes (even if written in C). This system
28  * has then advantage to make the access to data streams
29  * independent from the implementation logic.<br>
30  * The stream interface can be used as base class for high level
31  * object types such as files, sockets, serial ports, pipes etc.
32  * @{
33  */
34 
35 #ifndef HAL_STREAMS_H
36 #define HAL_STREAMS_H
37 
38 /**
39  * @name Streams return codes
40  * @{
41  */
42 #define STM_OK MSG_OK
43 #define STM_TIMEOUT MSG_TIMEOUT
44 #define STM_RESET MSG_RESET
45 /** @} */
46 
47 /**
48  * @brief BaseSequentialStream specific methods.
49  */
50 #define _base_sequential_stream_methods \
51  _base_object_methods \
52  /* Stream write buffer method.*/ \
53  size_t (*write)(void *instance, const uint8_t *bp, size_t n); \
54  /* Stream read buffer method.*/ \
55  size_t (*read)(void *instance, uint8_t *bp, size_t n); \
56  /* Channel put method, blocking.*/ \
57  msg_t (*put)(void *instance, uint8_t b); \
58  /* Channel get method, blocking.*/ \
59  msg_t (*get)(void *instance); \
60 
61 /**
62  * @brief @p BaseSequentialStream specific data.
63  * @note It is empty because @p BaseSequentialStream is only an interface
64  * without implementation.
65  */
66 #define _base_sequential_stream_data \
67  _base_object_data
68 
69 /**
70  * @brief @p BaseSequentialStream virtual methods table.
71  */
74 };
75 
76 /**
77  * @extends BaseObject
78  *
79  * @brief Base stream class.
80  * @details This class represents a generic blocking unbuffered sequential
81  * data stream.
82  */
83 typedef struct {
84  /** @brief Virtual Methods Table.*/
88 
89 /**
90  * @name Macro Functions (BaseSequentialStream)
91  * @{
92  */
93 /**
94  * @brief Sequential Stream write.
95  * @details The function writes data from a buffer to a stream.
96  *
97  * @param[in] ip pointer to a @p BaseSequentialStream or derived class
98  * @param[in] bp pointer to the data buffer
99  * @param[in] n the maximum amount of data to be transferred
100  * @return The number of bytes transferred. The return value can
101  * be less than the specified number of bytes if an
102  * end-of-file condition has been met.
103  *
104  * @api
105  */
106 #define streamWrite(ip, bp, n) ((ip)->vmt->write(ip, bp, n))
107 
108 /**
109  * @brief Sequential Stream read.
110  * @details The function reads data from a stream into a buffer.
111  *
112  * @param[in] ip pointer to a @p BaseSequentialStream or derived class
113  * @param[out] bp pointer to the data buffer
114  * @param[in] n the maximum amount of data to be transferred
115  * @return The number of bytes transferred. The return value can
116  * be less than the specified number of bytes if an
117  * end-of-file condition has been met.
118  *
119  * @api
120  */
121 #define streamRead(ip, bp, n) ((ip)->vmt->read(ip, bp, n))
122 
123 /**
124  * @brief Sequential Stream blocking byte write.
125  * @details This function writes a byte value to a channel. If the channel
126  * is not ready to accept data then the calling thread is suspended.
127  *
128  * @param[in] ip pointer to a @p BaseChannel or derived class
129  * @param[in] b the byte value to be written to the channel
130  *
131  * @return The operation status.
132  * @retval STM_OK if the operation succeeded.
133  * @retval STM_RESET if an end-of-file condition has been met.
134  *
135  * @api
136  */
137 #define streamPut(ip, b) ((ip)->vmt->put(ip, b))
138 
139 /**
140  * @brief Sequential Stream blocking byte read.
141  * @details This function reads a byte value from a channel. If the data
142  * is not available then the calling thread is suspended.
143  *
144  * @param[in] ip pointer to a @p BaseChannel or derived class
145  *
146  * @return A byte value from the queue.
147  * @retval STM_RESET if an end-of-file condition has been met.
148  *
149  * @api
150  */
151 #define streamGet(ip) ((ip)->vmt->get(ip))
152 /** @} */
153 
154 #endif /* HAL_STREAMS_H */
155 
156 /** @} */
Base stream class.
Definition: hal_streams.h:83
const struct BaseSequentialStreamVMT * vmt
Virtual Methods Table.
Definition: hal_streams.h:85
#define _base_sequential_stream_methods
BaseSequentialStream specific methods.
Definition: hal_streams.h:50
#define _base_sequential_stream_data
BaseSequentialStream specific data.
Definition: hal_streams.h:66
BaseSequentialStream virtual methods table.
Definition: hal_streams.h:72