Skip to content

Commit

Permalink
Fix #1020, resolve discrepancies between socket API and unit tests
Browse files Browse the repository at this point in the history 
Ensures correlation between the test cases and documented return
values for the OSAL socket API.
  • Loading branch information
@jphickey
jphickey committed May 28, 2021
1 parent 6776050 commit 5fe26e1
Show file tree
Hide file tree
Showing 3 changed files with 291 additions and 338 deletions.
75 changes: 54 additions & 21 deletions src/os/inc/osapi-sockets.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -145,11 +145,13 @@ typedef struct
*
* The address is set to a suitable default value for the family.
*
* @param[out] Addr The address buffer to initialize
* @param[out] Addr The address buffer to initialize @nonnull
* @param[in] Domain The address family
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if Addr argument is NULL
* @retval #OS_ERR_NOT_IMPLEMENTED if the system does not implement the requested domain
*/
int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain);

Expand All @@ -165,13 +167,15 @@ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain);
*
* @note For IPv4, this would typically be the dotted-decimal format (X.X.X.X).
*
* @param[out] buffer Buffer to hold the output string
* @param[in] buflen Maximum length of the output string
* @param[in] Addr The network address buffer to convert
* @param[out] buffer Buffer to hold the output string @nonnull
* @param[in] buflen Maximum length of the output string @nonzero
* @param[in] Addr The network address buffer to convert @nonnull
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_INVALID_SIZE if passed-in buflen is not valid
* @retval #OS_ERROR if the address cannot be converted to string, or string buffer too small
*/
int32 OS_SocketAddrToString(char *buffer, size_t buflen, const OS_SockAddr_t *Addr);

Expand All @@ -190,11 +194,13 @@ int32 OS_SocketAddrToString(char *buffer, size_t buflen, const OS_SockAddr_t *Ad
* Since many embedded deployments do not have name services, this should
* not be relied upon.
*
* @param[out] Addr The address buffer to initialize
* @param[in] string The string to initialize the address from.
* @param[out] Addr The address buffer to initialize @nonnull
* @param[in] string The string to initialize the address from @nonnull
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERROR if the string cannot be converted to an address
*/
int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string);

Expand All @@ -206,11 +212,13 @@ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string);
* as TCP/IP and UDP/IP) this function gets the port number from the
* address structure.
*
* @param[out] PortNum Buffer to store the port number
* @param[in] Addr The network address buffer
* @param[out] PortNum Buffer to store the port number @nonnull
* @param[in] Addr The network address buffer @nonnull
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_BAD_ADDRESS if the address domain is not compatible
*/
int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr);

Expand All @@ -222,11 +230,13 @@ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr);
* as TCP/IP and UDP/IP) this function sets the port number from the
* address structure.
*
* @param[out] Addr The network address buffer @nonnull
* @param[in] PortNum The port number to set
* @param[out] Addr The network address buffer
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_BAD_ADDRESS if the address domain is not compatible
*/
int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum);
/**@}*/
Expand All @@ -253,12 +263,14 @@ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum);
*
* A new, unconnected and unbound socket is allocated of the given domain and type.
*
* @param[out] sock_id Buffer to hold the non-zero OSAL ID
* @param[out] sock_id Buffer to hold the non-zero OSAL ID @nonnull
* @param[in] Domain The domain / address family of the socket (INET or INET6, etc)
* @param[in] Type The type of the socket (STREAM or DATAGRAM)
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_NOT_IMPLEMENTED if the system does not implement the requested socket/address domain
*/
int32 OS_SocketOpen(osal_id_t *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t Type);

