@CHIP-RTOS C Library - TCP/IP API

Receive message from another socket.

int recvfrom ( int sd, char far *bufptr, int bufLen,
               int flags, unsigned long timeout,
               struct sockaddr far *fromPtr,
               int *error );

Parameters

sd

Socket descriptor.

bufptr

Pointer to input buffer where received characters will be output.

bufLen

Maximum characters to store in buffer at bufptr .

flags

Wait option:

MSG_BLOCKING - Sleep until data comes in
MSG_TIMEOUT - The caller wakes up after timeout or if bufLen data bytes are received.
MSG_DONTWAIT - Return immediately after collecting what ever data is ready

timeout

Maximum milliseconds to wait if flags is set to MSG_TIMEOUT:

fromPtr

Output parameter: Pointer to a sockaddr_in (IPv4) or sockaddr_in6 (IPv6, SC1x3/SC2x only! ) data structure, which will be set to indicate from where the received data originated. This pointer can be set to NULL if this information is not desired.

error

Output parameter: Failure code, 0 on success.

Return Value

-1: Failure, see error value reported
otherwise: Count of bytes received and placed in bufptr (0 if time-out)

Comments

This API function applies only to UDP sockets.

The MSG_BLOCKING mode will not work if the socket has been put into non-blocking mode using the Set_Blocking_Mode API.

This function's prototype takes a pointer to the generic type sockaddr for its fromPtr parameter, for compatibility between IPv4 and IPv6 protocols. The pointer to the sockaddr_in (IPv4) or sockaddr_in6 (IPv6, SC1x3/SC2x only! ) data structure which is actually used should be cast to a sockaddr type pointer to avoid compiler warnings, "Suspicious pointer conversion".

SC1x Comments

recvfrom() can only return complete UDP datagrams at the user provided buffer. If the waiting datagram at the internal socket receive queue has size larger than the specified bufLen, recvfrom returns with -1 and error code 240 ("Message too long") without writing the datagram into the user buffer. You can use GetWaitingBytes to detect the size of the next waiting datagram at the internal receive queue of this socket.

SC1x3/SC2x Comments

The actual library function reached here is named recvfrom_ipstackV2 .   The name change occurs due to a macro in the library header file.

If the waiting datagram at the internal socket receive queue has size larger than the specified bufLen , recvfrom() returns with -1 and error code 240 ("Message too long").   The receive buffer contains the truncated datagram.

This legacy version of recvfrom() specified here is not compatible to the BSD 4.4 Socket API.   The recvfrom() function can be used in BSD 4.4 compatible mode if the compilation switch

     #define BSD44_SOCKET_API_STYLE

is defined in the user application prior to including the Beck C-Library header files.   Using this switch the C-Library TCPIP_Socket.H include file redefines recvfrom() to recvfrom_bsd().  The parameters to recvfrom_bsd() are identical to the parameters of the BSD4.4 socket recvfrom() function.

The recvfrom_bsd() method uses dynamical linking, so therefore executes faster than this legacy API's sofware interrupt method. The compilation switch

     #define TCPIP_DYN_LINK_SOCK

may be defined in the user application prior to including the Beck C-Library header files to implement this legacy recvfrom() method using the faster recvfrom_bsd() dynamic linked API.

The first compilation switch takes precedence.   This second compilation option, TCPIP_DYN_LINK_SOCK will be not affect this API when the first option (BSD44_SOCKET_API_STYLE ) is defined.

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

Supported since or modified in @CHIP-RTOS version

SC12 SC13 SC11 SC1x3 SC2x V1.00 V1.00 V1.00 V0.90 V1.00

This API List
List of C Libraries
@CHIP-RTOS Main Index

End of document