Unix datagram socket class.
More...
#include <simple_socket/UnixDatagramSocket.h>
|
| | UnixDatagramSocket () |
| IOResult | sendTo (const void *buffer, size_t len, std::string_view foreignPath) |
| IOResult | receiveFrom (void *buffer, size_t len, std::string &sourcePath) |
| IOResult | timedReceiveFrom (void *buffer, size_t len, std::string &sourcePath, int timeout) |
| ConnectResult | connect (std::string_view foreignPath) |
| void | bind (std::string_view localPath) |
| std::string | getLocalPath () const |
| std::string | getForeignPath () const |
| PeerCredentials | peerCredentials () const |
| int | nativeHandle () noexcept |
| | Return the native descriptor. Ownership remains with the object.
|
| int | duplicateNativeHandle () const |
| | Duplicates the underlaying native socket descriptor.
|
| bool | valid () const noexcept |
| | Returns true if socket is in a usable (non-moved) state and open.
|
| IOResult | send (const void *buffer, size_t len) |
| | send data through a connected socket
|
| IOResult | receive (void *buffer, size_t len) |
| | receive data from a bound socket
|
| IOResult | timedReceive (void *buffer, size_t len, int timeout) |
| | receive data from a bound socket, return after the given timespan
|
| void | disconnect () |
| | Disconnect and unset any foreign addresses.
|
| bool | isConnected () const |
| | check if the kernel currently has an associated peer address
|
| void | shutdown (ShutdownDirection type) |
| | shutdown the connection in the specified direction
|
| bool | peerDisconnected () const |
| | returns whether a currently associated peer disconnected
|
| bool | isBlocking () const |
| | returns true if socket is in blocking mode
|
| void | setBlocking (bool blocking) |
| | set socket to blocking or non-blocking I/O operations
|
| void | setSendBufferSize (int bytes) |
| | override default send buffer size for this socket
|
| void | setReceiveBufferSize (int bytes) |
| | override default receive buffer size for this socket
|
|
| | UnixSocket (int type, int protocol) |
| | allows a subclass to create new socket
|
| | UnixSocket (AdoptSocketTag, int sockfd, int type) |
| | allows a subclass to take ownership of an existing socket
|
| | UnixSocket (UnixSocket &&other) noexcept |
| void | listen (int backlog=128) |
| | listen for incoming connections
|
| ConnectResult | finishConnect (int timeout=0) |
| | check if a previously started connected attempt is finished
|
| IOResult | sendAll (const void *buffer, size_t len) |
| | send data through a connected socket
|
| IOResult | receiveAll (void *buffer, size_t len) |
| | receive exactly the requested amount unless the peer disconnects
|
Unix datagram socket class.
Definition at line 9 of file UnixDatagramSocket.h.
◆ UnixDatagramSocket()
| NET::UnixDatagramSocket::UnixDatagramSocket |
( |
| ) |
|
Construct a Unix datagram socket
- Exceptions
-
◆ adoptNativeHandle()
Take ownership of an existing native Unix datagram socket descriptor.
This is intended for sockets created outside simple-socket, for example listening sockets supplied through systemd socket activation.
The descriptor must refer to an an AF_UNIX SOCK_DGRAM socket. On success ownership is transferred to the returned object and the descriptor will be closed when that object is destroyed.
An adopted socket does not claim ownership of its filesystem path.
- Parameters
-
| sockfd | native socket descriptor to adopt |
- Returns
- UnixDatagramSocket owning sockfd
- Exceptions
-
◆ bind()
| void NET::UnixSocket::bind |
( |
std::string_view | localPath | ) |
|
|
inherited |
Set the local path to the specified path
- Parameters
-
| localPath | specifies where the socket should be bound |
- Exceptions
-
◆ connect()
| ConnectResult NET::UnixSocket::connect |
( |
std::string_view | foreignPath | ) |
|
|
inherited |
Establish a socket connection with the given socket
- Parameters
-
| foreignPath | the path of the remote socket |
- Returns
- ConnectResult
- Exceptions
-
◆ createPair()
Construct a connected pair of Unix sockets in the given mode
- Exceptions
-
◆ disconnect()
| void NET::SimpleSocket::disconnect |
( |
| ) |
|
|
inherited |
Disconnect and unset any foreign addresses.
This will ungracefully abort the connection by sending an RST frame. disconnect() should not be used under normal circumstances, as it will terminate the connection OOB, preventing the other end of the communication from retrieving data that would still be available in the OS buffer.
For normal termination of a connection use shutdown().
- Exceptions
-
◆ duplicateNativeHandle()
| int NET::SimpleSocket::duplicateNativeHandle |
( |
| ) |
const |
|
nodiscardinherited |
Duplicates the underlaying native socket descriptor.
◆ finishConnect()
| ConnectResult NET::SimpleSocket::finishConnect |
( |
int | timeout = 0 | ) |
|
|
protectedinherited |
check if a previously started connected attempt is finished
Use this to check if a non-blocking connect() call has completed.
- Parameters
-
| timeout | the timeout in ms after which we stop waiting, connection is still active |
- Exceptions
-
◆ getForeignPath()
| std::string NET::UnixSocket::getForeignPath |
( |
| ) |
const |
|
inherited |
Get the foreign path. Call connect() before using this function.
- Returns
- foreign path or empty string when not connected
- Exceptions
-
◆ getLocalPath()
| std::string NET::UnixSocket::getLocalPath |
( |
| ) |
const |
|
inherited |
Get the local path (after binding the socket)
- Returns
- local path of socket
- Exceptions
-
◆ isBlocking()
| bool NET::SimpleSocket::isBlocking |
( |
| ) |
const |
|
nodiscardinherited |
returns true if socket is in blocking mode
◆ isConnected()
| bool NET::SimpleSocket::isConnected |
( |
| ) |
const |
|
nodiscardinherited |
check if the kernel currently has an associated peer address
For stream sockets, true means a peer association exists; it does not guarantee that the remote endpoint is alive or that I/O can succeed. A peer that has sent FIN may still be associated with the socket.
For datagram sockets, true only indicates that connect() configured a default peer address; it does not establish a network connection.
- Returns
- false if getpeername() reports ENOTCONN
- Exceptions
-
◆ listen()
| void NET::SimpleSocket::listen |
( |
int | backlog = 128 | ) |
|
|
protectedinherited |
listen for incoming connections
listen() can be called on a bound socket. The socket will then go into a passive state and accept incoming connections. To answer to an incoming connection call accept() or timedAccept() on the socket.
The backlog specifies the maximum requested number of pending connections waiting to be accepted.
- Parameters
-
| backlog | requested pending connection queue size |
- Exceptions
-
◆ nativeHandle()
| int NET::SimpleSocket::nativeHandle |
( |
| ) |
|
|
inlinenoexceptinherited |
Return the native descriptor. Ownership remains with the object.
Definition at line 128 of file SimpleSocket.h.
◆ peerCredentials()
Returns the credentials of the peer process connected to this socket.
- Exceptions
-
◆ peerDisconnected()
| bool NET::SimpleSocket::peerDisconnected |
( |
| ) |
const |
|
nodiscardinherited |
returns whether a currently associated peer disconnected
Returns whether the OS currently reports hangup or error for the stream peer. A false result does not guarantee that the remote peer is reachable.
- Returns
- true if a peer disconnected or is no longer connected
◆ receive()
| IOResult NET::SimpleSocket::receive |
( |
void * | buffer, |
|
|
size_t | len ) |
|
inherited |
receive data from a bound socket
receive() can only be used on a socket that called bind() or connect() before. If you try to use receive() on a not bound socket, SocketException will be thrown.
If using a stream oriented Socket, receive can return a part of a received messge, e.g. if you send 100 bytes, it's possible you will receive 50 bytes two times in a row. However, the order of the sent data will be preserved.
If you are using a datagram oriented sockets, you will only receive whole datagrams. But beware of using a too small buffer. If the receive buffer is too small for the received datagram, the data you didn't read in the receive call will be discared.
If the remote host has closed the connection (on a connection based socket like TCP) receive() will return PeerDisconnected in the result status. If you are using a connectionless protocol (like UDP) you may get DestinationUnavailable in the result status when the peer refuses via ICMP.
- Parameters
-
| buffer | the buffer the received data will be written to |
| len | length of the provided buffer, receive will not read more than that |
- Returns
- IOResult
- Exceptions
-
◆ receiveAll()
| IOResult NET::SimpleSocket::receiveAll |
( |
void * | buffer, |
|
|
size_t | len ) |
|
protectedinherited |
receive exactly the requested amount unless the peer disconnects
receiveAll() repeatedly calls receive() until len bytes have been received. This is useful for fixed-size data on TCP, where one receive() call is not guaranteed to return all bytes sent by the peer.
If the peer closes or resets the connection before len bytes arrive, the function returns an error status with the number of bytes received so far.
- Parameters
-
| buffer | buffer the received data will be written to |
| len | number of bytes to receive |
- Returns
- IOResult
- Exceptions
-
◆ receiveFrom()
| IOResult NET::UnixDatagramSocket::receiveFrom |
( |
void * | buffer, |
|
|
size_t | len, |
|
|
std::string & | sourcePath ) |
Read read up to len bytes data from this socket. The given buffer is where the data will be placed.
- Parameters
-
| buffer | buffer to receive data |
| len | maximum number of bytes to receive |
| sourcePath | path where the data originated |
- Returns
- IOResult
- Exceptions
-
◆ send()
| IOResult NET::SimpleSocket::send |
( |
const void * | buffer, |
|
|
size_t | len ) |
|
inherited |
send data through a connected socket
send() can only be used on a socket that called connect() before. If you try to use send() on a not connected socket, SocketException will be thrown.
If you are using a stream oriented socket (like TCPSocket), the operating system is allowed to send only a part of the packet you told it to send, so send() will return the number of bytes actually sent. It is your responsibility to resend the data not sent by send()
If you are using a datagram oriented socket (like UDPSocket or SCTPSocket) the operating system will only send and receive complete datagrams, but send() will fail if you are trying to send too much data. In that case SocketException will be thrown.
- Parameters
-
| buffer | data to be send |
| len | length of the data to be sent |
- Returns
- IOResult
- Exceptions
-
◆ sendAll()
| IOResult NET::SimpleSocket::sendAll |
( |
const void * | buffer, |
|
|
size_t | len ) |
|
protectedinherited |
send data through a connected socket
sendAll() can only be used on a socket that called connect() before. If you try to use sendAll() on a unconnected socket, a SocketException will be thrown.
When using a stream oriented socket, the operating system is allowed to send only a part of the data you requested it to send. Because of this, you would have to check the number of sent bytes when using send(), and resend unsent data manually. sendAll() takes that responsibility from you and resends as long as it needs, to completely send the data given to it.
- Parameters
-
| buffer | data to be send |
| len | length of the data to be sent |
- Returns
- IOResult
- Exceptions
-
◆ sendTo()
| IOResult NET::UnixDatagramSocket::sendTo |
( |
const void * | buffer, |
|
|
size_t | len, |
|
|
std::string_view | foreignPath ) |
Send the given buffer as a datagram to the specified address / port.
- Parameters
-
| buffer | data to be send |
| len | number of bytes to write |
| foreignPath | filename of the datagram socket the data should be sent to |
- Returns
- IOResult
- Exceptions
-
◆ setBlocking()
| void NET::SimpleSocket::setBlocking |
( |
bool | blocking | ) |
|
|
inherited |
set socket to blocking or non-blocking I/O operations
A non-blocking socket will return from all I/O operations right away. The IOStatus WouldBlock is used to signify no work can be done at the moment. An event handler can use poll(), epoll(), etc. to monitor the socket for readyness for the next operation.
All timed operations provided by socket classes are not affected. Timed calls wait up to timeout ms for even with non-blocking sockets.
◆ setReceiveBufferSize()
| void NET::SimpleSocket::setReceiveBufferSize |
( |
int | bytes | ) |
|
|
inherited |
override default receive buffer size for this socket
◆ setSendBufferSize()
| void NET::SimpleSocket::setSendBufferSize |
( |
int | bytes | ) |
|
|
inherited |
override default send buffer size for this socket
◆ shutdown()
shutdown the connection in the specified direction
This will gracefully end a connection by sending a FIN frame. Use this to end a normal communication cycle. To abort a connection see disconnect().
Depending on the specified ShutdownDirection, calls for that direction will stop working. Use this function if you want to have more control than just destroing the socket. It allows you to cut the connection in one direction, or both.
If you use shutdown() on an unconnected socket, the corresponding calls will simply stop working.
- Parameters
-
- Exceptions
-
- Examples
- TCP_Server.cpp.
◆ timedReceive()
| IOResult NET::SimpleSocket::timedReceive |
( |
void * | buffer, |
|
|
size_t | len, |
|
|
int | timeout ) |
|
inherited |
receive data from a bound socket, return after the given timespan
timedReceive() can only be used on a socket that called bind() or connect before. If you try to use receive() on a not bound socket, SocketException will be thrown.
If using a stream oriented Socket, receive can return a part of a received messge, e.g. if you send 100 bytes, it's possible you will receive 50 bytes two times in a row. However, the order of the sent data will be preserved.
If you are using a datagram oriented sockets, you will only receive whole datagrams. But beware of using a too small buffer. If the receive buffer is too small for the received datagram, the data you didn't read in the receive call will be discared.
If the remote host has closed the connection (on a connection based socket like TCP) receive() will return PeerDisconnected in the result status. If you are using a connectionless protocol (like UDP) you may get DestinationUnavailable in the result status when the peer refuses via ICMP.
- Parameters
-
| buffer | the buffer the received data will be written to |
| len | length of the provided buffer, receive will not read more than that |
| timeout | the timeout in ms after which receive will give up and return |
- Returns
- IOResult
- Exceptions
-
- Examples
- TCP_Client.cpp, and TCP_Client_Reconnect.cpp.
◆ timedReceiveFrom()
| IOResult NET::UnixDatagramSocket::timedReceiveFrom |
( |
void * | buffer, |
|
|
size_t | len, |
|
|
std::string & | sourcePath, |
|
|
int | timeout ) |
Read read up to len bytes data from this socket. The given buffer is where the data will be placed. If no host has sent a datagram before the timeout runs out, the function will return without changing the buffer.
- Parameters
-
| buffer | buffer to receive data |
| len | maximum number of bytes to receive |
| sourcePath | path where the data originated |
| timeout | timeout in milliseconds |
- Returns
- IOResult
- Exceptions
-
◆ UnixSocket() [1/3]
allows a subclass to take ownership of an existing socket
◆ UnixSocket() [2/3]
allows a subclass to create new socket
◆ UnixSocket() [3/3]
◆ valid()
| bool NET::SimpleSocket::valid |
( |
| ) |
const |
|
noexceptinherited |
Returns true if socket is in a usable (non-moved) state and open.
◆ m_boundPath
| std::string NET::UnixSocket::m_boundPath |
|
protectedinherited |
◆ m_connectionOriented
| bool NET::SimpleSocket::m_connectionOriented |
|
protectedinherited |
◆ m_socket
| int NET::SimpleSocket::m_socket |
|
protectedinherited |
The documentation for this class was generated from the following file: