Skip to content

Commit

Permalink
clarify documentation of flags parameter
Browse files Browse the repository at this point in the history
  • Loading branch information
@obiltschnig
obiltschnig committed Feb 8, 2020
1 parent 58e4839 commit 137c6ad
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 19 deletions.
41 changes: 37 additions & 4 deletions Net/include/Poco/Net/DatagramSocket.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ class Net_API DatagramSocket: public Socket
///
/// Releases the socket's SocketImpl and
/// attaches the SocketImpl from the other socket and
/// increments the reference count of the SocketImpl.
/// increments the reference count of the SocketImpl.

void connect(const SocketAddress& address);
/// Restricts incoming and outgoing
Expand All @@ -81,7 +81,7 @@ class Net_API DatagramSocket: public Socket
/// Bind a local address to the socket.
///
/// This is usually only done when establishing a server
/// socket.
/// socket.
///
/// If reuseAddress is true, sets the SO_REUSEADDR
/// socket option.
Expand All @@ -92,7 +92,7 @@ class Net_API DatagramSocket: public Socket
/// Bind a local address to the socket.
///
/// This is usually only done when establishing a server
/// socket.
/// socket.
///
/// If reuseAddress is true, sets the SO_REUSEADDR
/// socket option.
Expand All @@ -108,50 +108,74 @@ class Net_API DatagramSocket: public Socket
///
/// Returns the number of bytes sent, which may be
/// less than the number of bytes specified.
///
/// The flags parameter can be used to pass system-defined flags
/// for send() like MSG_DONTROUTE.

int sendBytes(const SocketBufVec& buffer, int flags = 0);
/// Sends the contents of the given buffers through
/// the socket.
///
/// Returns the number of bytes sent, which may be
/// less than the number of bytes specified.
///
/// The flags parameter can be used to pass system-defined flags
/// for send() like MSG_DONTROUTE.

int receiveBytes(void* buffer, int length, int flags = 0);
/// Receives data from the socket and stores it
/// in buffer. Up to length bytes are received.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recv() like MSG_PEEK.

int receiveBytes(SocketBufVec& buffer, int flags = 0);
/// Receives data from the socket and stores it in buffers.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recv() like MSG_PEEK.

int receiveBytes(Poco::Buffer<char>& buffer, int flags = 0, const Poco::Timespan& timeout = 100000);
/// Receives data from the socket and stores it in buffers.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recv() like MSG_PEEK.

int sendTo(const void* buffer, int length, const SocketAddress& address, int flags = 0);
/// Sends the contents of the given buffer through
/// the socket to the given address.
///
/// Returns the number of bytes sent, which may be
/// less than the number of bytes specified.
///
/// The flags parameter can be used to pass system-defined flags
/// for sendto() like MSG_DONTROUTE.

int sendTo(const SocketBufVec& buffers, const SocketAddress& address, int flags = 0);
/// Sends the contents of the given buffers through
/// the socket to the given address.
///
/// Returns the number of bytes sent, which may be
/// less than the number of bytes specified.
///
/// The flags parameter can be used to pass system-defined flags
/// for sendto() like MSG_DONTROUTE.

int receiveFrom(void* buffer, int length, SocketAddress& address, int flags = 0);
/// Receives data from the socket and stores it
/// in buffer. Up to length bytes are received.
/// Stores the address of the sender in address.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recvfrom() like MSG_PEEK.

int receiveFrom(void* buffer, int length, struct sockaddr** ppSA, poco_socklen_t** ppSALen, int flags = 0);
/// Receives data from the socket and stores it
Expand All @@ -160,6 +184,9 @@ class Net_API DatagramSocket: public Socket
/// ppSA, and the length of native address in ppSALen.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recvfrom() like MSG_PEEK.

int receiveFrom(SocketBufVec& buffers, SocketAddress& address, int flags = 0);
/// Receives data from the socket and stores it
Expand All @@ -168,6 +195,9 @@ class Net_API DatagramSocket: public Socket
/// Stores the address of the sender in address.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recvfrom() like MSG_PEEK.

int receiveFrom(SocketBufVec& buffers, struct sockaddr** ppSA, poco_socklen_t** ppSALen, int flags = 0);
/// Receives data from the socket and stores it
Expand All @@ -176,13 +206,16 @@ class Net_API DatagramSocket: public Socket
/// ppSA, and the length of native address in ppSALen.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recvfrom() like MSG_PEEK.

void setBroadcast(bool flag);
/// Sets the value of the SO_BROADCAST socket option.
///
/// Setting this flag allows sending datagrams to
/// the broadcast address.

bool getBroadcast() const;
/// Returns the value of the SO_BROADCAST socket option.

