1	//
2	// basic_socket.hpp
3	// ~~~~~~~~~~~~~~~~
4	//
5	// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6	//
7	// Distributed under the Boost Software License, Version 1.0. (See accompanying
8	// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9	//
10
11	#ifndef BOOST_ASIO_BASIC_SOCKET_HPP
12	#define BOOST_ASIO_BASIC_SOCKET_HPP
13
14	#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15	# pragma once
16	#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
18	#include <utility>
19	#include <boost/asio/any_io_executor.hpp>
20	#include <boost/asio/detail/config.hpp>
21	#include <boost/asio/async_result.hpp>
22	#include <boost/asio/detail/handler_type_requirements.hpp>
23	#include <boost/asio/detail/io_object_impl.hpp>
24	#include <boost/asio/detail/non_const_lvalue.hpp>
25	#include <boost/asio/detail/throw_error.hpp>
26	#include <boost/asio/detail/type_traits.hpp>
27	#include <boost/asio/error.hpp>
28	#include <boost/asio/execution_context.hpp>
29	#include <boost/asio/post.hpp>
30	#include <boost/asio/socket_base.hpp>
31
32	#if defined(BOOST_ASIO_WINDOWS_RUNTIME)
33	# include <boost/asio/detail/null_socket_service.hpp>
34	#elif defined(BOOST_ASIO_HAS_IOCP)
35	# include <boost/asio/detail/win_iocp_socket_service.hpp>
36	#elif defined(BOOST_ASIO_HAS_IO_URING_AS_DEFAULT)
37	# include <boost/asio/detail/io_uring_socket_service.hpp>
38	#else
39	# include <boost/asio/detail/reactive_socket_service.hpp>
40	#endif
41
42	#include <boost/asio/detail/push_options.hpp>
43
44	namespace boost {
45	namespace asio {
46
47	#if !defined(BOOST_ASIO_BASIC_SOCKET_FWD_DECL)
48	#define BOOST_ASIO_BASIC_SOCKET_FWD_DECL
49
50	// Forward declaration with defaulted arguments.
51	template <typename Protocol, typename Executor = any_io_executor>
52	class basic_socket;
53
54	#endif // !defined(BOOST_ASIO_BASIC_SOCKET_FWD_DECL)
55
56	/// Provides socket functionality.
57	/**
58	* The basic_socket class template provides functionality that is common to both
59	* stream-oriented and datagram-oriented sockets.
60	*
61	* @par Thread Safety
62	* @e Distinct @e objects: Safe.@n
63	* @e Shared @e objects: Unsafe.
64	*/
65	template <typename Protocol, typename Executor>
66	class basic_socket
67	: public socket_base
68	{
69	private:
70	class initiate_async_connect;
71	class initiate_async_wait;
72
73	public:
74	/// The type of the executor associated with the object.
75	typedef Executor executor_type;
76
77	/// Rebinds the socket type to another executor.
78	template <typename Executor1>
79	struct rebind_executor
80	{
81	/// The socket type when rebound to the specified executor.
82	typedef basic_socket<Protocol, Executor1> other;
83	};
84
85	/// The native representation of a socket.
86	#if defined(GENERATING_DOCUMENTATION)
87	typedef implementation_defined native_handle_type;
88	#elif defined(BOOST_ASIO_WINDOWS_RUNTIME)
89	typedef typename detail::null_socket_service<
90	Protocol>::native_handle_type native_handle_type;
91	#elif defined(BOOST_ASIO_HAS_IOCP)
92	typedef typename detail::win_iocp_socket_service<
93	Protocol>::native_handle_type native_handle_type;
94	#elif defined(BOOST_ASIO_HAS_IO_URING_AS_DEFAULT)
95	typedef typename detail::io_uring_socket_service<
96	Protocol>::native_handle_type native_handle_type;
97	#else
98	typedef typename detail::reactive_socket_service<
99	Protocol>::native_handle_type native_handle_type;
100	#endif
101
102	/// The protocol type.
103	typedef Protocol protocol_type;
104
105	/// The endpoint type.
106	typedef typename Protocol::endpoint endpoint_type;
107
108	#if !defined(BOOST_ASIO_NO_EXTENSIONS)
109	/// A basic_socket is always the lowest layer.
110	typedef basic_socket<Protocol, Executor> lowest_layer_type;
111	#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
112
113	/// Construct a basic_socket without opening it.
114	/**
115	* This constructor creates a socket without opening it.
116	*
117	* @param ex The I/O executor that the socket will use, by default, to
118	* dispatch handlers for any asynchronous operations performed on the socket.
119	*/
120	explicit basic_socket(const executor_type& ex)
121	: impl_(0, ex)
122	{
123	}
124
125	/// Construct a basic_socket without opening it.
126	/**
127	* This constructor creates a socket without opening it.
128	*
129	* @param context An execution context which provides the I/O executor that
130	* the socket will use, by default, to dispatch handlers for any asynchronous
131	* operations performed on the socket.
132	*/
133	template <typename ExecutionContext>
134	explicit basic_socket(ExecutionContext& context,
135	constraint_t<
136	is_convertible<ExecutionContext&, execution_context&>::value
137	> = 0)
138	: impl_(0, 0, context)
139	{
140	}
141
142	/// Construct and open a basic_socket.
143	/**
144	* This constructor creates and opens a socket.
145	*
146	* @param ex The I/O executor that the socket will use, by default, to
147	* dispatch handlers for any asynchronous operations performed on the socket.
148	*
149	* @param protocol An object specifying protocol parameters to be used.
150	*
151	* @throws boost::system::system_error Thrown on failure.
152	*/
153	basic_socket(const executor_type& ex, const protocol_type& protocol)
154	: impl_(0, ex)
155	{
156	boost::system::error_code ec;
157	impl_.get_service().open(impl_.get_implementation(), protocol, ec);
158	boost::asio::detail::throw_error(err: ec, location: "open");
159	}
160
161	/// Construct and open a basic_socket.
162	/**
163	* This constructor creates and opens a socket.
164	*
165	* @param context An execution context which provides the I/O executor that
166	* the socket will use, by default, to dispatch handlers for any asynchronous
167	* operations performed on the socket.
168	*
169	* @param protocol An object specifying protocol parameters to be used.
170	*
171	* @throws boost::system::system_error Thrown on failure.
172	*/
173	template <typename ExecutionContext>
174	basic_socket(ExecutionContext& context, const protocol_type& protocol,
175	constraint_t<
176	is_convertible<ExecutionContext&, execution_context&>::value,
177	defaulted_constraint
178	> = defaulted_constraint())
179	: impl_(0, 0, context)
180	{
181	boost::system::error_code ec;
182	impl_.get_service().open(impl_.get_implementation(), protocol, ec);
183	boost::asio::detail::throw_error(err: ec, location: "open");
184	}
185
186	/// Construct a basic_socket, opening it and binding it to the given local
187	/// endpoint.
188	/**
189	* This constructor creates a socket and automatically opens it bound to the
190	* specified endpoint on the local machine. The protocol used is the protocol
191	* associated with the given endpoint.
192	*
193	* @param ex The I/O executor that the socket will use, by default, to
194	* dispatch handlers for any asynchronous operations performed on the socket.
195	*
196	* @param endpoint An endpoint on the local machine to which the socket will
197	* be bound.
198	*
199	* @throws boost::system::system_error Thrown on failure.
200	*/
201	basic_socket(const executor_type& ex, const endpoint_type& endpoint)
202	: impl_(0, ex)
203	{
204	boost::system::error_code ec;
205	const protocol_type protocol = endpoint.protocol();
206	impl_.get_service().open(impl_.get_implementation(), protocol, ec);
207	boost::asio::detail::throw_error(err: ec, location: "open");
208	impl_.get_service().bind(impl_.get_implementation(), endpoint, ec);
209	boost::asio::detail::throw_error(err: ec, location: "bind");
210	}
211
212	/// Construct a basic_socket, opening it and binding it to the given local
213	/// endpoint.
214	/**
215	* This constructor creates a socket and automatically opens it bound to the
216	* specified endpoint on the local machine. The protocol used is the protocol
217	* associated with the given endpoint.
218	*
219	* @param context An execution context which provides the I/O executor that
220	* the socket will use, by default, to dispatch handlers for any asynchronous
221	* operations performed on the socket.
222	*
223	* @param endpoint An endpoint on the local machine to which the socket will
224	* be bound.
225	*
226	* @throws boost::system::system_error Thrown on failure.
227	*/
228	template <typename ExecutionContext>
229	basic_socket(ExecutionContext& context, const endpoint_type& endpoint,
230	constraint_t<
231	is_convertible<ExecutionContext&, execution_context&>::value
232	> = 0)
233	: impl_(0, 0, context)
234	{
235	boost::system::error_code ec;
236	const protocol_type protocol = endpoint.protocol();
237	impl_.get_service().open(impl_.get_implementation(), protocol, ec);
238	boost::asio::detail::throw_error(err: ec, location: "open");
239	impl_.get_service().bind(impl_.get_implementation(), endpoint, ec);
240	boost::asio::detail::throw_error(err: ec, location: "bind");
241	}
242
243	/// Construct a basic_socket on an existing native socket.
244	/**
245	* This constructor creates a socket object to hold an existing native socket.
246	*
247	* @param ex The I/O executor that the socket will use, by default, to
248	* dispatch handlers for any asynchronous operations performed on the socket.
249	*
250	* @param protocol An object specifying protocol parameters to be used.
251	*
252	* @param native_socket A native socket.
253	*
254	* @throws boost::system::system_error Thrown on failure.
255	*/
256	basic_socket(const executor_type& ex, const protocol_type& protocol,
257	const native_handle_type& native_socket)
258	: impl_(0, ex)
259	{
260	boost::system::error_code ec;
261	impl_.get_service().assign(impl_.get_implementation(),
262	protocol, native_socket, ec);
263	boost::asio::detail::throw_error(err: ec, location: "assign");
264	}
265
266	/// Construct a basic_socket on an existing native socket.
267	/**
268	* This constructor creates a socket object to hold an existing native socket.
269	*
270	* @param context An execution context which provides the I/O executor that
271	* the socket will use, by default, to dispatch handlers for any asynchronous
272	* operations performed on the socket.
273	*
274	* @param protocol An object specifying protocol parameters to be used.
275	*
276	* @param native_socket A native socket.
277	*
278	* @throws boost::system::system_error Thrown on failure.
279	*/
280	template <typename ExecutionContext>
281	basic_socket(ExecutionContext& context, const protocol_type& protocol,
282	const native_handle_type& native_socket,
283	constraint_t<
284	is_convertible<ExecutionContext&, execution_context&>::value
285	> = 0)
286	: impl_(0, 0, context)
287	{
288	boost::system::error_code ec;
289	impl_.get_service().assign(impl_.get_implementation(),
290	protocol, native_socket, ec);
291	boost::asio::detail::throw_error(err: ec, location: "assign");
292	}
293
294	/// Move-construct a basic_socket from another.
295	/**
296	* This constructor moves a socket from one object to another.
297	*
298	* @param other The other basic_socket object from which the move will
299	* occur.
300	*
301	* @note Following the move, the moved-from object is in the same state as if
302	* constructed using the @c basic_socket(const executor_type&) constructor.
303	*/
304	basic_socket(basic_socket&& other) noexcept
305	: impl_(std::move(other.impl_))
306	{
307	}
308
309	/// Move-assign a basic_socket from another.
310	/**
311	* This assignment operator moves a socket from one object to another.
312	*
313	* @param other The other basic_socket object from which the move will
314	* occur.
315	*
316	* @note Following the move, the moved-from object is in the same state as if
317	* constructed using the @c basic_socket(const executor_type&) constructor.
318	*/
319	basic_socket& operator=(basic_socket&& other)
320	{
321	impl_ = std::move(other.impl_);
322	return *this;
323	}
324
325	// All sockets have access to each other's implementations.
326	template <typename Protocol1, typename Executor1>
327	friend class basic_socket;
328
329	/// Move-construct a basic_socket from a socket of another protocol type.
330	/**
331	* This constructor moves a socket from one object to another.
332	*
333	* @param other The other basic_socket object from which the move will
334	* occur.
335	*
336	* @note Following the move, the moved-from object is in the same state as if
337	* constructed using the @c basic_socket(const executor_type&) constructor.
338	*/
339	template <typename Protocol1, typename Executor1>
340	basic_socket(basic_socket<Protocol1, Executor1>&& other,
341	constraint_t<
342	is_convertible<Protocol1, Protocol>::value
343	&& is_convertible<Executor1, Executor>::value
344	> = 0)
345	: impl_(std::move(other.impl_))
346	{
347	}
348
349	/// Move-assign a basic_socket from a socket of another protocol type.
350	/**
351	* This assignment operator moves a socket from one object to another.
352	*
353	* @param other The other basic_socket object from which the move will
354	* occur.
355	*
356	* @note Following the move, the moved-from object is in the same state as if
357	* constructed using the @c basic_socket(const executor_type&) constructor.
358	*/
359	template <typename Protocol1, typename Executor1>
360	constraint_t<
361	is_convertible<Protocol1, Protocol>::value
362	&& is_convertible<Executor1, Executor>::value,
363	basic_socket&
364	> operator=(basic_socket<Protocol1, Executor1>&& other)
365	{
366	basic_socket tmp(std::move(other));
367	impl_ = std::move(tmp.impl_);
368	return *this;
369	}
370
371	/// Get the executor associated with the object.
372	const executor_type& get_executor() noexcept
373	{
374	return impl_.get_executor();
375	}
376
377	#if !defined(BOOST_ASIO_NO_EXTENSIONS)
378	/// Get a reference to the lowest layer.
379	/**
380	* This function returns a reference to the lowest layer in a stack of
381	* layers. Since a basic_socket cannot contain any further layers, it simply
382	* returns a reference to itself.
383	*
384	* @return A reference to the lowest layer in the stack of layers. Ownership
385	* is not transferred to the caller.
386	*/
387	lowest_layer_type& lowest_layer()
388	{
389	return *this;
390	}
391
392	/// Get a const reference to the lowest layer.
393	/**
394	* This function returns a const reference to the lowest layer in a stack of
395	* layers. Since a basic_socket cannot contain any further layers, it simply
396	* returns a reference to itself.
397	*
398	* @return A const reference to the lowest layer in the stack of layers.
399	* Ownership is not transferred to the caller.
400	*/
401	const lowest_layer_type& lowest_layer() const
402	{
403	return *this;
404	}
405	#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
406
407	/// Open the socket using the specified protocol.
408	/**
409	* This function opens the socket so that it will use the specified protocol.
410	*
411	* @param protocol An object specifying protocol parameters to be used.
412	*
413	* @throws boost::system::system_error Thrown on failure.
414	*
415	* @par Example
416	* @code
417	* boost::asio::ip::tcp::socket socket(my_context);
418	* socket.open(boost::asio::ip::tcp::v4());
419	* @endcode
420	*/
421	void open(const protocol_type& protocol = protocol_type())
422	{
423	boost::system::error_code ec;
424	impl_.get_service().open(impl_.get_implementation(), protocol, ec);
425	boost::asio::detail::throw_error(err: ec, location: "open");
426	}
427
428	/// Open the socket using the specified protocol.
429	/**
430	* This function opens the socket so that it will use the specified protocol.
431	*
432	* @param protocol An object specifying which protocol is to be used.
433	*
434	* @param ec Set to indicate what error occurred, if any.
435	*
436	* @par Example
437	* @code
438	* boost::asio::ip::tcp::socket socket(my_context);
439	* boost::system::error_code ec;
440	* socket.open(boost::asio::ip::tcp::v4(), ec);
441	* if (ec)
442	* {
443	* // An error occurred.
444	* }
445	* @endcode
446	*/
447	BOOST_ASIO_SYNC_OP_VOID open(const protocol_type& protocol,
448	boost::system::error_code& ec)
449	{
450	impl_.get_service().open(impl_.get_implementation(), protocol, ec);
451	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
452	}
453
454	/// Assign an existing native socket to the socket.
455	/*
456	* This function opens the socket to hold an existing native socket.
457	*
458	* @param protocol An object specifying which protocol is to be used.
459	*
460	* @param native_socket A native socket.
461	*
462	* @throws boost::system::system_error Thrown on failure.
463	*/
464	void assign(const protocol_type& protocol,
465	const native_handle_type& native_socket)
466	{
467	boost::system::error_code ec;
468	impl_.get_service().assign(impl_.get_implementation(),
469	protocol, native_socket, ec);
470	boost::asio::detail::throw_error(err: ec, location: "assign");
471	}
472
473	/// Assign an existing native socket to the socket.
474	/*
475	* This function opens the socket to hold an existing native socket.
476	*
477	* @param protocol An object specifying which protocol is to be used.
478	*
479	* @param native_socket A native socket.
480	*
481	* @param ec Set to indicate what error occurred, if any.
482	*/
483	BOOST_ASIO_SYNC_OP_VOID assign(const protocol_type& protocol,
484	const native_handle_type& native_socket, boost::system::error_code& ec)
485	{
486	impl_.get_service().assign(impl_.get_implementation(),
487	protocol, native_socket, ec);
488	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
489	}
490
491	/// Determine whether the socket is open.
492	bool is_open() const
493	{
494	return impl_.get_service().is_open(impl_.get_implementation());
495	}
496
497	/// Close the socket.
498	/**
499	* This function is used to close the socket. Any asynchronous send, receive
500	* or connect operations will be cancelled immediately, and will complete
501	* with the boost::asio::error::operation_aborted error.
502	*
503	* @throws boost::system::system_error Thrown on failure. Note that, even if
504	* the function indicates an error, the underlying descriptor is closed.
505	*
506	* @note For portable behaviour with respect to graceful closure of a
507	* connected socket, call shutdown() before closing the socket.
508	*/
509	void close()
510	{
511	boost::system::error_code ec;
512	impl_.get_service().close(impl_.get_implementation(), ec);
513	boost::asio::detail::throw_error(err: ec, location: "close");
514	}
515
516	/// Close the socket.
517	/**
518	* This function is used to close the socket. Any asynchronous send, receive
519	* or connect operations will be cancelled immediately, and will complete
520	* with the boost::asio::error::operation_aborted error.
521	*
522	* @param ec Set to indicate what error occurred, if any. Note that, even if
523	* the function indicates an error, the underlying descriptor is closed.
524	*
525	* @par Example
526	* @code
527	* boost::asio::ip::tcp::socket socket(my_context);
528	* ...
529	* boost::system::error_code ec;
530	* socket.close(ec);
531	* if (ec)
532	* {
533	* // An error occurred.
534	* }
535	* @endcode
536	*
537	* @note For portable behaviour with respect to graceful closure of a
538	* connected socket, call shutdown() before closing the socket.
539	*/
540	BOOST_ASIO_SYNC_OP_VOID close(boost::system::error_code& ec)
541	{
542	impl_.get_service().close(impl_.get_implementation(), ec);
543	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
544	}
545
546	/// Release ownership of the underlying native socket.
547	/**
548	* This function causes all outstanding asynchronous connect, send and receive
549	* operations to finish immediately, and the handlers for cancelled operations
550	* will be passed the boost::asio::error::operation_aborted error. Ownership
551	* of the native socket is then transferred to the caller.
552	*
553	* @throws boost::system::system_error Thrown on failure.
554	*
555	* @note This function is unsupported on Windows versions prior to Windows
556	* 8.1, and will fail with boost::asio::error::operation_not_supported on
557	* these platforms.
558	*/
559	#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
560	&& (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0603)
561	__declspec(deprecated("This function always fails with "
562	"operation_not_supported when used on Windows versions "
563	"prior to Windows 8.1."))
564	#endif
565	native_handle_type release()
566	{
567	boost::system::error_code ec;
568	native_handle_type s = impl_.get_service().release(
569	impl_.get_implementation(), ec);
570	boost::asio::detail::throw_error(err: ec, location: "release");
571	return s;
572	}
573
574	/// Release ownership of the underlying native socket.
575	/**
576	* This function causes all outstanding asynchronous connect, send and receive
577	* operations to finish immediately, and the handlers for cancelled operations
578	* will be passed the boost::asio::error::operation_aborted error. Ownership
579	* of the native socket is then transferred to the caller.
580	*
581	* @param ec Set to indicate what error occurred, if any.
582	*
583	* @note This function is unsupported on Windows versions prior to Windows
584	* 8.1, and will fail with boost::asio::error::operation_not_supported on
585	* these platforms.
586	*/
587	#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
588	&& (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0603)
589	__declspec(deprecated("This function always fails with "
590	"operation_not_supported when used on Windows versions "
591	"prior to Windows 8.1."))
592	#endif
593	native_handle_type release(boost::system::error_code& ec)
594	{
595	return impl_.get_service().release(impl_.get_implementation(), ec);
596	}
597
598	/// Get the native socket representation.
599	/**
600	* This function may be used to obtain the underlying representation of the
601	* socket. This is intended to allow access to native socket functionality
602	* that is not otherwise provided.
603	*/
604	native_handle_type native_handle()
605	{
606	return impl_.get_service().native_handle(impl_.get_implementation());
607	}
608
609	/// Cancel all asynchronous operations associated with the socket.
610	/**
611	* This function causes all outstanding asynchronous connect, send and receive
612	* operations to finish immediately, and the handlers for cancelled operations
613	* will be passed the boost::asio::error::operation_aborted error.
614	*
615	* @throws boost::system::system_error Thrown on failure.
616	*
617	* @note Calls to cancel() will always fail with
618	* boost::asio::error::operation_not_supported when run on Windows XP, Windows
619	* Server 2003, and earlier versions of Windows, unless
620	* BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
621	* two issues that should be considered before enabling its use:
622	*
623	* @li It will only cancel asynchronous operations that were initiated in the
624	* current thread.
625	*
626	* @li It can appear to complete without error, but the request to cancel the
627	* unfinished operations may be silently ignored by the operating system.
628	* Whether it works or not seems to depend on the drivers that are installed.
629	*
630	* For portable cancellation, consider using one of the following
631	* alternatives:
632	*
633	* @li Disable asio's I/O completion port backend by defining
634	* BOOST_ASIO_DISABLE_IOCP.
635	*
636	* @li Use the close() function to simultaneously cancel the outstanding
637	* operations and close the socket.
638	*
639	* When running on Windows Vista, Windows Server 2008, and later, the
640	* CancelIoEx function is always used. This function does not have the
641	* problems described above.
642	*/
643	#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
644	&& (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
645	&& !defined(BOOST_ASIO_ENABLE_CANCELIO)
646	__declspec(deprecated("By default, this function always fails with "
647	"operation_not_supported when used on Windows XP, Windows Server 2003, "
648	"or earlier. Consult documentation for details."))
649	#endif
650	void cancel()
651	{
652	boost::system::error_code ec;
653	impl_.get_service().cancel(impl_.get_implementation(), ec);
654	boost::asio::detail::throw_error(err: ec, location: "cancel");
655	}
656
657	/// Cancel all asynchronous operations associated with the socket.
658	/**
659	* This function causes all outstanding asynchronous connect, send and receive
660	* operations to finish immediately, and the handlers for cancelled operations
661	* will be passed the boost::asio::error::operation_aborted error.
662	*
663	* @param ec Set to indicate what error occurred, if any.
664	*
665	* @note Calls to cancel() will always fail with
666	* boost::asio::error::operation_not_supported when run on Windows XP, Windows
667	* Server 2003, and earlier versions of Windows, unless
668	* BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
669	* two issues that should be considered before enabling its use:
670	*
671	* @li It will only cancel asynchronous operations that were initiated in the
672	* current thread.
673	*
674	* @li It can appear to complete without error, but the request to cancel the
675	* unfinished operations may be silently ignored by the operating system.
676	* Whether it works or not seems to depend on the drivers that are installed.
677	*
678	* For portable cancellation, consider using one of the following
679	* alternatives:
680	*
681	* @li Disable asio's I/O completion port backend by defining
682	* BOOST_ASIO_DISABLE_IOCP.
683	*
684	* @li Use the close() function to simultaneously cancel the outstanding
685	* operations and close the socket.
686	*
687	* When running on Windows Vista, Windows Server 2008, and later, the
688	* CancelIoEx function is always used. This function does not have the
689	* problems described above.
690	*/
691	#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
692	&& (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
693	&& !defined(BOOST_ASIO_ENABLE_CANCELIO)
694	__declspec(deprecated("By default, this function always fails with "
695	"operation_not_supported when used on Windows XP, Windows Server 2003, "
696	"or earlier. Consult documentation for details."))
697	#endif
698	BOOST_ASIO_SYNC_OP_VOID cancel(boost::system::error_code& ec)
699	{
700	impl_.get_service().cancel(impl_.get_implementation(), ec);
701	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
702	}
703
704	/// Determine whether the socket is at the out-of-band data mark.
705	/**
706	* This function is used to check whether the socket input is currently
707	* positioned at the out-of-band data mark.
708	*
709	* @return A bool indicating whether the socket is at the out-of-band data
710	* mark.
711	*
712	* @throws boost::system::system_error Thrown on failure.
713	*/
714	bool at_mark() const
715	{
716	boost::system::error_code ec;
717	bool b = impl_.get_service().at_mark(impl_.get_implementation(), ec);
718	boost::asio::detail::throw_error(err: ec, location: "at_mark");
719	return b;
720	}
721
722	/// Determine whether the socket is at the out-of-band data mark.
723	/**
724	* This function is used to check whether the socket input is currently
725	* positioned at the out-of-band data mark.
726	*
727	* @param ec Set to indicate what error occurred, if any.
728	*
729	* @return A bool indicating whether the socket is at the out-of-band data
730	* mark.
731	*/
732	bool at_mark(boost::system::error_code& ec) const
733	{
734	return impl_.get_service().at_mark(impl_.get_implementation(), ec);
735	}
736
737	/// Determine the number of bytes available for reading.
738	/**
739	* This function is used to determine the number of bytes that may be read
740	* without blocking.
741	*
742	* @return The number of bytes that may be read without blocking, or 0 if an
743	* error occurs.
744	*
745	* @throws boost::system::system_error Thrown on failure.
746	*/
747	std::size_t available() const
748	{
749	boost::system::error_code ec;
750	std::size_t s = impl_.get_service().available(
751	impl_.get_implementation(), ec);
752	boost::asio::detail::throw_error(err: ec, location: "available");
753	return s;
754	}
755
756	/// Determine the number of bytes available for reading.
757	/**
758	* This function is used to determine the number of bytes that may be read
759	* without blocking.
760	*
761	* @param ec Set to indicate what error occurred, if any.
762	*
763	* @return The number of bytes that may be read without blocking, or 0 if an
764	* error occurs.
765	*/
766	std::size_t available(boost::system::error_code& ec) const
767	{
768	return impl_.get_service().available(impl_.get_implementation(), ec);
769	}
770
771	/// Bind the socket to the given local endpoint.
772	/**
773	* This function binds the socket to the specified endpoint on the local
774	* machine.
775	*
776	* @param endpoint An endpoint on the local machine to which the socket will
777	* be bound.
778	*
779	* @throws boost::system::system_error Thrown on failure.
780	*
781	* @par Example
782	* @code
783	* boost::asio::ip::tcp::socket socket(my_context);
784	* socket.open(boost::asio::ip::tcp::v4());
785	* socket.bind(boost::asio::ip::tcp::endpoint(
786	* boost::asio::ip::tcp::v4(), 12345));
787	* @endcode
788	*/
789	void bind(const endpoint_type& endpoint)
790	{
791	boost::system::error_code ec;
792	impl_.get_service().bind(impl_.get_implementation(), endpoint, ec);
793	boost::asio::detail::throw_error(err: ec, location: "bind");
794	}
795
796	/// Bind the socket to the given local endpoint.
797	/**
798	* This function binds the socket to the specified endpoint on the local
799	* machine.
800	*
801	* @param endpoint An endpoint on the local machine to which the socket will
802	* be bound.
803	*
804	* @param ec Set to indicate what error occurred, if any.
805	*
806	* @par Example
807	* @code
808	* boost::asio::ip::tcp::socket socket(my_context);
809	* socket.open(boost::asio::ip::tcp::v4());
810	* boost::system::error_code ec;
811	* socket.bind(boost::asio::ip::tcp::endpoint(
812	* boost::asio::ip::tcp::v4(), 12345), ec);
813	* if (ec)
814	* {
815	* // An error occurred.
816	* }
817	* @endcode
818	*/
819	BOOST_ASIO_SYNC_OP_VOID bind(const endpoint_type& endpoint,
820	boost::system::error_code& ec)
821	{
822	impl_.get_service().bind(impl_.get_implementation(), endpoint, ec);
823	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
824	}
825
826	/// Connect the socket to the specified endpoint.
827	/**
828	* This function is used to connect a socket to the specified remote endpoint.
829	* The function call will block until the connection is successfully made or
830	* an error occurs.
831	*
832	* The socket is automatically opened if it is not already open. If the
833	* connect fails, and the socket was automatically opened, the socket is
834	* not returned to the closed state.
835	*
836	* @param peer_endpoint The remote endpoint to which the socket will be
837	* connected.
838	*
839	* @throws boost::system::system_error Thrown on failure.
840	*
841	* @par Example
842	* @code
843	* boost::asio::ip::tcp::socket socket(my_context);
844	* boost::asio::ip::tcp::endpoint endpoint(
845	* boost::asio::ip::address::from_string("1.2.3.4"), 12345);
846	* socket.connect(endpoint);
847	* @endcode
848	*/
849	void connect(const endpoint_type& peer_endpoint)
850	{
851	boost::system::error_code ec;
852	if (!is_open())
853	{
854	impl_.get_service().open(impl_.get_implementation(),
855	peer_endpoint.protocol(), ec);
856	boost::asio::detail::throw_error(err: ec, location: "connect");
857	}
858	impl_.get_service().connect(impl_.get_implementation(), peer_endpoint, ec);
859	boost::asio::detail::throw_error(err: ec, location: "connect");
860	}
861
862	/// Connect the socket to the specified endpoint.
863	/**
864	* This function is used to connect a socket to the specified remote endpoint.
865	* The function call will block until the connection is successfully made or
866	* an error occurs.
867	*
868	* The socket is automatically opened if it is not already open. If the
869	* connect fails, and the socket was automatically opened, the socket is
870	* not returned to the closed state.
871	*
872	* @param peer_endpoint The remote endpoint to which the socket will be
873	* connected.
874	*
875	* @param ec Set to indicate what error occurred, if any.
876	*
877	* @par Example
878	* @code
879	* boost::asio::ip::tcp::socket socket(my_context);
880	* boost::asio::ip::tcp::endpoint endpoint(
881	* boost::asio::ip::address::from_string("1.2.3.4"), 12345);
882	* boost::system::error_code ec;
883	* socket.connect(endpoint, ec);
884	* if (ec)
885	* {
886	* // An error occurred.
887	* }
888	* @endcode
889	*/
890	BOOST_ASIO_SYNC_OP_VOID connect(const endpoint_type& peer_endpoint,
891	boost::system::error_code& ec)
892	{
893	if (!is_open())
894	{
895	impl_.get_service().open(impl_.get_implementation(),
896	peer_endpoint.protocol(), ec);
897	if (ec)
898	{
899	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
900	}
901	}
902
903	impl_.get_service().connect(impl_.get_implementation(), peer_endpoint, ec);
904	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
905	}
906
907	/// Start an asynchronous connect.
908	/**
909	* This function is used to asynchronously connect a socket to the specified
910	* remote endpoint. It is an initiating function for an @ref
911	* asynchronous_operation, and always returns immediately.
912	*
913	* The socket is automatically opened if it is not already open. If the
914	* connect fails, and the socket was automatically opened, the socket is
915	* not returned to the closed state.
916	*
917	* @param peer_endpoint The remote endpoint to which the socket will be
918	* connected. Copies will be made of the endpoint object as required.
919	*
920	* @param token The @ref completion_token that will be used to produce a
921	* completion handler, which will be called when the connect completes.
922	* Potential completion tokens include @ref use_future, @ref use_awaitable,
923	* @ref yield_context, or a function object with the correct completion
924	* signature. The function signature of the completion handler must be:
925	* @code void handler(
926	* const boost::system::error_code& error // Result of operation.
927	* ); @endcode
928	* Regardless of whether the asynchronous operation completes immediately or
929	* not, the completion handler will not be invoked from within this function.
930	* On immediate completion, invocation of the handler will be performed in a
931	* manner equivalent to using boost::asio::post().
932	*
933	* @par Completion Signature
934	* @code void(boost::system::error_code) @endcode
935	*
936	* @par Example
937	* @code
938	* void connect_handler(const boost::system::error_code& error)
939	* {
940	* if (!error)
941	* {
942	* // Connect succeeded.
943	* }
944	* }
945	*
946	* ...
947	*
948	* boost::asio::ip::tcp::socket socket(my_context);
949	* boost::asio::ip::tcp::endpoint endpoint(
950	* boost::asio::ip::address::from_string("1.2.3.4"), 12345);
951	* socket.async_connect(endpoint, connect_handler);
952	* @endcode
953	*
954	* @par Per-Operation Cancellation
955	* On POSIX or Windows operating systems, this asynchronous operation supports
956	* cancellation for the following boost::asio::cancellation_type values:
957	*
958	* @li @c cancellation_type::terminal
959	*
960	* @li @c cancellation_type::partial
961	*
962	* @li @c cancellation_type::total
963	*/
964	template <
965	BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code))
966	ConnectToken = default_completion_token_t<executor_type>>
967	auto async_connect(const endpoint_type& peer_endpoint,
968	ConnectToken&& token = default_completion_token_t<executor_type>())
969	-> decltype(
970	async_initiate<ConnectToken, void (boost::system::error_code)>(
971	declval<initiate_async_connect>(), token,
972	peer_endpoint, declval<boost::system::error_code&>()))
973	{
974	boost::system::error_code open_ec;
975	if (!is_open())
976	{
977	const protocol_type protocol = peer_endpoint.protocol();
978	impl_.get_service().open(impl_.get_implementation(), protocol, open_ec);
979	}
980
981	return async_initiate<ConnectToken, void (boost::system::error_code)>(
982	initiate_async_connect(this), token, peer_endpoint, open_ec);
983	}
984
985	/// Set an option on the socket.
986	/**
987	* This function is used to set an option on the socket.
988	*
989	* @param option The new option value to be set on the socket.
990	*
991	* @throws boost::system::system_error Thrown on failure.
992	*
993	* @sa SettableSocketOption @n
994	* boost::asio::socket_base::broadcast @n
995	* boost::asio::socket_base::do_not_route @n
996	* boost::asio::socket_base::keep_alive @n
997	* boost::asio::socket_base::linger @n
998	* boost::asio::socket_base::receive_buffer_size @n
999	* boost::asio::socket_base::receive_low_watermark @n
1000	* boost::asio::socket_base::reuse_address @n
1001	* boost::asio::socket_base::send_buffer_size @n
1002	* boost::asio::socket_base::send_low_watermark @n
1003	* boost::asio::ip::multicast::join_group @n
1004	* boost::asio::ip::multicast::leave_group @n
1005	* boost::asio::ip::multicast::enable_loopback @n
1006	* boost::asio::ip::multicast::outbound_interface @n
1007	* boost::asio::ip::multicast::hops @n
1008	* boost::asio::ip::tcp::no_delay
1009	*
1010	* @par Example
1011	* Setting the IPPROTO_TCP/TCP_NODELAY option:
1012	* @code
1013	* boost::asio::ip::tcp::socket socket(my_context);
1014	* ...
1015	* boost::asio::ip::tcp::no_delay option(true);
1016	* socket.set_option(option);
1017	* @endcode
1018	*/
1019	template <typename SettableSocketOption>
1020	void set_option(const SettableSocketOption& option)
1021	{
1022	boost::system::error_code ec;
1023	impl_.get_service().set_option(impl_.get_implementation(), option, ec);
1024	boost::asio::detail::throw_error(err: ec, location: "set_option");
1025	}
1026
1027	/// Set an option on the socket.
1028	/**
1029	* This function is used to set an option on the socket.
1030	*
1031	* @param option The new option value to be set on the socket.
1032	*
1033	* @param ec Set to indicate what error occurred, if any.
1034	*
1035	* @sa SettableSocketOption @n
1036	* boost::asio::socket_base::broadcast @n
1037	* boost::asio::socket_base::do_not_route @n
1038	* boost::asio::socket_base::keep_alive @n
1039	* boost::asio::socket_base::linger @n
1040	* boost::asio::socket_base::receive_buffer_size @n
1041	* boost::asio::socket_base::receive_low_watermark @n
1042	* boost::asio::socket_base::reuse_address @n
1043	* boost::asio::socket_base::send_buffer_size @n
1044	* boost::asio::socket_base::send_low_watermark @n
1045	* boost::asio::ip::multicast::join_group @n
1046	* boost::asio::ip::multicast::leave_group @n
1047	* boost::asio::ip::multicast::enable_loopback @n
1048	* boost::asio::ip::multicast::outbound_interface @n
1049	* boost::asio::ip::multicast::hops @n
1050	* boost::asio::ip::tcp::no_delay
1051	*
1052	* @par Example
1053	* Setting the IPPROTO_TCP/TCP_NODELAY option:
1054	* @code
1055	* boost::asio::ip::tcp::socket socket(my_context);
1056	* ...
1057	* boost::asio::ip::tcp::no_delay option(true);
1058	* boost::system::error_code ec;
1059	* socket.set_option(option, ec);
1060	* if (ec)
1061	* {
1062	* // An error occurred.
1063	* }
1064	* @endcode
1065	*/
1066	template <typename SettableSocketOption>
1067	BOOST_ASIO_SYNC_OP_VOID set_option(const SettableSocketOption& option,
1068	boost::system::error_code& ec)
1069	{
1070	impl_.get_service().set_option(impl_.get_implementation(), option, ec);
1071	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1072	}
1073
1074	/// Get an option from the socket.
1075	/**
1076	* This function is used to get the current value of an option on the socket.
1077	*
1078	* @param option The option value to be obtained from the socket.
1079	*
1080	* @throws boost::system::system_error Thrown on failure.
1081	*
1082	* @sa GettableSocketOption @n
1083	* boost::asio::socket_base::broadcast @n
1084	* boost::asio::socket_base::do_not_route @n
1085	* boost::asio::socket_base::keep_alive @n
1086	* boost::asio::socket_base::linger @n
1087	* boost::asio::socket_base::receive_buffer_size @n
1088	* boost::asio::socket_base::receive_low_watermark @n
1089	* boost::asio::socket_base::reuse_address @n
1090	* boost::asio::socket_base::send_buffer_size @n
1091	* boost::asio::socket_base::send_low_watermark @n
1092	* boost::asio::ip::multicast::join_group @n
1093	* boost::asio::ip::multicast::leave_group @n
1094	* boost::asio::ip::multicast::enable_loopback @n
1095	* boost::asio::ip::multicast::outbound_interface @n
1096	* boost::asio::ip::multicast::hops @n
1097	* boost::asio::ip::tcp::no_delay
1098	*
1099	* @par Example
1100	* Getting the value of the SOL_SOCKET/SO_KEEPALIVE option:
1101	* @code
1102	* boost::asio::ip::tcp::socket socket(my_context);
1103	* ...
1104	* boost::asio::ip::tcp::socket::keep_alive option;
1105	* socket.get_option(option);
1106	* bool is_set = option.value();
1107	* @endcode
1108	*/
1109	template <typename GettableSocketOption>
1110	void get_option(GettableSocketOption& option) const
1111	{
1112	boost::system::error_code ec;
1113	impl_.get_service().get_option(impl_.get_implementation(), option, ec);
1114	boost::asio::detail::throw_error(err: ec, location: "get_option");
1115	}
1116
1117	/// Get an option from the socket.
1118	/**
1119	* This function is used to get the current value of an option on the socket.
1120	*
1121	* @param option The option value to be obtained from the socket.
1122	*
1123	* @param ec Set to indicate what error occurred, if any.
1124	*
1125	* @sa GettableSocketOption @n
1126	* boost::asio::socket_base::broadcast @n
1127	* boost::asio::socket_base::do_not_route @n
1128	* boost::asio::socket_base::keep_alive @n
1129	* boost::asio::socket_base::linger @n
1130	* boost::asio::socket_base::receive_buffer_size @n
1131	* boost::asio::socket_base::receive_low_watermark @n
1132	* boost::asio::socket_base::reuse_address @n
1133	* boost::asio::socket_base::send_buffer_size @n
1134	* boost::asio::socket_base::send_low_watermark @n
1135	* boost::asio::ip::multicast::join_group @n
1136	* boost::asio::ip::multicast::leave_group @n
1137	* boost::asio::ip::multicast::enable_loopback @n
1138	* boost::asio::ip::multicast::outbound_interface @n
1139	* boost::asio::ip::multicast::hops @n
1140	* boost::asio::ip::tcp::no_delay
1141	*
1142	* @par Example
1143	* Getting the value of the SOL_SOCKET/SO_KEEPALIVE option:
1144	* @code
1145	* boost::asio::ip::tcp::socket socket(my_context);
1146	* ...
1147	* boost::asio::ip::tcp::socket::keep_alive option;
1148	* boost::system::error_code ec;
1149	* socket.get_option(option, ec);
1150	* if (ec)
1151	* {
1152	* // An error occurred.
1153	* }
1154	* bool is_set = option.value();
1155	* @endcode
1156	*/
1157	template <typename GettableSocketOption>
1158	BOOST_ASIO_SYNC_OP_VOID get_option(GettableSocketOption& option,
1159	boost::system::error_code& ec) const
1160	{
1161	impl_.get_service().get_option(impl_.get_implementation(), option, ec);
1162	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1163	}
1164
1165	/// Perform an IO control command on the socket.
1166	/**
1167	* This function is used to execute an IO control command on the socket.
1168	*
1169	* @param command The IO control command to be performed on the socket.
1170	*
1171	* @throws boost::system::system_error Thrown on failure.
1172	*
1173	* @sa IoControlCommand @n
1174	* boost::asio::socket_base::bytes_readable @n
1175	* boost::asio::socket_base::non_blocking_io
1176	*
1177	* @par Example
1178	* Getting the number of bytes ready to read:
1179	* @code
1180	* boost::asio::ip::tcp::socket socket(my_context);
1181	* ...
1182	* boost::asio::ip::tcp::socket::bytes_readable command;
1183	* socket.io_control(command);
1184	* std::size_t bytes_readable = command.get();
1185	* @endcode
1186	*/
1187	template <typename IoControlCommand>
1188	void io_control(IoControlCommand& command)
1189	{
1190	boost::system::error_code ec;
1191	impl_.get_service().io_control(impl_.get_implementation(), command, ec);
1192	boost::asio::detail::throw_error(err: ec, location: "io_control");
1193	}
1194
1195	/// Perform an IO control command on the socket.
1196	/**
1197	* This function is used to execute an IO control command on the socket.
1198	*
1199	* @param command The IO control command to be performed on the socket.
1200	*
1201	* @param ec Set to indicate what error occurred, if any.
1202	*
1203	* @sa IoControlCommand @n
1204	* boost::asio::socket_base::bytes_readable @n
1205	* boost::asio::socket_base::non_blocking_io
1206	*
1207	* @par Example
1208	* Getting the number of bytes ready to read:
1209	* @code
1210	* boost::asio::ip::tcp::socket socket(my_context);
1211	* ...
1212	* boost::asio::ip::tcp::socket::bytes_readable command;
1213	* boost::system::error_code ec;
1214	* socket.io_control(command, ec);
1215	* if (ec)
1216	* {
1217	* // An error occurred.
1218	* }
1219	* std::size_t bytes_readable = command.get();
1220	* @endcode
1221	*/
1222	template <typename IoControlCommand>
1223	BOOST_ASIO_SYNC_OP_VOID io_control(IoControlCommand& command,
1224	boost::system::error_code& ec)
1225	{
1226	impl_.get_service().io_control(impl_.get_implementation(), command, ec);
1227	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1228	}
1229
1230	/// Gets the non-blocking mode of the socket.
1231	/**
1232	* @returns @c true if the socket's synchronous operations will fail with
1233	* boost::asio::error::would_block if they are unable to perform the requested
1234	* operation immediately. If @c false, synchronous operations will block
1235	* until complete.
1236	*
1237	* @note The non-blocking mode has no effect on the behaviour of asynchronous
1238	* operations. Asynchronous operations will never fail with the error
1239	* boost::asio::error::would_block.
1240	*/
1241	bool non_blocking() const
1242	{
1243	return impl_.get_service().non_blocking(impl_.get_implementation());
1244	}
1245
1246	/// Sets the non-blocking mode of the socket.
1247	/**
1248	* @param mode If @c true, the socket's synchronous operations will fail with
1249	* boost::asio::error::would_block if they are unable to perform the requested
1250	* operation immediately. If @c false, synchronous operations will block
1251	* until complete.
1252	*
1253	* @throws boost::system::system_error Thrown on failure.
1254	*
1255	* @note The non-blocking mode has no effect on the behaviour of asynchronous
1256	* operations. Asynchronous operations will never fail with the error
1257	* boost::asio::error::would_block.
1258	*/
1259	void non_blocking(bool mode)
1260	{
1261	boost::system::error_code ec;
1262	impl_.get_service().non_blocking(impl_.get_implementation(), mode, ec);
1263	boost::asio::detail::throw_error(err: ec, location: "non_blocking");
1264	}
1265
1266	/// Sets the non-blocking mode of the socket.
1267	/**
1268	* @param mode If @c true, the socket's synchronous operations will fail with
1269	* boost::asio::error::would_block if they are unable to perform the requested
1270	* operation immediately. If @c false, synchronous operations will block
1271	* until complete.
1272	*
1273	* @param ec Set to indicate what error occurred, if any.
1274	*
1275	* @note The non-blocking mode has no effect on the behaviour of asynchronous
1276	* operations. Asynchronous operations will never fail with the error
1277	* boost::asio::error::would_block.
1278	*/
1279	BOOST_ASIO_SYNC_OP_VOID non_blocking(
1280	bool mode, boost::system::error_code& ec)
1281	{
1282	impl_.get_service().non_blocking(impl_.get_implementation(), mode, ec);
1283	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1284	}
1285
1286	/// Gets the non-blocking mode of the native socket implementation.
1287	/**
1288	* This function is used to retrieve the non-blocking mode of the underlying
1289	* native socket. This mode has no effect on the behaviour of the socket
1290	* object's synchronous operations.
1291	*
1292	* @returns @c true if the underlying socket is in non-blocking mode and
1293	* direct system calls may fail with boost::asio::error::would_block (or the
1294	* equivalent system error).
1295	*
1296	* @note The current non-blocking mode is cached by the socket object.
1297	* Consequently, the return value may be incorrect if the non-blocking mode
1298	* was set directly on the native socket.
1299	*
1300	* @par Example
1301	* This function is intended to allow the encapsulation of arbitrary
1302	* non-blocking system calls as asynchronous operations, in a way that is
1303	* transparent to the user of the socket object. The following example
1304	* illustrates how Linux's @c sendfile system call might be encapsulated:
1305	* @code template <typename Handler>
1306	* struct sendfile_op
1307	* {
1308	* tcp::socket& sock_;
1309	* int fd_;
1310	* Handler handler_;
1311	* off_t offset_;
1312	* std::size_t total_bytes_transferred_;
1313	*
1314	* // Function call operator meeting WriteHandler requirements.
1315	* // Used as the handler for the async_write_some operation.
1316	* void operator()(boost::system::error_code ec, std::size_t)
1317	* {
1318	* // Put the underlying socket into non-blocking mode.
1319	* if (!ec)
1320	* if (!sock_.native_non_blocking())
1321	* sock_.native_non_blocking(true, ec);
1322	*
1323	* if (!ec)
1324	* {
1325	* for (;;)
1326	* {
1327	* // Try the system call.
1328	* errno = 0;
1329	* int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536);
1330	* ec = boost::system::error_code(n < 0 ? errno : 0,
1331	* boost::asio::error::get_system_category());
1332	* total_bytes_transferred_ += ec ? 0 : n;
1333	*
1334	* // Retry operation immediately if interrupted by signal.
1335	* if (ec == boost::asio::error::interrupted)
1336	* continue;
1337	*
1338	* // Check if we need to run the operation again.
1339	* if (ec == boost::asio::error::would_block
1340	* || ec == boost::asio::error::try_again)
1341	* {
1342	* // We have to wait for the socket to become ready again.
1343	* sock_.async_wait(tcp::socket::wait_write, *this);
1344	* return;
1345	* }
1346	*
1347	* if (ec || n == 0)
1348	* {
1349	* // An error occurred, or we have reached the end of the file.
1350	* // Either way we must exit the loop so we can call the handler.
1351	* break;
1352	* }
1353	*
1354	* // Loop around to try calling sendfile again.
1355	* }
1356	* }
1357	*
1358	* // Pass result back to user's handler.
1359	* handler_(ec, total_bytes_transferred_);
1360	* }
1361	* };
1362	*
1363	* template <typename Handler>
1364	* void async_sendfile(tcp::socket& sock, int fd, Handler h)
1365	* {
1366	* sendfile_op<Handler> op = { sock, fd, h, 0, 0 };
1367	* sock.async_wait(tcp::socket::wait_write, op);
1368	* } @endcode
1369	*/
1370	bool native_non_blocking() const
1371	{
1372	return impl_.get_service().native_non_blocking(impl_.get_implementation());
1373	}
1374
1375	/// Sets the non-blocking mode of the native socket implementation.
1376	/**
1377	* This function is used to modify the non-blocking mode of the underlying
1378	* native socket. It has no effect on the behaviour of the socket object's
1379	* synchronous operations.
1380	*
1381	* @param mode If @c true, the underlying socket is put into non-blocking
1382	* mode and direct system calls may fail with boost::asio::error::would_block
1383	* (or the equivalent system error).
1384	*
1385	* @throws boost::system::system_error Thrown on failure. If the @c mode is
1386	* @c false, but the current value of @c non_blocking() is @c true, this
1387	* function fails with boost::asio::error::invalid_argument, as the
1388	* combination does not make sense.
1389	*
1390	* @par Example
1391	* This function is intended to allow the encapsulation of arbitrary
1392	* non-blocking system calls as asynchronous operations, in a way that is
1393	* transparent to the user of the socket object. The following example
1394	* illustrates how Linux's @c sendfile system call might be encapsulated:
1395	* @code template <typename Handler>
1396	* struct sendfile_op
1397	* {
1398	* tcp::socket& sock_;
1399	* int fd_;
1400	* Handler handler_;
1401	* off_t offset_;
1402	* std::size_t total_bytes_transferred_;
1403	*
1404	* // Function call operator meeting WriteHandler requirements.
1405	* // Used as the handler for the async_write_some operation.
1406	* void operator()(boost::system::error_code ec, std::size_t)
1407	* {
1408	* // Put the underlying socket into non-blocking mode.
1409	* if (!ec)
1410	* if (!sock_.native_non_blocking())
1411	* sock_.native_non_blocking(true, ec);
1412	*
1413	* if (!ec)
1414	* {
1415	* for (;;)
1416	* {
1417	* // Try the system call.
1418	* errno = 0;
1419	* int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536);
1420	* ec = boost::system::error_code(n < 0 ? errno : 0,
1421	* boost::asio::error::get_system_category());
1422	* total_bytes_transferred_ += ec ? 0 : n;
1423	*
1424	* // Retry operation immediately if interrupted by signal.
1425	* if (ec == boost::asio::error::interrupted)
1426	* continue;
1427	*
1428	* // Check if we need to run the operation again.
1429	* if (ec == boost::asio::error::would_block
1430	* || ec == boost::asio::error::try_again)
1431	* {
1432	* // We have to wait for the socket to become ready again.
1433	* sock_.async_wait(tcp::socket::wait_write, *this);
1434	* return;
1435	* }
1436	*
1437	* if (ec || n == 0)
1438	* {
1439	* // An error occurred, or we have reached the end of the file.
1440	* // Either way we must exit the loop so we can call the handler.
1441	* break;
1442	* }
1443	*
1444	* // Loop around to try calling sendfile again.
1445	* }
1446	* }
1447	*
1448	* // Pass result back to user's handler.
1449	* handler_(ec, total_bytes_transferred_);
1450	* }
1451	* };
1452	*
1453	* template <typename Handler>
1454	* void async_sendfile(tcp::socket& sock, int fd, Handler h)
1455	* {
1456	* sendfile_op<Handler> op = { sock, fd, h, 0, 0 };
1457	* sock.async_wait(tcp::socket::wait_write, op);
1458	* } @endcode
1459	*/
1460	void native_non_blocking(bool mode)
1461	{
1462	boost::system::error_code ec;
1463	impl_.get_service().native_non_blocking(
1464	impl_.get_implementation(), mode, ec);
1465	boost::asio::detail::throw_error(err: ec, location: "native_non_blocking");
1466	}
1467
1468	/// Sets the non-blocking mode of the native socket implementation.
1469	/**
1470	* This function is used to modify the non-blocking mode of the underlying
1471	* native socket. It has no effect on the behaviour of the socket object's
1472	* synchronous operations.
1473	*
1474	* @param mode If @c true, the underlying socket is put into non-blocking
1475	* mode and direct system calls may fail with boost::asio::error::would_block
1476	* (or the equivalent system error).
1477	*
1478	* @param ec Set to indicate what error occurred, if any. If the @c mode is
1479	* @c false, but the current value of @c non_blocking() is @c true, this
1480	* function fails with boost::asio::error::invalid_argument, as the
1481	* combination does not make sense.
1482	*
1483	* @par Example
1484	* This function is intended to allow the encapsulation of arbitrary
1485	* non-blocking system calls as asynchronous operations, in a way that is
1486	* transparent to the user of the socket object. The following example
1487	* illustrates how Linux's @c sendfile system call might be encapsulated:
1488	* @code template <typename Handler>
1489	* struct sendfile_op
1490	* {
1491	* tcp::socket& sock_;
1492	* int fd_;
1493	* Handler handler_;
1494	* off_t offset_;
1495	* std::size_t total_bytes_transferred_;
1496	*
1497	* // Function call operator meeting WriteHandler requirements.
1498	* // Used as the handler for the async_write_some operation.
1499	* void operator()(boost::system::error_code ec, std::size_t)
1500	* {
1501	* // Put the underlying socket into non-blocking mode.
1502	* if (!ec)
1503	* if (!sock_.native_non_blocking())
1504	* sock_.native_non_blocking(true, ec);
1505	*
1506	* if (!ec)
1507	* {
1508	* for (;;)
1509	* {
1510	* // Try the system call.
1511	* errno = 0;
1512	* int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536);
1513	* ec = boost::system::error_code(n < 0 ? errno : 0,
1514	* boost::asio::error::get_system_category());
1515	* total_bytes_transferred_ += ec ? 0 : n;
1516	*
1517	* // Retry operation immediately if interrupted by signal.
1518	* if (ec == boost::asio::error::interrupted)
1519	* continue;
1520	*
1521	* // Check if we need to run the operation again.
1522	* if (ec == boost::asio::error::would_block
1523	* || ec == boost::asio::error::try_again)
1524	* {
1525	* // We have to wait for the socket to become ready again.
1526	* sock_.async_wait(tcp::socket::wait_write, *this);
1527	* return;
1528	* }
1529	*
1530	* if (ec || n == 0)
1531	* {
1532	* // An error occurred, or we have reached the end of the file.
1533	* // Either way we must exit the loop so we can call the handler.
1534	* break;
1535	* }
1536	*
1537	* // Loop around to try calling sendfile again.
1538	* }
1539	* }
1540	*
1541	* // Pass result back to user's handler.
1542	* handler_(ec, total_bytes_transferred_);
1543	* }
1544	* };
1545	*
1546	* template <typename Handler>
1547	* void async_sendfile(tcp::socket& sock, int fd, Handler h)
1548	* {
1549	* sendfile_op<Handler> op = { sock, fd, h, 0, 0 };
1550	* sock.async_wait(tcp::socket::wait_write, op);
1551	* } @endcode
1552	*/
1553	BOOST_ASIO_SYNC_OP_VOID native_non_blocking(
1554	bool mode, boost::system::error_code& ec)
1555	{
1556	impl_.get_service().native_non_blocking(
1557	impl_.get_implementation(), mode, ec);
1558	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1559	}
1560
1561	/// Get the local endpoint of the socket.
1562	/**
1563	* This function is used to obtain the locally bound endpoint of the socket.
1564	*
1565	* @returns An object that represents the local endpoint of the socket.
1566	*
1567	* @throws boost::system::system_error Thrown on failure.
1568	*
1569	* @par Example
1570	* @code
1571	* boost::asio::ip::tcp::socket socket(my_context);
1572	* ...
1573	* boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
1574	* @endcode
1575	*/
1576	endpoint_type local_endpoint() const
1577	{
1578	boost::system::error_code ec;
1579	endpoint_type ep = impl_.get_service().local_endpoint(
1580	impl_.get_implementation(), ec);
1581	boost::asio::detail::throw_error(err: ec, location: "local_endpoint");
1582	return ep;
1583	}
1584
1585	/// Get the local endpoint of the socket.
1586	/**
1587	* This function is used to obtain the locally bound endpoint of the socket.
1588	*
1589	* @param ec Set to indicate what error occurred, if any.
1590	*
1591	* @returns An object that represents the local endpoint of the socket.
1592	* Returns a default-constructed endpoint object if an error occurred.
1593	*
1594	* @par Example
1595	* @code
1596	* boost::asio::ip::tcp::socket socket(my_context);
1597	* ...
1598	* boost::system::error_code ec;
1599	* boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
1600	* if (ec)
1601	* {
1602	* // An error occurred.
1603	* }
1604	* @endcode
1605	*/
1606	endpoint_type local_endpoint(boost::system::error_code& ec) const
1607	{
1608	return impl_.get_service().local_endpoint(impl_.get_implementation(), ec);
1609	}
1610
1611	/// Get the remote endpoint of the socket.
1612	/**
1613	* This function is used to obtain the remote endpoint of the socket.
1614	*
1615	* @returns An object that represents the remote endpoint of the socket.
1616	*
1617	* @throws boost::system::system_error Thrown on failure.
1618	*
1619	* @par Example
1620	* @code
1621	* boost::asio::ip::tcp::socket socket(my_context);
1622	* ...
1623	* boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
1624	* @endcode
1625	*/
1626	endpoint_type remote_endpoint() const
1627	{
1628	boost::system::error_code ec;
1629	endpoint_type ep = impl_.get_service().remote_endpoint(
1630	impl_.get_implementation(), ec);
1631	boost::asio::detail::throw_error(err: ec, location: "remote_endpoint");
1632	return ep;
1633	}
1634
1635	/// Get the remote endpoint of the socket.
1636	/**
1637	* This function is used to obtain the remote endpoint of the socket.
1638	*
1639	* @param ec Set to indicate what error occurred, if any.
1640	*
1641	* @returns An object that represents the remote endpoint of the socket.
1642	* Returns a default-constructed endpoint object if an error occurred.
1643	*
1644	* @par Example
1645	* @code
1646	* boost::asio::ip::tcp::socket socket(my_context);
1647	* ...
1648	* boost::system::error_code ec;
1649	* boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
1650	* if (ec)
1651	* {
1652	* // An error occurred.
1653	* }
1654	* @endcode
1655	*/
1656	endpoint_type remote_endpoint(boost::system::error_code& ec) const
1657	{
1658	return impl_.get_service().remote_endpoint(impl_.get_implementation(), ec);
1659	}
1660
1661	/// Disable sends or receives on the socket.
1662	/**
1663	* This function is used to disable send operations, receive operations, or
1664	* both.
1665	*
1666	* @param what Determines what types of operation will no longer be allowed.
1667	*
1668	* @throws boost::system::system_error Thrown on failure.
1669	*
1670	* @par Example
1671	* Shutting down the send side of the socket:
1672	* @code
1673	* boost::asio::ip::tcp::socket socket(my_context);
1674	* ...
1675	* socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
1676	* @endcode
1677	*/
1678	void shutdown(shutdown_type what)
1679	{
1680	boost::system::error_code ec;
1681	impl_.get_service().shutdown(impl_.get_implementation(), what, ec);
1682	boost::asio::detail::throw_error(err: ec, location: "shutdown");
1683	}
1684
1685	/// Disable sends or receives on the socket.
1686	/**
1687	* This function is used to disable send operations, receive operations, or
1688	* both.
1689	*
1690	* @param what Determines what types of operation will no longer be allowed.
1691	*
1692	* @param ec Set to indicate what error occurred, if any.
1693	*
1694	* @par Example
1695	* Shutting down the send side of the socket:
1696	* @code
1697	* boost::asio::ip::tcp::socket socket(my_context);
1698	* ...
1699	* boost::system::error_code ec;
1700	* socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
1701	* if (ec)
1702	* {
1703	* // An error occurred.
1704	* }
1705	* @endcode
1706	*/
1707	BOOST_ASIO_SYNC_OP_VOID shutdown(shutdown_type what,
1708	boost::system::error_code& ec)
1709	{
1710	impl_.get_service().shutdown(impl_.get_implementation(), what, ec);
1711	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1712	}
1713
1714	/// Wait for the socket to become ready to read, ready to write, or to have
1715	/// pending error conditions.
1716	/**
1717	* This function is used to perform a blocking wait for a socket to enter
1718	* a ready to read, write or error condition state.
1719	*
1720	* @param w Specifies the desired socket state.
1721	*
1722	* @par Example
1723	* Waiting for a socket to become readable.
1724	* @code
1725	* boost::asio::ip::tcp::socket socket(my_context);
1726	* ...
1727	* socket.wait(boost::asio::ip::tcp::socket::wait_read);
1728	* @endcode
1729	*/
1730	void wait(wait_type w)
1731	{
1732	boost::system::error_code ec;
1733	impl_.get_service().wait(impl_.get_implementation(), w, ec);
1734	boost::asio::detail::throw_error(err: ec, location: "wait");
1735	}
1736
1737	/// Wait for the socket to become ready to read, ready to write, or to have
1738	/// pending error conditions.
1739	/**
1740	* This function is used to perform a blocking wait for a socket to enter
1741	* a ready to read, write or error condition state.
1742	*
1743	* @param w Specifies the desired socket state.
1744	*
1745	* @param ec Set to indicate what error occurred, if any.
1746	*
1747	* @par Example
1748	* Waiting for a socket to become readable.
1749	* @code
1750	* boost::asio::ip::tcp::socket socket(my_context);
1751	* ...
1752	* boost::system::error_code ec;
1753	* socket.wait(boost::asio::ip::tcp::socket::wait_read, ec);
1754	* @endcode
1755	*/
1756	BOOST_ASIO_SYNC_OP_VOID wait(wait_type w, boost::system::error_code& ec)
1757	{
1758	impl_.get_service().wait(impl_.get_implementation(), w, ec);
1759	BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
1760	}
1761
1762	/// Asynchronously wait for the socket to become ready to read, ready to
1763	/// write, or to have pending error conditions.
1764	/**
1765	* This function is used to perform an asynchronous wait for a socket to enter
1766	* a ready to read, write or error condition state. It is an initiating
1767	* function for an @ref asynchronous_operation, and always returns
1768	* immediately.
1769	*
1770	* @param w Specifies the desired socket state.
1771	*
1772	* @param token The @ref completion_token that will be used to produce a
1773	* completion handler, which will be called when the wait completes. Potential
1774	* completion tokens include @ref use_future, @ref use_awaitable, @ref
1775	* yield_context, or a function object with the correct completion signature.
1776	* The function signature of the completion handler must be:
1777	* @code void handler(
1778	* const boost::system::error_code& error // Result of operation.
1779	* ); @endcode
1780	* Regardless of whether the asynchronous operation completes immediately or
1781	* not, the completion handler will not be invoked from within this function.
1782	* On immediate completion, invocation of the handler will be performed in a
1783	* manner equivalent to using boost::asio::post().
1784	*
1785	* @par Completion Signature
1786	* @code void(boost::system::error_code) @endcode
1787	*
1788	* @par Example
1789	* @code
1790	* void wait_handler(const boost::system::error_code& error)
1791	* {
1792	* if (!error)
1793	* {
1794	* // Wait succeeded.
1795	* }
1796	* }
1797	*
1798	* ...
1799	*
1800	* boost::asio::ip::tcp::socket socket(my_context);
1801	* ...
1802	* socket.async_wait(boost::asio::ip::tcp::socket::wait_read, wait_handler);
1803	* @endcode
1804	*
1805	* @par Per-Operation Cancellation
1806	* On POSIX or Windows operating systems, this asynchronous operation supports
1807	* cancellation for the following boost::asio::cancellation_type values:
1808	*
1809	* @li @c cancellation_type::terminal
1810	*
1811	* @li @c cancellation_type::partial
1812	*
1813	* @li @c cancellation_type::total
1814	*/
1815	template <
1816	BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code))
1817	WaitToken = default_completion_token_t<executor_type>>
1818	auto async_wait(wait_type w,
1819	WaitToken&& token = default_completion_token_t<executor_type>())
1820	-> decltype(
1821	async_initiate<WaitToken, void (boost::system::error_code)>(
1822	declval<initiate_async_wait>(), token, w))
1823	{
1824	return async_initiate<WaitToken, void (boost::system::error_code)>(
1825	initiate_async_wait(this), token, w);
1826	}
1827
1828	protected:
1829	/// Protected destructor to prevent deletion through this type.
1830	/**
1831	* This function destroys the socket, cancelling any outstanding asynchronous
1832	* operations associated with the socket as if by calling @c cancel.
1833	*/
1834	~basic_socket()
1835	{
1836	}
1837
1838	#if defined(BOOST_ASIO_WINDOWS_RUNTIME)
1839	detail::io_object_impl<
1840	detail::null_socket_service<Protocol>, Executor> impl_;
1841	#elif defined(BOOST_ASIO_HAS_IOCP)
1842	detail::io_object_impl<
1843	detail::win_iocp_socket_service<Protocol>, Executor> impl_;
1844	#elif defined(BOOST_ASIO_HAS_IO_URING_AS_DEFAULT)
1845	detail::io_object_impl<
1846	detail::io_uring_socket_service<Protocol>, Executor> impl_;
1847	#else
1848	detail::io_object_impl<
1849	detail::reactive_socket_service<Protocol>, Executor> impl_;
1850	#endif
1851
1852	private:
1853	// Disallow copying and assignment.
1854	basic_socket(const basic_socket&) = delete;
1855	basic_socket& operator=(const basic_socket&) = delete;
1856
1857	class initiate_async_connect
1858	{
1859	public:
1860	typedef Executor executor_type;
1861
1862	explicit initiate_async_connect(basic_socket* self)
1863	: self_(self)
1864	{
1865	}
1866
1867	const executor_type& get_executor() const noexcept
1868	{
1869	return self_->get_executor();
1870	}
1871
1872	template <typename ConnectHandler>
1873	void operator()(ConnectHandler&& handler,
1874	const endpoint_type& peer_endpoint,
1875	const boost::system::error_code& open_ec) const
1876	{
1877	// If you get an error on the following line it means that your handler
1878	// does not meet the documented type requirements for a ConnectHandler.
1879	BOOST_ASIO_CONNECT_HANDLER_CHECK(ConnectHandler, handler) type_check;
1880
1881	if (open_ec)
1882	{
1883	boost::asio::post(self_->impl_.get_executor(),
1884	boost::asio::detail::bind_handler(
1885	static_cast<ConnectHandler&&>(handler), open_ec));
1886	}
1887	else
1888	{
1889	detail::non_const_lvalue<ConnectHandler> handler2(handler);
1890	self_->impl_.get_service().async_connect(
1891	self_->impl_.get_implementation(), peer_endpoint,
1892	handler2.value, self_->impl_.get_executor());
1893	}
1894	}
1895
1896	private:
1897	basic_socket* self_;
1898	};
1899
1900	class initiate_async_wait
1901	{
1902	public:
1903	typedef Executor executor_type;
1904
1905	explicit initiate_async_wait(basic_socket* self)
1906	: self_(self)
1907	{
1908	}
1909
1910	const executor_type& get_executor() const noexcept
1911	{
1912	return self_->get_executor();
1913	}
1914
1915	template <typename WaitHandler>
1916	void operator()(WaitHandler&& handler, wait_type w) const
1917	{
1918	// If you get an error on the following line it means that your handler
1919	// does not meet the documented type requirements for a WaitHandler.
1920	BOOST_ASIO_WAIT_HANDLER_CHECK(WaitHandler, handler) type_check;
1921
1922	detail::non_const_lvalue<WaitHandler> handler2(handler);
1923	self_->impl_.get_service().async_wait(
1924	self_->impl_.get_implementation(), w,
1925	handler2.value, self_->impl_.get_executor());
1926	}
1927
1928	private:
1929	basic_socket* self_;
1930	};
1931	};
1932
1933	} // namespace asio
1934	} // namespace boost
1935
1936	#include <boost/asio/detail/pop_options.hpp>
1937
1938	#endif // BOOST_ASIO_BASIC_SOCKET_HPP
1939