2 // basic_serial_port.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6 // Copyright (c) 2008 Rep Invariant Systems, Inc. (info@repinvariant.com)
8 // Distributed under the Boost Software License, Version 1.0. (See accompanying
9 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
12 #ifndef BOOST_ASIO_BASIC_SERIAL_PORT_HPP
13 #define BOOST_ASIO_BASIC_SERIAL_PORT_HPP
15 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
17 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
19 #include <boost/asio/detail/config.hpp>
21 #if defined(BOOST_ASIO_HAS_SERIAL_PORT) \
22 || defined(GENERATING_DOCUMENTATION)
25 #include <boost/asio/basic_io_object.hpp>
26 #include <boost/asio/detail/handler_type_requirements.hpp>
27 #include <boost/asio/detail/throw_error.hpp>
28 #include <boost/asio/error.hpp>
29 #include <boost/asio/serial_port_base.hpp>
30 #include <boost/asio/serial_port_service.hpp>
32 #include <boost/asio/detail/push_options.hpp>
37 /// Provides serial port functionality.
39 * The basic_serial_port class template provides functionality that is common
40 * to all serial ports.
43 * @e Distinct @e objects: Safe.@n
44 * @e Shared @e objects: Unsafe.
46 template <typename SerialPortService = serial_port_service>
47 class basic_serial_port
48 : public basic_io_object<SerialPortService>,
49 public serial_port_base
52 /// (Deprecated: Use native_handle_type.) The native representation of a
54 typedef typename SerialPortService::native_handle_type native_type;
56 /// The native representation of a serial port.
57 typedef typename SerialPortService::native_handle_type native_handle_type;
59 /// A basic_serial_port is always the lowest layer.
60 typedef basic_serial_port<SerialPortService> lowest_layer_type;
62 /// Construct a basic_serial_port without opening it.
64 * This constructor creates a serial port without opening it.
66 * @param io_service The io_service object that the serial port will use to
67 * dispatch handlers for any asynchronous operations performed on the port.
69 explicit basic_serial_port(boost::asio::io_service& io_service)
70 : basic_io_object<SerialPortService>(io_service)
74 /// Construct and open a basic_serial_port.
76 * This constructor creates and opens a serial port for the specified device
79 * @param io_service The io_service object that the serial port will use to
80 * dispatch handlers for any asynchronous operations performed on the port.
82 * @param device The platform-specific device name for this serial
85 explicit basic_serial_port(boost::asio::io_service& io_service,
87 : basic_io_object<SerialPortService>(io_service)
89 boost::system::error_code ec;
90 this->get_service().open(this->get_implementation(), device, ec);
91 boost::asio::detail::throw_error(ec, "open");
94 /// Construct and open a basic_serial_port.
96 * This constructor creates and opens a serial port for the specified device
99 * @param io_service The io_service object that the serial port will use to
100 * dispatch handlers for any asynchronous operations performed on the port.
102 * @param device The platform-specific device name for this serial
105 explicit basic_serial_port(boost::asio::io_service& io_service,
106 const std::string& device)
107 : basic_io_object<SerialPortService>(io_service)
109 boost::system::error_code ec;
110 this->get_service().open(this->get_implementation(), device, ec);
111 boost::asio::detail::throw_error(ec, "open");
114 /// Construct a basic_serial_port on an existing native serial port.
116 * This constructor creates a serial port object to hold an existing native
119 * @param io_service The io_service object that the serial port will use to
120 * dispatch handlers for any asynchronous operations performed on the port.
122 * @param native_serial_port A native serial port.
124 * @throws boost::system::system_error Thrown on failure.
126 basic_serial_port(boost::asio::io_service& io_service,
127 const native_handle_type& native_serial_port)
128 : basic_io_object<SerialPortService>(io_service)
130 boost::system::error_code ec;
131 this->get_service().assign(this->get_implementation(),
132 native_serial_port, ec);
133 boost::asio::detail::throw_error(ec, "assign");
136 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
137 /// Move-construct a basic_serial_port from another.
139 * This constructor moves a serial port from one object to another.
141 * @param other The other basic_serial_port object from which the move will
144 * @note Following the move, the moved-from object is in the same state as if
145 * constructed using the @c basic_serial_port(io_service&) constructor.
147 basic_serial_port(basic_serial_port&& other)
148 : basic_io_object<SerialPortService>(
149 BOOST_ASIO_MOVE_CAST(basic_serial_port)(other))
153 /// Move-assign a basic_serial_port from another.
155 * This assignment operator moves a serial port from one object to another.
157 * @param other The other basic_serial_port object from which the move will
160 * @note Following the move, the moved-from object is in the same state as if
161 * constructed using the @c basic_serial_port(io_service&) constructor.
163 basic_serial_port& operator=(basic_serial_port&& other)
165 basic_io_object<SerialPortService>::operator=(
166 BOOST_ASIO_MOVE_CAST(basic_serial_port)(other));
169 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
171 /// Get a reference to the lowest layer.
173 * This function returns a reference to the lowest layer in a stack of
174 * layers. Since a basic_serial_port cannot contain any further layers, it
175 * simply returns a reference to itself.
177 * @return A reference to the lowest layer in the stack of layers. Ownership
178 * is not transferred to the caller.
180 lowest_layer_type& lowest_layer()
185 /// Get a const reference to the lowest layer.
187 * This function returns a const reference to the lowest layer in a stack of
188 * layers. Since a basic_serial_port cannot contain any further layers, it
189 * simply returns a reference to itself.
191 * @return A const reference to the lowest layer in the stack of layers.
192 * Ownership is not transferred to the caller.
194 const lowest_layer_type& lowest_layer() const
199 /// Open the serial port using the specified device name.
201 * This function opens the serial port for the specified device name.
203 * @param device The platform-specific device name.
205 * @throws boost::system::system_error Thrown on failure.
207 void open(const std::string& device)
209 boost::system::error_code ec;
210 this->get_service().open(this->get_implementation(), device, ec);
211 boost::asio::detail::throw_error(ec, "open");
214 /// Open the serial port using the specified device name.
216 * This function opens the serial port using the given platform-specific
219 * @param device The platform-specific device name.
221 * @param ec Set the indicate what error occurred, if any.
223 boost::system::error_code open(const std::string& device,
224 boost::system::error_code& ec)
226 return this->get_service().open(this->get_implementation(), device, ec);
229 /// Assign an existing native serial port to the serial port.
231 * This function opens the serial port to hold an existing native serial port.
233 * @param native_serial_port A native serial port.
235 * @throws boost::system::system_error Thrown on failure.
237 void assign(const native_handle_type& native_serial_port)
239 boost::system::error_code ec;
240 this->get_service().assign(this->get_implementation(),
241 native_serial_port, ec);
242 boost::asio::detail::throw_error(ec, "assign");
245 /// Assign an existing native serial port to the serial port.
247 * This function opens the serial port to hold an existing native serial port.
249 * @param native_serial_port A native serial port.
251 * @param ec Set to indicate what error occurred, if any.
253 boost::system::error_code assign(const native_handle_type& native_serial_port,
254 boost::system::error_code& ec)
256 return this->get_service().assign(this->get_implementation(),
257 native_serial_port, ec);
260 /// Determine whether the serial port is open.
263 return this->get_service().is_open(this->get_implementation());
266 /// Close the serial port.
268 * This function is used to close the serial port. Any asynchronous read or
269 * write operations will be cancelled immediately, and will complete with the
270 * boost::asio::error::operation_aborted error.
272 * @throws boost::system::system_error Thrown on failure.
276 boost::system::error_code ec;
277 this->get_service().close(this->get_implementation(), ec);
278 boost::asio::detail::throw_error(ec, "close");
281 /// Close the serial port.
283 * This function is used to close the serial port. Any asynchronous read or
284 * write operations will be cancelled immediately, and will complete with the
285 * boost::asio::error::operation_aborted error.
287 * @param ec Set to indicate what error occurred, if any.
289 boost::system::error_code close(boost::system::error_code& ec)
291 return this->get_service().close(this->get_implementation(), ec);
294 /// (Deprecated: Use native_handle().) Get the native serial port
297 * This function may be used to obtain the underlying representation of the
298 * serial port. This is intended to allow access to native serial port
299 * functionality that is not otherwise provided.
303 return this->get_service().native_handle(this->get_implementation());
306 /// Get the native serial port representation.
308 * This function may be used to obtain the underlying representation of the
309 * serial port. This is intended to allow access to native serial port
310 * functionality that is not otherwise provided.
312 native_handle_type native_handle()
314 return this->get_service().native_handle(this->get_implementation());
317 /// Cancel all asynchronous operations associated with the serial port.
319 * This function causes all outstanding asynchronous read or write operations
320 * to finish immediately, and the handlers for cancelled operations will be
321 * passed the boost::asio::error::operation_aborted error.
323 * @throws boost::system::system_error Thrown on failure.
327 boost::system::error_code ec;
328 this->get_service().cancel(this->get_implementation(), ec);
329 boost::asio::detail::throw_error(ec, "cancel");
332 /// Cancel all asynchronous operations associated with the serial port.
334 * This function causes all outstanding asynchronous read or write operations
335 * to finish immediately, and the handlers for cancelled operations will be
336 * passed the boost::asio::error::operation_aborted error.
338 * @param ec Set to indicate what error occurred, if any.
340 boost::system::error_code cancel(boost::system::error_code& ec)
342 return this->get_service().cancel(this->get_implementation(), ec);
345 /// Send a break sequence to the serial port.
347 * This function causes a break sequence of platform-specific duration to be
348 * sent out the serial port.
350 * @throws boost::system::system_error Thrown on failure.
354 boost::system::error_code ec;
355 this->get_service().send_break(this->get_implementation(), ec);
356 boost::asio::detail::throw_error(ec, "send_break");
359 /// Send a break sequence to the serial port.
361 * This function causes a break sequence of platform-specific duration to be
362 * sent out the serial port.
364 * @param ec Set to indicate what error occurred, if any.
366 boost::system::error_code send_break(boost::system::error_code& ec)
368 return this->get_service().send_break(this->get_implementation(), ec);
371 /// Set an option on the serial port.
373 * This function is used to set an option on the serial port.
375 * @param option The option value to be set on the serial port.
377 * @throws boost::system::system_error Thrown on failure.
379 * @sa SettableSerialPortOption @n
380 * boost::asio::serial_port_base::baud_rate @n
381 * boost::asio::serial_port_base::flow_control @n
382 * boost::asio::serial_port_base::parity @n
383 * boost::asio::serial_port_base::stop_bits @n
384 * boost::asio::serial_port_base::character_size
386 template <typename SettableSerialPortOption>
387 void set_option(const SettableSerialPortOption& option)
389 boost::system::error_code ec;
390 this->get_service().set_option(this->get_implementation(), option, ec);
391 boost::asio::detail::throw_error(ec, "set_option");
394 /// Set an option on the serial port.
396 * This function is used to set an option on the serial port.
398 * @param option The option value to be set on the serial port.
400 * @param ec Set to indicate what error occurred, if any.
402 * @sa SettableSerialPortOption @n
403 * boost::asio::serial_port_base::baud_rate @n
404 * boost::asio::serial_port_base::flow_control @n
405 * boost::asio::serial_port_base::parity @n
406 * boost::asio::serial_port_base::stop_bits @n
407 * boost::asio::serial_port_base::character_size
409 template <typename SettableSerialPortOption>
410 boost::system::error_code set_option(const SettableSerialPortOption& option,
411 boost::system::error_code& ec)
413 return this->get_service().set_option(
414 this->get_implementation(), option, ec);
417 /// Get an option from the serial port.
419 * This function is used to get the current value of an option on the serial
422 * @param option The option value to be obtained from the serial port.
424 * @throws boost::system::system_error Thrown on failure.
426 * @sa GettableSerialPortOption @n
427 * boost::asio::serial_port_base::baud_rate @n
428 * boost::asio::serial_port_base::flow_control @n
429 * boost::asio::serial_port_base::parity @n
430 * boost::asio::serial_port_base::stop_bits @n
431 * boost::asio::serial_port_base::character_size
433 template <typename GettableSerialPortOption>
434 void get_option(GettableSerialPortOption& option)
436 boost::system::error_code ec;
437 this->get_service().get_option(this->get_implementation(), option, ec);
438 boost::asio::detail::throw_error(ec, "get_option");
441 /// Get an option from the serial port.
443 * This function is used to get the current value of an option on the serial
446 * @param option The option value to be obtained from the serial port.
448 * @param ec Set to indicate what error occurred, if any.
450 * @sa GettableSerialPortOption @n
451 * boost::asio::serial_port_base::baud_rate @n
452 * boost::asio::serial_port_base::flow_control @n
453 * boost::asio::serial_port_base::parity @n
454 * boost::asio::serial_port_base::stop_bits @n
455 * boost::asio::serial_port_base::character_size
457 template <typename GettableSerialPortOption>
458 boost::system::error_code get_option(GettableSerialPortOption& option,
459 boost::system::error_code& ec)
461 return this->get_service().get_option(
462 this->get_implementation(), option, ec);
465 /// Write some data to the serial port.
467 * This function is used to write data to the serial port. The function call
468 * will block until one or more bytes of the data has been written
469 * successfully, or until an error occurs.
471 * @param buffers One or more data buffers to be written to the serial port.
473 * @returns The number of bytes written.
475 * @throws boost::system::system_error Thrown on failure. An error code of
476 * boost::asio::error::eof indicates that the connection was closed by the
479 * @note The write_some operation may not transmit all of the data to the
480 * peer. Consider using the @ref write function if you need to ensure that
481 * all data is written before the blocking operation completes.
484 * To write a single data buffer use the @ref buffer function as follows:
486 * serial_port.write_some(boost::asio::buffer(data, size));
488 * See the @ref buffer documentation for information on writing multiple
489 * buffers in one go, and how to use it with arrays, boost::array or
492 template <typename ConstBufferSequence>
493 std::size_t write_some(const ConstBufferSequence& buffers)
495 boost::system::error_code ec;
496 std::size_t s = this->get_service().write_some(
497 this->get_implementation(), buffers, ec);
498 boost::asio::detail::throw_error(ec, "write_some");
502 /// Write some data to the serial port.
504 * This function is used to write data to the serial port. The function call
505 * will block until one or more bytes of the data has been written
506 * successfully, or until an error occurs.
508 * @param buffers One or more data buffers to be written to the serial port.
510 * @param ec Set to indicate what error occurred, if any.
512 * @returns The number of bytes written. Returns 0 if an error occurred.
514 * @note The write_some operation may not transmit all of the data to the
515 * peer. Consider using the @ref write function if you need to ensure that
516 * all data is written before the blocking operation completes.
518 template <typename ConstBufferSequence>
519 std::size_t write_some(const ConstBufferSequence& buffers,
520 boost::system::error_code& ec)
522 return this->get_service().write_some(
523 this->get_implementation(), buffers, ec);
526 /// Start an asynchronous write.
528 * This function is used to asynchronously write data to the serial port.
529 * The function call always returns immediately.
531 * @param buffers One or more data buffers to be written to the serial port.
532 * Although the buffers object may be copied as necessary, ownership of the
533 * underlying memory blocks is retained by the caller, which must guarantee
534 * that they remain valid until the handler is called.
536 * @param handler The handler to be called when the write operation completes.
537 * Copies will be made of the handler as required. The function signature of
538 * the handler must be:
539 * @code void handler(
540 * const boost::system::error_code& error, // Result of operation.
541 * std::size_t bytes_transferred // Number of bytes written.
543 * Regardless of whether the asynchronous operation completes immediately or
544 * not, the handler will not be invoked from within this function. Invocation
545 * of the handler will be performed in a manner equivalent to using
546 * boost::asio::io_service::post().
548 * @note The write operation may not transmit all of the data to the peer.
549 * Consider using the @ref async_write function if you need to ensure that all
550 * data is written before the asynchronous operation completes.
553 * To write a single data buffer use the @ref buffer function as follows:
555 * serial_port.async_write_some(boost::asio::buffer(data, size), handler);
557 * See the @ref buffer documentation for information on writing multiple
558 * buffers in one go, and how to use it with arrays, boost::array or
561 template <typename ConstBufferSequence, typename WriteHandler>
562 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
563 void (boost::system::error_code, std::size_t))
564 async_write_some(const ConstBufferSequence& buffers,
565 BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
567 // If you get an error on the following line it means that your handler does
568 // not meet the documented type requirements for a WriteHandler.
569 BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
571 return this->get_service().async_write_some(this->get_implementation(),
572 buffers, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
575 /// Read some data from the serial port.
577 * This function is used to read data from the serial port. The function
578 * call will block until one or more bytes of data has been read successfully,
579 * or until an error occurs.
581 * @param buffers One or more buffers into which the data will be read.
583 * @returns The number of bytes read.
585 * @throws boost::system::system_error Thrown on failure. An error code of
586 * boost::asio::error::eof indicates that the connection was closed by the
589 * @note The read_some operation may not read all of the requested number of
590 * bytes. Consider using the @ref read function if you need to ensure that
591 * the requested amount of data is read before the blocking operation
595 * To read into a single data buffer use the @ref buffer function as follows:
597 * serial_port.read_some(boost::asio::buffer(data, size));
599 * See the @ref buffer documentation for information on reading into multiple
600 * buffers in one go, and how to use it with arrays, boost::array or
603 template <typename MutableBufferSequence>
604 std::size_t read_some(const MutableBufferSequence& buffers)
606 boost::system::error_code ec;
607 std::size_t s = this->get_service().read_some(
608 this->get_implementation(), buffers, ec);
609 boost::asio::detail::throw_error(ec, "read_some");
613 /// Read some data from the serial port.
615 * This function is used to read data from the serial port. The function
616 * call will block until one or more bytes of data has been read successfully,
617 * or until an error occurs.
619 * @param buffers One or more buffers into which the data will be read.
621 * @param ec Set to indicate what error occurred, if any.
623 * @returns The number of bytes read. Returns 0 if an error occurred.
625 * @note The read_some operation may not read all of the requested number of
626 * bytes. Consider using the @ref read function if you need to ensure that
627 * the requested amount of data is read before the blocking operation
630 template <typename MutableBufferSequence>
631 std::size_t read_some(const MutableBufferSequence& buffers,
632 boost::system::error_code& ec)
634 return this->get_service().read_some(
635 this->get_implementation(), buffers, ec);
638 /// Start an asynchronous read.
640 * This function is used to asynchronously read data from the serial port.
641 * The function call always returns immediately.
643 * @param buffers One or more buffers into which the data will be read.
644 * Although the buffers object may be copied as necessary, ownership of the
645 * underlying memory blocks is retained by the caller, which must guarantee
646 * that they remain valid until the handler is called.
648 * @param handler The handler to be called when the read operation completes.
649 * Copies will be made of the handler as required. The function signature of
650 * the handler must be:
651 * @code void handler(
652 * const boost::system::error_code& error, // Result of operation.
653 * std::size_t bytes_transferred // Number of bytes read.
655 * Regardless of whether the asynchronous operation completes immediately or
656 * not, the handler will not be invoked from within this function. Invocation
657 * of the handler will be performed in a manner equivalent to using
658 * boost::asio::io_service::post().
660 * @note The read operation may not read all of the requested number of bytes.
661 * Consider using the @ref async_read function if you need to ensure that the
662 * requested amount of data is read before the asynchronous operation
666 * To read into a single data buffer use the @ref buffer function as follows:
668 * serial_port.async_read_some(boost::asio::buffer(data, size), handler);
670 * See the @ref buffer documentation for information on reading into multiple
671 * buffers in one go, and how to use it with arrays, boost::array or
674 template <typename MutableBufferSequence, typename ReadHandler>
675 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
676 void (boost::system::error_code, std::size_t))
677 async_read_some(const MutableBufferSequence& buffers,
678 BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
680 // If you get an error on the following line it means that your handler does
681 // not meet the documented type requirements for a ReadHandler.
682 BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
684 return this->get_service().async_read_some(this->get_implementation(),
685 buffers, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
692 #include <boost/asio/detail/pop_options.hpp>
694 #endif // defined(BOOST_ASIO_HAS_SERIAL_PORT)
695 // || defined(GENERATING_DOCUMENTATION)
697 #endif // BOOST_ASIO_BASIC_SERIAL_PORT_HPP