Expand Down
48 changes: 33 additions & 15 deletions Net/include/Poco/Net/StreamSocket.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ class Net_API StreamSocket: public Socket
/// for the given address family.
///
/// This is useful if certain socket options
/// (like send and receive buffer) sizes, that must
/// (like send and receive buffer) sizes, that must
/// be set before connecting the socket, will be
/// set later on.

Expand All @@ -68,35 +68,35 @@ class Net_API StreamSocket: public Socket
///
/// Releases the socket's SocketImpl and
/// attaches the SocketImpl from the other socket and
/// increments the reference count of the SocketImpl.
/// increments the reference count of the SocketImpl.

void connect(const SocketAddress& address);
/// Initializes the socket and establishes a connection to
/// Initializes the socket and establishes a connection to
/// the TCP server at the given address.
///
/// Can also be used for UDP sockets. In this case, no
/// connection is established. Instead, incoming and outgoing
/// packets are restricted to the specified address.

void connect(const SocketAddress& address, const Poco::Timespan& timeout);
/// Initializes the socket, sets the socket timeout and
/// Initializes the socket, sets the socket timeout and
/// establishes a connection to the TCP server at the given address.

void connectNB(const SocketAddress& address);
/// Initializes the socket and establishes a connection to
/// Initializes the socket and establishes a connection to
/// the TCP server at the given address. Prior to opening the
/// connection the socket is set to nonblocking mode.

void shutdownReceive();
/// Shuts down the receiving part of the socket connection.

void shutdownSend();
/// Shuts down the sending part of the socket connection.

void shutdown();
/// Shuts down both the receiving and the sending part
/// of the socket connection.

int sendBytes(const void* buffer, int length, int flags = 0);
/// Sends the contents of the given buffer through
/// the socket.
Expand All @@ -106,13 +106,19 @@ class Net_API StreamSocket: public Socket
///
/// Certain socket implementations may also return a negative
/// value denoting a certain condition.
///
/// The flags parameter can be used to pass system-defined flags
/// for send() like MSG_OOB.

int sendBytes(const SocketBufVec& buffer, int flags = 0);
/// Sends the contents of the given buffers through
/// the socket.
///
/// Returns the number of bytes sent, which may be
/// less than the number of bytes specified.
///
/// The flags parameter can be used to pass system-defined flags
/// for send() like MSG_OOB.

int sendBytes(Poco::FIFOBuffer& buffer);
/// Sends the contents of the given buffer through
Expand All @@ -126,38 +132,50 @@ class Net_API StreamSocket: public Socket
///
/// Certain socket implementations may also return a negative
/// value denoting a certain condition.
///
/// The flags parameter can be used to pass system-defined flags
/// for send() like MSG_OOB.

int receiveBytes(void* buffer, int length, int flags = 0);
/// Receives data from the socket and stores it
/// in buffer. Up to length bytes are received.
///
/// Returns the number of bytes received.
/// A return value of 0 means a graceful shutdown
/// Returns the number of bytes received.
/// A return value of 0 means a graceful shutdown
/// of the connection from the peer.
///
/// Throws a TimeoutException if a receive timeout has
/// been set and nothing is received within that interval.
/// Throws a NetException (or a subclass) in case of other errors.
///
/// The flags parameter can be used to pass system-defined flags
/// for recv() like MSG_OOB, MSG_PEEK or MSG_WAITALL.

int receiveBytes(SocketBufVec& buffer, int flags = 0);
/// Receives data from the socket and stores it in buffers.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recv() like MSG_OOB, MSG_PEEK or MSG_WAITALL.

int receiveBytes(Poco::Buffer<char>& buffer, int flags = 0, const Poco::Timespan& timeout = 100000);
/// Receives data from the socket and stores it in buffers.
///
/// Returns the number of bytes received.
///
/// The flags parameter can be used to pass system-defined flags
/// for recv() like MSG_OOB, MSG_PEEK or MSG_WAITALL.

int receiveBytes(Poco::FIFOBuffer& buffer);
/// Receives data from the socket and stores it
/// in buffer. Up to length bytes are received. FIFOBuffer has
/// writable/readable transition notifications which may be enabled
/// to notify the caller when the buffer transitions between empty,
/// in buffer. Up to length bytes are received. FIFOBuffer has
/// writable/readable transition notifications which may be enabled
/// to notify the caller when the buffer transitions between empty,
/// partially full and full states.
///
/// Returns the number of bytes received.
/// A return value of 0 means a graceful shutdown
/// Returns the number of bytes received.
/// A return value of 0 means a graceful shutdown
/// of the connection from the peer.
///
/// Throws a TimeoutException if a receive timeout has
Expand Down

0 comments on commit 137c6ad

Please sign in to comment.