The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

 Real time embedded FreeRTOS RSS feed 
Homepage FreeRTOS+ Products FreeRTOS Labs Support Forum Contact / Enquiries

 FreeRTOS+POSIX:
 POSIX API for FreeRTOS
 FreeRTOS+FAT:
 Thread aware file system

FreeRTOS_connect()

[FreeRTOS+TCP API Reference]

FreeRTOS_sockets.h 
BaseType_t FreeRTOS_connect( Socket_t xClientSocket,
                             struct freertos_sockaddr *pxAddress,
                             socklen_t xAddressLength );

Connect a TCP socket to a remote socket.

The socket must first have been successfully created by a call to FreeRTOS_socket(), and optionally bound to a port using a call to FreeRTOS_bind().

If FreeRTOS_connect() is called on a socket that is not bound to a port number, and the value of ipconfigALLOW_SOCKET_SEND_WITHOUT_BIND is set to 1 in FreeRTOSIPConfig.h, then the TCP/IP stack will automatically bind the socket to a port number from the private address range.

FreeRTOS_connect() has an optional timeout. The timeout defaults to ipconfigSOCK_DEFAULT_RECEIVE_BLOCK_TIME, and is modified using the FREERTOS_SO_RCVTIMEO parameter in a call to FreeRTOS_setsockopt(). If the connect operation does not succeed immediately then the calling RTOS task will be held in the Blocked state (so that other tasks can execute) until either the connect request is successful, or the timeout expires.

Parameters:

xSocket   The handle of the socket being bound. The socket must have already been created (see FreeRTOS_socket()).

pxAddress   A pointer to a freertos_sockaddr structure that contains the destination IP address and port number (the remote socket the local socket is attempting to connect to).

xAddressLength   Not currently used, but should be set to sizeof( struct freertos_sockaddr ) to ensure future compatibility.

Returns:

If the connect operation succeeded then 0 is returned.

If xSocket is not a valid TCP socket then -pdFREERTOS_ERRNO_EBADF is returned.

If xSocket was already connected before FreeRTOS_connect() was called then -pdFREERTOS_ERRNO_EISCONN is returned.

If xSocket is not in a state that allows a connect operation then either -pdFREERTOS_ERRNO_EINPROGRESS or -pdFREERTOS_ERRNO_EAGAIN is returned.

If the socket has a read block time of zero and the connect operation cannot succeed immediately then -pdFREERTOS_ERRNO_EWOULDBLOCK is returned.

If the connect attempt times out then -pdFREERTOS_ERRNO_ETIMEDOUT is returned.

Note that, because FreeRTOS does not implement errno, the behaviour in the presence of an error is necessarily different to that of connect() functions that are fully compliant with the expected Berkeley sockets behaviour.

Example usage:

See the Sending TCP Data section of the FreeRTOS+TCP networking tutorial pages.


[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ FreeRTOS Labs Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]




Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.