ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update internetsocket docs

pull/8534/head
paul-szczepanek-arm 2018-10-24 16:50:35 +01:00
parent ba23fef90b
commit fd0612b763
2 changed files with 66 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
features/netsocket/InternetSocket.h
View File

@ -32,164 +32,150 @@
*/ */
class InternetSocket : public Socket { class InternetSocket : public Socket {
public: 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() {} 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 * @note Not needed if stack is passed to the socket's constructor.
* network interface. Not needed if stack is passed to the
* socket's constructor.
* *
* @param stack Network stack as target for socket * @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure * @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/ */
nsapi_error_t open(NetworkStack *stack); nsapi_error_t open(NetworkStack *stack);
#if !defined(DOXYGEN_ONLY)
template <typename S> template <typename S>
nsapi_error_t open(S *stack) nsapi_error_t open(S *stack)
{ {
return open(nsapi_create_stack(stack)); return open(nsapi_create_stack(stack));
} }
#endif //!defined(DOXYGEN_ONLY)
/** Close the socket /** Close any open connection and deallocate any memory associated
*
* Closes any open connection and deallocates any memory associated
* with the socket. Called from destructor if socket is not closed. * 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(); virtual nsapi_error_t close();
/** Subscribes to an IP multicast group /** Subscribe to an IP multicast group.
* *
* @param address Multicast group IP address * @param address Multicast group IP address.
* @return Negative error code on failure * @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/ */
int join_multicast_group(const SocketAddress &address); int join_multicast_group(const SocketAddress &address);
/** Leave an IP multicast group /** Leave an IP multicast group.
* *
* @param address Multicast group IP address * @param address Multicast group IP address.
* @return Negative error code on failure * @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/ */
int leave_multicast_group(const SocketAddress &address); int leave_multicast_group(const SocketAddress &address);
/** Bind the socket to a port on which to receive data.
/** Bind a specific address to a socket
* *
* Binding a socket specifies the address and port on which to receive * @param port Local port to bind.
* data. * @return 0 on success, negative error code on failure (@see nsapi_types.h).
*
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
*/ */
nsapi_error_t bind(uint16_t port); nsapi_error_t bind(uint16_t port);
/** Bind a specific address to a socket /** 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.
* *
* Binding a socket specifies the address and port on which to receive * @param address Null-terminated local address to bind.
* data. If the IP address is zeroed, only the port is bound. * @param port Local port to bind.
* * @return 0 on success, negative error code on failure (@see nsapi_types.h).
* @param address Null-terminated local address to bind
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
*/ */
nsapi_error_t bind(const char *address, uint16_t port); nsapi_error_t bind(const char *address, uint16_t port);
/** Bind a specific address to a socket /** Bind the socket to a specific address and port on which to receive
*
* Binding a socket specifies the address and port on which to receive
* data. If the IP address is zeroed, only the port is bound. * data. If the IP address is zeroed, only the port is bound.
* *
* @param address Local address to bind * @param address Local SocketAddress to bind which includes the address and port.
* @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 bind(const SocketAddress &address); virtual nsapi_error_t bind(const SocketAddress &address);
/** Set blocking or non-blocking mode of the socket /** Set blocking or non-blocking mode of the socket.
* *
* Initially all sockets are in blocking mode. In non-blocking mode * Initially all sockets are in blocking mode. In non-blocking mode
* blocking operations such as send/recv/accept return * blocking operations such as send/recv/accept return
* NSAPI_ERROR_WOULD_BLOCK if they can not continue. * NSAPI_ERROR_WOULD_BLOCK if they can not continue.
* *
* set_blocking(false) is equivalent to set_timeout(-1) * @note set_blocking(false) is equivalent to set_timeout(-1) and
* set_blocking(true) is equivalent to set_timeout(0) * 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 non-blocking mode.
*/ */
virtual void set_blocking(bool blocking); 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 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
* is returned if a blocking operation takes longer than the specified * is returned if a blocking operation takes longer than the specified
* timeout. A timeout of 0 removes the timeout from the socket. A negative * timeout. A timeout of 0 removes the timeout from the socket. A negative
* value give the socket an unbounded timeout. * value give the socket an unbounded timeout.
* *
* set_timeout(0) is equivalent to set_blocking(false) * @note set_timeout(0) is equivalent to set_blocking(false) and
* set_timeout(-1) is equivalent to set_blocking(true) * 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); 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. * and the socket is unmodified.
* *
* @param level Stack-specific protocol level or nsapi_socket_level_t * @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name * @param optname Level-specific option name.
* @param optval Option value * @param optval Option value.
* @param optlen Length of the option value * @param optlen Length of the option value.
* @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 setsockopt(int level, int optname, const void *optval, unsigned optlen); virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
/* Get socket options /** Retrieve stack-specific options from the underlying stack using
* * stack-specific level and option names, or request generic options
* getsockopt allows an application to retrieve stack-specific options * using levels from nsapi_socket_level_t.
* from 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. * and the socket is unmodified.
* *
* @param level Stack-specific protocol level or nsapi_socket_level_t * @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name * @param optname Level-specific option name.
* @param optval Destination for option value * @param optval Destination for option value.
* @param optlen Length of the option value * @param optlen Length of the option value.
* @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 getsockopt(int level, int optname, void *optval, unsigned *optlen); 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 specified callback will be called on state changes such as when
* the socket can recv/send/accept successfully and on when an error * the socket can recv/send/accept successfully and when an error
* occurs. The callback may also be called spuriously without reason. * occurs. The callback may also be called spuriously without a reason.
* *
* The callback may be called in an interrupt context and should not * 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 * @note This is not intended as a replacement for a poll or attach-like
* asynchronous api, but rather as a building block for constructing * asynchronous API, but rather as a building block for constructing
* such functionality. The exact timing of when the registered function * 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); 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 * @see Socket::sigio
* @deprecated * @deprecated
@ -201,7 +187,7 @@ public:
"mbed OS and has been known to cause confusion. Replaced by Socket::sigio.") "mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
void attach(mbed::Callback<void()> func); 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 * @see Socket::sigio
* @deprecated * @deprecated
@ -217,6 +203,8 @@ public:
attach(mbed::callback(obj, method)); attach(mbed::callback(obj, method));
} }
#if !defined(DOXYGEN_ONLY)
protected: protected:
InternetSocket(); InternetSocket();
virtual nsapi_protocol_t get_proto() = 0; virtual nsapi_protocol_t get_proto() = 0;
@ -240,6 +228,8 @@ protected:
static const int READ_FLAG = 0x1u; static const int READ_FLAG = 0x1u;
static const int WRITE_FLAG = 0x2u; static const int WRITE_FLAG = 0x2u;
static const int FINISHED_FLAG = 0x3u; static const int FINISHED_FLAG = 0x3u;
#endif //!defined(DOXYGEN_ONLY)
}; };
#endif // INTERNETSOCKET_H #endif // INTERNETSOCKET_H

4
features/netsocket/Socket.h
View File

@ -194,7 +194,7 @@ public:
*/ */
virtual void sigio(mbed::Callback<void()> func) = 0; virtual void sigio(mbed::Callback<void()> func) = 0;
/* Set socket options. /** Set socket options.
* *
* setsockopt() allows an application to pass stack-specific options * setsockopt() allows an application to pass stack-specific options
* to the underlying stack using stack-specific level and option names, * to the underlying stack using stack-specific level and option names,
@ -211,7 +211,7 @@ public:
*/ */
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0; 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 * getsockopt() allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names, * from the underlying stack using stack-specific level and option names,