Skip to content

Docs: InternetSocket doxygen fixes #8534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 27, 2018
Merged

Docs: InternetSocket doxygen fixes #8534

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd0612b
update internetsocket docs
paul-szczepanek-arm Oct 24, 2018
6db0f67
Edit InternetSocket.h
Oct 25, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 74 additions & 84 deletions features/netsocket/InternetSocket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,176 +32,162 @@
*/
class InternetSocket : public Socket {
public:
/** Destroy a socket
/** Destroy the socket.
*
* Closes socket if the socket is still open
* @note Closes socket if it's still open.
*/
virtual ~InternetSocket() {}

/** Opens a socket
/** Open a network socket on the network stack of the given
* network interface.
*
* Creates a network socket on the network stack of the given
* network interface. Not needed if stack is passed to the
* socket's constructor.
* @note Not needed if stack is passed to the socket's constructor.
*
* @param stack Network stack as target for socket
* @return 0 on success, negative error code on failure
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
nsapi_error_t open(NetworkStack *stack);

#if !defined(DOXYGEN_ONLY)
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is just a convenience func for casting

template <typename S>
nsapi_error_t open(S *stack)
{
return open(nsapi_create_stack(stack));
}
#endif //!defined(DOXYGEN_ONLY)

/** Close the socket
*
* Closes any open connection and deallocates any memory associated
/** Close any open connection, and deallocate any memory associated
* with the socket. Called from destructor if socket is not closed.
*
* @return 0 on success, negative error code on failure
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
virtual nsapi_error_t close();

/** Subscribes to an IP multicast group
/** Subscribe to an IP multicast group.
*
* @param address Multicast group IP address
* @return Negative error code on failure
* @param address Multicast group IP address.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
int join_multicast_group(const SocketAddress &address);

/** Leave an IP multicast group
/** Leave an IP multicast group.
*
* @param address Multicast group IP address
* @return Negative error code on failure
* @param address Multicast group IP address.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
int leave_multicast_group(const SocketAddress &address);


/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to receive
* data.
/** Bind the socket to a port on which to receive data.
*
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
* @param port Local port to bind.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
nsapi_error_t bind(uint16_t port);

/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to receive
/** Bind the socket to a specific address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Null-terminated local address to bind
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
* @param address Null-terminated local address to bind.
* @param port Local port to bind.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
nsapi_error_t bind(const char *address, uint16_t port);

/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to receive
/** Bind the socket to a specific address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local address to bind
* @return 0 on success, negative error code on failure.
* @param address Local SocketAddress to bind, which includes the address and port.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
virtual nsapi_error_t bind(const SocketAddress &address);

/** Set blocking or non-blocking mode of the socket
/** Set blocking or nonblocking mode of the socket.
*
* Initially all sockets are in blocking mode. In non-blocking mode
* blocking operations such as send/recv/accept return
* NSAPI_ERROR_WOULD_BLOCK if they can not continue.
* Initially all sockets are in blocking mode. In nonblocking mode,
* blocking operations, such as send/recv/accept, return
* NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
*
* set_blocking(false) is equivalent to set_timeout(-1)
* set_blocking(true) is equivalent to set_timeout(0)
* @note set_blocking(false) is equivalent to set_timeout(-1) and
* set_blocking(true) is equivalent to set_timeout(0).
*
* @param blocking true for blocking mode, false for non-blocking mode.
* @param blocking Use true for blocking mode, false for nonblocking mode.
*/
virtual void set_blocking(bool blocking);

/** Set timeout on blocking socket operations
/** Set timeout on blocking socket operations.
*
* Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
* is returned if a blocking operation takes longer than the specified
* timeout. A timeout of 0 removes the timeout from the socket. A negative
* value give the socket an unbounded timeout.
*
* set_timeout(0) is equivalent to set_blocking(false)
* set_timeout(-1) is equivalent to set_blocking(true)
* @note set_timeout(0) is equivalent to set_blocking(false) and
* set_timeout(-1) is equivalent to set_blocking(true).
*
* @param timeout Timeout in milliseconds
* @param timeout Timeout in milliseconds.
*/
virtual void set_timeout(int timeout);

/* Set socket options
/** Pass stack-specific options to the underlying stack using stack-specific
* level and option names, or request generic options using levels from nsapi_socket_level_t.
*
* setsockopt allows an application to pass stack-specific options
* to the underlying stack using stack-specific level and option names,
* or to request generic options using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned,
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name.
* @param optval Option value.
* @param optlen Length of the option value.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);

/* Get socket options
*
* getsockopt allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names,
* or to request generic options using levels from nsapi_socket_level_t.
/** Retrieve stack-specific options from the underlying stack using
* stack-specific level and option names, or request generic options
* using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned,
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name.
* @param optval Destination for option value.
* @param optlen Length of the option value.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);

/** Register a callback on state change of the socket
/** Register a callback on state change of the socket.
*
* The specified callback will be called on state changes such as when
* the socket can recv/send/accept successfully and on when an error
* occurs. The callback may also be called spuriously without reason.
* The specified callback is called on state changes, such as when
* the socket can recv/send/accept successfully and when an error
* occurs. The callback may also be called spuriously without a reason.
*
* The callback may be called in an interrupt context and should not
* perform expensive operations such as recv/send calls.
* perform expensive operations, such as recv/send calls.
*
* Note! This is not intended as a replacement for a poll or attach-like
* asynchronous api, but rather as a building block for constructing
* @note This is not intended as a replacement for a poll or attach-like
* asynchronous API, but rather as a building block for constructing
* such functionality. The exact timing of when the registered function
* is called is not guaranteed and susceptible to change.
* is called is not guaranteed and is susceptible to change.
*
* @param func Function to call on state change
* @param func Function to call on state change.
*/
virtual void sigio(mbed::Callback<void()> func);

/** Register a callback on state change of the socket
/** Register a callback on state change of the socket.
*
* @see Socket::sigio
* @deprecated
* The behaviour of Socket::attach differs from other attach functions in
* mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
* The behavior of Socket::attach differs from other attach functions in
* Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
*/
MBED_DEPRECATED_SINCE("mbed-os-5.4",
"The behaviour of Socket::attach differs from other attach functions in "
"mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
"The behavior of Socket::attach differs from other attach functions in "
"Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
void attach(mbed::Callback<void()> func);

/** Register a callback on state change of the socket
/** Register a callback on state change of the socket.
*
* @see Socket::sigio
* @deprecated
Expand All @@ -217,6 +203,8 @@ class InternetSocket : public Socket {
attach(mbed::callback(obj, method));
}

#if !defined(DOXYGEN_ONLY)

protected:
InternetSocket();
virtual nsapi_protocol_t get_proto() = 0;
Expand All @@ -240,6 +228,8 @@ class InternetSocket : public Socket {
static const int READ_FLAG = 0x1u;
static const int WRITE_FLAG = 0x2u;
static const int FINISHED_FLAG = 0x3u;

#endif //!defined(DOXYGEN_ONLY)
};

#endif // INTERNETSOCKET_H
Expand Down
4 changes: 2 additions & 2 deletions features/netsocket/Socket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ class Socket {
*/
virtual void sigio(mbed::Callback<void()> func) = 0;

/* Set socket options.
/** Set socket options.
*
* setsockopt() allows an application to pass stack-specific options
* to the underlying stack using stack-specific level and option names,
Expand All @@ -211,7 +211,7 @@ class Socket {
*/
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;

/* Get socket options.
/** Get socket options.
*
* getsockopt() allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names,
Expand Down