[#Sock]
= Sock
:mrdocs:

RAII helper class that manages a socket and closes it automatically when it goes out of scope.

== Synopsis

Declared in `<util/sock.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Sock;
----

== Types

[cols="1,4"]
|===
| Name| Description
| xref:Sock/EqualSharedPtrSock.adoc[`EqualSharedPtrSock`] 
| Equality comparator for `shared_ptr<const Sock>` based on the underlying socket descriptor.
| xref:Sock/Events.adoc[`Events`] 
| Auxiliary requested/occurred events to wait for in `WaitMany()`.
| xref:Sock/HashSharedPtrSock.adoc[`HashSharedPtrSock`] 
| Hasher for a `shared_ptr<const Sock>` keyed on the underlying socket descriptor.
|===


== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:Sock/Event.adoc[`Event`] 
| Bitmask type for the I/O readiness events passed to and returned from `Wait()`/`WaitMany()`.
| xref:Sock/EventsPerSock.adoc[`EventsPerSock`] 
| On which socket to wait for what events in `WaitMany()`. The `shared_ptr` is copied into the map to ensure that the `Sock` object is not destroyed (its destructor would close the underlying socket). If this happens shortly before or after we call `poll(2)` and a new socket gets created under the same file descriptor number then the report from `WaitMany()` will be bogus.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:Sock/2constructor-07.adoc[`Sock`]         [.small]#[constructor]#
| Constructors
| xref:Sock/2destructor.adoc[`~Sock`] [.small]#[destructor]# [.small]#[virtual]#
| Destructor, close the socket or do nothing if empty.
| xref:Sock/operator_assign-0e.adoc[`operator=`] 
| Assignment operators
| xref:Sock/Accept.adoc[`Accept`]  [.small]#[virtual]#
| accept(2) wrapper. Equivalent to `std::make_unique<Sock>(accept(m_socket, addr, addr_len))`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation. The returned unique_ptr is empty if `accept()` failed in which case errno will be set.
| xref:Sock/Bind.adoc[`Bind`]  [.small]#[virtual]#
| bind(2) wrapper. Equivalent to `bind(m_socket, addr, addr_len)`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/Connect.adoc[`Connect`]  [.small]#[virtual]#
| connect(2) wrapper. Equivalent to `connect(m_socket, addr, addrlen)`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/GetSockName.adoc[`GetSockName`]  [.small]#[virtual]#
| getsockname(2) wrapper. Equivalent to `getsockname(m_socket, name, name_len)`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/GetSockOpt.adoc[`GetSockOpt`]  [.small]#[virtual]#
| getsockopt(2) wrapper. Equivalent to `getsockopt(m_socket, level, opt_name, opt_val, opt_len)`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/IsConnected.adoc[`IsConnected`]  [.small]#[virtual]#
| Check if still connected.
| xref:Sock/IsSelectable.adoc[`IsSelectable`]  [.small]#[virtual]#
| Check if the underlying socket can be used for `select(2)` (or the `Wait()` method).
| xref:Sock/Listen.adoc[`Listen`]  [.small]#[virtual]#
| listen(2) wrapper. Equivalent to `listen(m_socket, backlog)`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/Recv.adoc[`Recv`]  [.small]#[virtual]#
| recv(2) wrapper. Equivalent to `recv(m_socket, buf, len, flags);`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/RecvUntilTerminator.adoc[`RecvUntilTerminator`]  [.small]#[virtual]#
| Read from socket until a terminator character is encountered. Will never consume bytes past the terminator from the socket.
| xref:Sock/Send.adoc[`Send`]  [.small]#[virtual]#
| send(2) wrapper. Equivalent to `send(m_socket, data, len, flags);`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/SendComplete-0bd3.adoc[`SendComplete`] 
| `SendComplete` overloads
| xref:Sock/SetNonBlocking.adoc[`SetNonBlocking`]  [.small]#[virtual]#
| Set the non‐blocking option on the socket.
| xref:Sock/SetSockOpt.adoc[`SetSockOpt`]  [.small]#[virtual]#
| setsockopt(2) wrapper. Equivalent to `setsockopt(m_socket, level, opt_name, opt_val, opt_len)`. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.
| xref:Sock/Wait.adoc[`Wait`]  [.small]#[virtual]#
| Wait for readiness for input (recv) or output (send).
| xref:Sock/WaitMany.adoc[`WaitMany`]  [.small]#[virtual]#
| Same as `Wait()`, but wait on many sockets within the same timeout.
| xref:Sock/operator_eq.adoc[`operator==`] 
| Check if the internal socket is equal to `s`. Use only in tests.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:Sock/ErrorEvent.adoc[`ErrorEvent`] 
| Ignored if passed to `Wait()`, but could be set in the occurred events if an exceptional condition has occurred on the socket or if it has been disconnected.
| xref:Sock/RecvEvent.adoc[`RecvEvent`] 
| If passed to `Wait()`, then it will wait for readiness to read from the socket.
| xref:Sock/SendEvent.adoc[`SendEvent`] 
| If passed to `Wait()`, then it will wait for readiness to send to the socket.
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:Sock/m_socket.adoc[`m_socket`] 
| Contained socket. `INVALID_SOCKET` designates the object is empty.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:ConnectDirectly-0c.adoc[`ConnectDirectly`]
| Create a socket and try to connect to the specified service, using the provided timeout.
| xref:ConnectDirectly-0e.adoc[`ConnectDirectly`]
| Create a socket and try to connect to the specified service.
| xref:ConnectThroughProxy.adoc[`ConnectThroughProxy`]
| Connect to a specified destination service through a SOCKS5 proxy by first connecting to the SOCKS5 proxy.
| xref:CreateSockOS.adoc[`CreateSockOS`]
| Create a real socket from the operating system.
| xref:GetBindAddress.adoc[`GetBindAddress`]
| Get the bind address for a socket as CService.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#