diff --git a/features/netsocket/UDPSocket.h b/features/netsocket/UDPSocket.h index 087bb8932d..71e7e4a6e3 100644 --- a/features/netsocket/UDPSocket.h +++ b/features/netsocket/UDPSocket.h @@ -26,22 +26,21 @@ #include "rtos/EventFlags.h" -/** UDP socket +/** UDP socket implementation. */ class UDPSocket : public InternetSocket { public: - /** Create an uninitialized socket + /** Create an uninitialized socket. * - * Must call open to initialize the socket on a network stack. + * @note Must call open to initialize the socket on a network stack. */ UDPSocket(); - /** Create a socket on a network interface - * - * Creates and opens a socket on the network stack of the given + /** Create and open a socket on the network stack of the given * network interface. * - * @param stack Network stack as target for socket + * @tparam S Type of the Network stack. + * @param stack Network stack as target for socket. */ template UDPSocket(S *stack) @@ -49,96 +48,84 @@ public: open(stack); } - /** Destroy a socket + /** Destroy a socket. * - * Closes socket if the socket is still open + * @note Closes socket if the socket is still open. */ virtual ~UDPSocket(); - /** Send a packet over a UDP socket - * - * Sends data to the specified address specified by either a domain name - * or an IP address and port. Returns the number of bytes sent from the - * buffer. + /** Send data to the specified host and port. * * By default, sendto blocks until data is sent. If socket is set to * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned * immediately. * - * @param host Hostname of the remote host - * @param port Port of the remote host - * @param data Buffer of data to send to the host - * @param size Size of the buffer in bytes + * @param host Domain name of the remote host or a dotted notation IP address. + * @param port Port of the remote host. + * @param data Buffer of data to send to the host. + * @param size Size of the buffer in bytes. * @return Number of sent bytes on success, negative error - * code on failure + * code on failure. */ virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port, const void *data, nsapi_size_t size); - /** Send a packet over a UDP socket - * - * Sends data to the specified address. Returns the number of bytes - * sent from the buffer. + /** Send data to the specified address. * * By default, sendto blocks until data is sent. If socket is set to * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned * immediately. * - * @param address The SocketAddress of the remote host - * @param data Buffer of data to send to the host - * @param size Size of the buffer in bytes + * @param address The SocketAddress of the remote host. + * @param data Buffer of data to send to the host. + * @param size Size of the buffer in bytes. * @return Number of sent bytes on success, negative error - * code on failure + * code on failure. */ virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size); - /** Receive a datagram over a UDP socket - * - * Receives a datagram and stores the source address in address if address - * is not NULL. Returns the number of bytes written into the buffer. If the - * datagram is larger than the buffer, the excess data is silently discarded. - * - * If socket is connected, only packets coming from connected peer address - * are accepted. - * - * @note recvfrom() is allowed write to address and data buffers even if error occurs. + /** Receive a datagram and store the source address in address if it's not NULL. * * By default, recvfrom blocks until a datagram is received. If socket is set to * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK * is returned. * - * @param address Destination for the source address or NULL - * @param data Destination buffer for datagram received from the host - * @param size Size of the buffer in bytes + * @note If the datagram is larger than the buffer, the excess data is silently discarded. + * + * @note If socket is connected, only packets coming from connected peer address + * are accepted. + * + * @note recvfrom() is allowed write to address and data buffers even if error occurs. + * + * @param address Destination for the source address or NULL. + * @param data Destination buffer for datagram received from the host. + * @param size Size of the buffer in bytes. * @return Number of received bytes on success, negative error - * code on failure + * code on failure. */ virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size); - /** Set remote peer address - * - * Set the remote address for next send() call and filtering - * for incomming packets. To reset the address, zero initialised + /** Set the remote address for next send() call and filtering + * of incoming packets. To reset the address, zero initialised * SocketAddress must be in the address parameter. * - * @param address The SocketAddress of the remote host - * @return 0 on success, negative error code on failure + * @param address The SocketAddress of the remote host. + * @return 0 on success, negative error code on failure. */ virtual nsapi_error_t connect(const SocketAddress &address); - /** Send a datagram to pre-specified remote. - * - * The socket must be connected to a remote host before send() call. - * Returns the number of bytes sent from the buffer. + /** Send a datagram to connected remote address. * * By default, send blocks until all data is sent. If socket is set to * non-blocking or times out, a partial amount can be written. * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written. * - * @param data Buffer of data to send to the host - * @param size Size of the buffer in bytes + * @note The socket must be connected to a remote host before send() call. + * + * @param data Buffer of data to send to the host. + * @param size Size of the buffer in bytes. * @return Number of sent bytes on success, negative error * code on failure. */ @@ -151,35 +138,39 @@ public: * If socket is connected, only packets coming from connected peer address * are accepted. * - * @note recv() is allowed write to data buffer even if error occurs. - * * By default, recv blocks until some data is received. If socket is set to * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to * indicate no data. * - * @param data Destination buffer for data received from the host - * @param size Size of the buffer in bytes + * @note recv() is allowed write to data buffer even if error occurs. + * + * @param data Pointer to buffer for data received from the host. + * @param size Size of the buffer in bytes. * @return Number of received bytes on success, negative error * code on failure. */ virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size); - /** Not implemented for UDP + /** Not implemented for UDP. * - * @param error unused + * @param error Not used. * @return NSAPI_ERROR_UNSUPPORTED */ virtual Socket *accept(nsapi_error_t *error = NULL); - /** Not implemented for UDP + /** Not implemented for UDP. * - * @param backlog unused + * @param backlog Not used. * @return NSAPI_ERROR_UNSUPPORTED */ virtual nsapi_error_t listen(int backlog = 1); +#if !defined(DOXYGEN_ONLY) + protected: virtual nsapi_protocol_t get_proto(); + +#endif //!defined(DOXYGEN_ONLY) };