Expand All @@ -274,10 +286,14 @@ int32 OS_SocketOpen(osal_id_t *sock_id, OS_SocketDomain_t Domain, OS_SocketType_
* socket into a listening state for incoming connections at the local address.
*
* @param[in] sock_id The socket ID
* @param[in] Addr The local address to bind to
* @param[in] Addr The local address to bind to @nonnull
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_ERR_INVALID_ID if the sock_id parameter is not valid
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_INCORRECT_OBJ_STATE if the socket is already bound
* @retval #OS_ERR_INCORRECT_OBJ_TYPE if the handle is not a socket
*/
int32 OS_SocketBind(osal_id_t sock_id, const OS_SockAddr_t *Addr);

Expand All @@ -290,10 +306,14 @@ int32 OS_SocketBind(osal_id_t sock_id, const OS_SockAddr_t *Addr);
* socket will return an error (these sockets should use SendTo/RecvFrom).
*
* @param[in] sock_id The socket ID
* @param[in] Addr The remote address to connect to
* @param[in] Addr The remote address to connect to @nonnull
* @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_ERR_INCORRECT_OBJ_STATE if the socket is already connected
* @retval #OS_ERR_INVALID_ID if the sock_id parameter is not valid
* @retval #OS_ERR_INCORRECT_OBJ_TYPE if the handle is not a socket
* @retval #OS_INVALID_POINTER if Addr argument is NULL
*/
int32 OS_SocketConnect(osal_id_t sock_id, const OS_SockAddr_t *Addr, int32 timeout);
Expand All @@ -309,6 +329,11 @@ int32 OS_SocketConnect(osal_id_t sock_id, const OS_SockAddr_t *Addr, int32 timeo
* @param[in] Mode Whether to shutdown reading, writing, or both.
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_ERR_INVALID_ID if the sock_id parameter is not valid
* @retval #OS_ERR_INVALID_ARGUMENT if the Mode argument is not one of the valid options
* @retval #OS_ERR_INCORRECT_OBJ_TYPE if the handle is not a socket
* @retval #OS_ERR_INCORRECT_OBJ_STATE if the socket is not connected
*/
int32 OS_SocketShutdown(osal_id_t sock_id, OS_SocketShutdownMode_t Mode);

Expand All @@ -325,12 +350,16 @@ int32 OS_SocketShutdown(osal_id_t sock_id, OS_SocketShutdownMode_t Mode);
* server socket ID can be reused for the next connection.
*
* @param[in] sock_id The server socket ID, previously bound using OS_SocketBind()
* @param[out] connsock_id The connection socket, a new ID that can be read/written
* @param[in] Addr The remote address of the incoming connection
* @param[out] connsock_id The connection socket, a new ID that can be read/written @nonnull
* @param[in] Addr The remote address of the incoming connection @nonnull
* @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_INVALID_ID if the sock_id parameter is not valid
* @retval #OS_ERR_INCORRECT_OBJ_TYPE if the handle is not a socket
* @retval #OS_ERR_INCORRECT_OBJ_STATE if the socket is not bound or already connected
*/
int32 OS_SocketAccept(osal_id_t sock_id, osal_id_t *connsock_id, OS_SockAddr_t *Addr, int32 timeout);

Expand All @@ -342,14 +371,16 @@ int32 OS_SocketAccept(osal_id_t sock_id, osal_id_t *connsock_id, OS_SockAddr_t *
* that data without blocking. Otherwise, it may block up to the given timeout.
*
* @param[in] sock_id The socket ID, previously bound using OS_SocketBind()
* @param[out] buffer Pointer to message data receive buffer
* @param[in] buflen The maximum length of the message data to receive
* @param[out] buffer Pointer to message data receive buffer @nonnull
* @param[in] buflen The maximum length of the message data to receive @nonzero
* @param[out] RemoteAddr Buffer to store the remote network address (may be NULL)
* @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever
*
* @return Count of actual bytes received or error status, see @ref OSReturnCodes
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_INVALID_SIZE if passed-in buflen is not valid
* @retval #OS_ERR_INVALID_ID if the sock_id parameter is not valid
* @retval #OS_ERR_INCORRECT_OBJ_TYPE if the handle is not a socket
*/
int32 OS_SocketRecvFrom(osal_id_t sock_id, void *buffer, size_t buflen, OS_SockAddr_t *RemoteAddr, int32 timeout);

Expand All @@ -362,13 +393,15 @@ int32 OS_SocketRecvFrom(osal_id_t sock_id, void *buffer, size_t buflen, OS_SockA
* an error code.
*
* @param[in] sock_id The socket ID, which must be of the datagram type
* @param[in] buffer Pointer to message data to send
* @param[in] buflen The length of the message data to send
* @param[in] buffer Pointer to message data to send @nonnull
* @param[in] buflen The length of the message data to send @nonzero
* @param[in] RemoteAddr Buffer containing the remote network address to send to
*
* @return Count of actual bytes sent or error status, see @ref OSReturnCodes
* @retval #OS_INVALID_POINTER if argument is NULL
* @retval #OS_ERR_INVALID_SIZE if passed-in buflen is not valid
* @retval #OS_ERR_INVALID_ID if the sock_id parameter is not valid
* @retval #OS_ERR_INCORRECT_OBJ_TYPE if the handle is not a socket
*/
int32 OS_SocketSendTo(osal_id_t sock_id, const void *buffer, size_t buflen, const OS_SockAddr_t *RemoteAddr);

Expand All @@ -380,8 +413,8 @@ int32 OS_SocketSendTo(osal_id_t sock_id, const void *buffer, size_t buflen, cons
*
* @sa OS_SocketGetInfo()
*
* @param[out] sock_id Buffer to hold result
* @param[in] sock_name Name of socket to find
* @param[out] sock_id Buffer to hold result @nonnull
* @param[in] sock_name Name of socket to find @nonnull
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
Expand All @@ -399,7 +432,7 @@ int32 OS_SocketGetIdByName(osal_id_t *sock_id, const char *sock_name);
* This allows applications to find the name of a given socket.
*
* @param[in] sock_id The socket ID
* @param[out] sock_prop Buffer to hold socket information
* @param[out] sock_prop Buffer to hold socket information @nonnull
*
* @return Execution status, see @ref OSReturnCodes
* @retval #OS_SUCCESS @copybrief OS_SUCCESS
Expand Down
3 changes: 2 additions & 1 deletion src/os/portable/os-impl-bsd-sockets.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -733,7 +733,8 @@ int32 OS_SocketAddrFromString_Impl(OS_SockAddr_t *Addr, const char *string)
break;
}

if (inet_pton(Accessor->sa.sa_family, string, addrbuffer) < 0)
/* This function is defined as returning 1 on success, not 0 */
if (inet_pton(Accessor->sa.sa_family, string, addrbuffer) != 1)
{
return OS_ERROR;
}
Expand Down
Loading

0 comments on commit 5fe26e1

Please sign in to comment.