Network Core API#

The application programming interfaces (APIs) to the whole Network core stack are described in this section.

Network Initialization#

Function Name

Description

Net_Init()

Initializes Network stack

Net_ConfigureCoreTaskStk()

Configures the Network core task's stack.

Net_ConfigureCoreSvcTaskStk()

Configures the Network service task's stack. The service task is used for core modules like DHCP.

Net_ConfigureMemSeg()

Configures the memory segment to use when allocating control data for the network core.

Net_ConfigureDNS_Client()

Configure the DNS Client module parameters.

Net_CoreTaskPrioSet()

Assigns a new priority to the Network core task.

Net_CoreSvcTaskPrioSet()

Assigns a new priority to the Network core service task.

General Network Utilities#

Function Name

Description

NET_UTIL_HOST_TO_NET_16()

Convert 16-bit integer values from CPU host-order to network-order.

NET_UTIL_HOST_TO_NET_32()

Convert 32-bit integer values from CPU host-order to network-order.

NET_UTIL_NET_TO_HOST_16()

Convert 16-bit integer values from network-order to CPU host- order.

NET_UTIL_NET_TO_HOST_32()

Convert 32-bit integer values from network-order to CPU host- order.

NetUtil_TS_Get_ms()

Get current millisecond timestamp.

NetUtil_TS_Get()

Get the current Internet Timestamp.

ASCII Functions#

Function Name

Description

NetASCII_IPv4_to_Str()

Convert an IPv4 address in host-order into an IPv4 dotted-decimal notation ASCII string.

NetASCII_IPv6_to_Str()

Convert an IPv6 address into an IPv6 colon-decimal notation ASCII string.

NetASCII_MAC_to_Str()

Convert a Media Access Control (MAC) address into a hexadecimal address string.

NetASCII_Str_to_IP()

Convert a string of an IPv4 or IPv6 address in their respective decimal notation to an IPv4 or IPv6 address.

NetASCII_Str_to_IPv4()

Convert a string of an IPv4 address in dotted-decimal notation to an IPv4 address in host-order.

NetASCII_Str_to_IPv6()

Convert a string of an IPv6 address in common-decimal notation to an IPv6 address.

NetASCII_Str_to_MAC()

Convert an hexadecimal address string to a Media Access Control (MAC) address.

Network Buffer#

Function Name

Description

NetBuf_PoolStatGet()

Get an interface’s Network Buffers’ statistics pool.

NetBuf_PoolStatResetMaxUsed()

Reset an interface’s Network Buffers’ statistics pool’s maximum number of entries used.

NetBuf_RxLargePoolStatGet()

Get an interface’s large receive buffers’ statistics pool.

NetBuf_RxLargePoolStatResetMaxUsed()

Reset an interface’s large receive buffers’ statistics pool’s maximum number of entries used.

NetBuf_TxLargePoolStatGet()

Get an interface’s large transmit buffers’ statistics pool.

NetBuf_TxLargePoolStatResetMaxUsed()

Reset an interface’s large transmit buffers’ statistics pool’s maximum number of entries used.

NetBuf_TxSmallPoolStatGet()

Get an interface’s small transmit buffers’ statistics pool.

NetBuf_TxSmallPoolStatResetMaxUsed()

Reset an interface’s small transmit buffers’ statistics pool’s maximum number of entries used.

Network Connection#

Function Name

Description

NetConn_CfgAccessedTh()

Configure network connection access promotion threshold.

NetConn_PoolStatGet()

Get Network Connections’ statistics pool.

NetConn_PoolStatResetMaxUsed()

Reset Network Connections’ statistics pool’s maximum number of entries used.

Network Timer#

Function Name

Description

NetTmr_PoolStatGet()

Gets the network timer statistics pool.

NetTmr_PoolStatResetMaxUsed()

Resets the network timer statistics pool's maximum number of entries used.

Network Interface#

Function Name

Description

NetIF_Add()

Add a network device and hardware as a network interface.

NetIF_AddrHW_Get()

Get network interface’s hardware address.

NetIF_AddrHW_IsValid()

Validate a network interface hardware address.

NetIF_AddrHW_Set()

Set network interface’s hardware address.

NetIF_CfgPerfMonPeriod()

Configure the network interface Performance Monitor Handler timeout.

NetIF_CfgPhyLinkPeriod()

Configure network interface Physical Link State Handler timeout.

NetIF_GetExtAvailCtr()

Returns the number of external interface configured.

NetIF_GetNbrBaseCfgd()

Gets the interface base number (first interface ID).

NetIF_GetRxDataAlignPtr()

Get an aligned pointer into a receive application data buffer.

NetIF_GetTxDataAlignPtr()

Get an aligned pointer into a transmit application data buffer.

NetIF_TypeGet()

Get the network interface type.

NetIF_IO_Ctrl()

Handle network interface and/or device specific (I/O) control(s).

NetIF_IsEn()

Validate network interface as enabled.

NetIF_IsEnCfgd()

Validate configured network interface as enabled.

NetIF_ISR_Handler()

Handle a network interface’s device interrupts.

NetIF_IsValid()

Validate network interface number.

NetIF_IsValidCfgd()

Validate configured network interface number.

NetIF_LinkStateGet()

Get network interface’s last known physical link state.

NetIF_LinkStateSubscribe()

Subscribe to get notified when an interface link state changes.

NetIF_LinkStateUnsubscribe()

Unsubscribe to get notified when interface link state changes.

NetIF_LinkStateWaitUntilUp()

Wait for a network interface's physical link state to be UP .

NetIF_MTU_Get()

Get network interface’s MTU.

NetIF_MTU_Set()

Set network interface’s MTU.

NetIF_Start()

Start a network interface.

NetIF_Stop()

Stop a network interface.

NetIF_TxSuspendTimeoutGet_ms()

Gets the network interface transmit suspend timeout value.

NetIF_TxSuspendTimeoutSet()

Sets the network interface transmit suspend timeout value.

NetIF_WaitSetupReady()

Wait for the network interface setup to be complete.

Ethernet Network Interface#

Macro Name

Description

NET_CTRLR_ETHER_REG()

Registers an Ethernet controller to the platform manager.

Function Name

Description

NetIF_Ether_Add()

Add & initialize a specific instance of a network Ethernet interface.

NetIF_Ether_Start()

Start an Ethernet type interface

Wireless Network Interface#

Macro Name

Description

NET_CTRLR_WIFI_SPI_REG()

Registers an external WiFi controller connected via SPI to the platform manager.

Function Name

Description

NetIF_WiFi_Add()

Add & initialize a specific instance of a network WiFi interface.

NetIF_WiFi_CreateAP()

Create a wireless ad-hoc access point.

NetIF_WiFi_GetPeerInfo()

Gets the peer info connected to the access point (when acting as an access point).

NetIF_WiFi_Join()

Join a wireless access point.

NetIF_WiFi_Leave()

Leave the access point previously joined.

NetIF_WiFi_Scan()

Scan available wireless access point.

NetIF_WiFi_Start()

Start a Wi-Fi-type interface.

DHCP Client#

Function Name

Description

DHCPc_IF_Add()

Attaches an interface to the DHCP module and starts the DHCP process on this interface.

DHCPc_IF_Reboot

Reboots the DHCP Client process.

DHCPc_IF_Remove

Stops and removes the DHCP operation on the given network interface.

DNS Client#

Function Name

Description

DNSc_CacheClrAll()

Flushes the DNS cache.

DNSc_CacheClrHost()

Removes a host from the cache.

DNSc_CfgServerByAddr()

Configures the DNS server to use by default with an address structure.

DNSc_CfgServerByStr()

Configures the DNS server to use by default using a string.

DNSc_GetServerByAddr()

Gets the default DNS server in an address object format.

DNSc_GetServerByStr()

Gets the default DNS server in string format.

DNSc_GetHost()

Converts a string representation of a host name to its corresponding IP address using DNS service.

DNSc GetHostAddrs()

Get a list of IP addresses assigned to a host.

DNSc FreeHostAddrs()

Free Host addresses allocated by DNS_HostAddrsGet().

ARP#

Function Name

Description

NetARP_CacheGetAddrHW()

Get the hardware address corresponding to a specific ARP cache’s protocol address.

NetARP_CachePoolStatGet()

Get ARP caches’ statistics pool.

NetARP_CachePoolStatResetMaxUsed()

Reset ARP caches’ statistics pool’s maximum number of entries used.

NetARP_CacheProbeAddrOnNet()

Transmit an ARP request to probe the local network for a specific protocol address.

NetARP_CfgAddrFilterEn()

Configures the ARP address filter feature

NetARP_CfgCacheAccessedTh()

Configure ARP cache access promotion threshold.

NetARP_CfgCacheTimeout()

Configure ARP cache timeout for ARP Cache List.

NetARP_CfgCacheTxQ_MaxTh()

Configures the ARP cache maximum number of transmit packet buffers to enqueue.

NetARP_CfgPendReqMaxRetries()

Configure maximum number of ARP request retries for ARP cache in PEND state.

NetARP_CfgPendReqTimeout()

Configure timeout between ARP request timeouts for ARP cache in PEND state.

NetARP_CfgRenewReqMaxRetries()

Configure maximum number of ARP request retries for ARP cache in RENEW state.

NetARP_CfgRenewReqTimeout()

Configure timeout between ARP request timeouts for ARP cache in RENEW state.

NetARP_IsAddrProtocolConflict()

Check interface’s protocol address conflict status between this interface’s ARP host protocol address(es) and any other host(s) on the local network.

NetARP_TxReqGratuitous()

Prepares and transmits an unrequested ARP Request into the local network.

NDP#

Function Name

Description

NetNDP_CfgNeighborCacheTimeout()

Configure NDP neighbor cache timeout for NDP Neighbor Cache List.

NetNDP_CfgReachabilityTimeout()

Configure one of the NDP neighbor timeouts associated with the Neighbors Unreachability Detection.

NetNDP_CfgSolicitMaxNbr()

Configure one of the NDP neighbor maximum solicitations number.

IGMP#

Function Name

Description

NetIGMP_HostGrpJoin()

Join a host group.

NetIGMP_HostGrpLeave()

Leave a host group.

MLDP#

Function Name

Description

NetMLDP_HostGrpJoin()

Join a MLDP Multicast host group.

NetMLDP_HostGrpLeave()

Leave a MLDP host group.

ICMP#

Function Name

Description

NetICMP_TxEchoReq()

Send ICMPv4 or ICMPv6 Echo Request message to a network host.

IPv4#

Function Name

Description

NetIPv4_AddrLinkLocalCfg()

Start the IPv4 Link Local process on the given interface.

NetIPv4_AddrLinkLocalCfgRemove()

Stop the IPv4 Link Local process on the given interface and remove the link local address if one has already been configured.

NetIPv4_CfgAddrAdd()

Add a statically-configured IPv4 host address, subnet mask, and default gateway to an interface.

NetIPv4_CfgAddrAddDynamic()

Add a dynamically-configured IPv4 host address, subnet mask, and default gateway to an interface.

NetIPv4_CfgAddrAddDynamicStart()

Start dynamic IPv4 address configuration for an interface.

NetIPv4_CfgAddrAddDynamicStop()

Stop dynamic IPv4 address configuration for an interface.

NetIPv4_CfgAddrRemove()

Remove a configured IPv4 host address from an interface.

NetIPv4_CfgAddrRemoveAll()

Remove all configured IPv4 host address(es) from an interface.

NetIPv4_CfgFragReasmTimeout()

Configure IPv4 fragment reassembly timeout.

NetIPv4_GetAddrDfltGateway()

Get the default gateway IPv4 address for a host’s configured IPv4 address.

NetIPv4_GetAddrHost()

Get an interface’s configured IPv4 host address(es).

NetIPv4_GetAddrSrc()

Get corresponding configured IPv4 host address for a remote IPv4 address to use as source address.

NetIPv4_GetAddrSubnetMask()

Get the IPv4 address subnet mask for a host’s configured IPv4 address.

NetIPv4_IsAddrBroadcast()

Validate an IPv4 address as the limited broadcast IPv4 address.

NetIPv4_IsAddrClassA()

Validate an IPv4 address as a Class-A IPv4 address.

NetIPv4_IsAddrClassB()

Validate an IPv4 address as a Class-B IPv4 address.

NetIPv4_IsAddrClassC()

Validate an IPv4 address as a Class-C IPv4 address.

NetIPv4_IsAddrHost()

Validate an IPv4 address as one the host’s IPv4 address(es).

NetIPv4_IsAddrHostCfgd()

Validate an IPv4 address as one the host’s configured IPv4 address(es).

NetIPv4_IsAddrLocalHost()

Validate an IPv4 address as a Localhost IPv4 address.

NetIPv4_IsAddrLocalLink()

Validate an IPv4 address as a link-local IPv4 address.

NetIPv4_IsAddrMulticast()

Validate an IPv4 address as a multicast IP address.

NetIPv4_IsAddrsCfgdOnIF()

Check if any IPv4 address(es) are configured on an interface.

NetIPv4_IsAddrThisHost()

Validate an IPv4 address as the ‘This Host’ initialization IPv4 address.

NetIPv4_IsValidAddrHost()

Validate an IPv4 address as a valid IPv4 host address.

NetIPv4_IsValidAddrHostCfgd()

Validate an IPv4 address as a valid, configurable IPv4 host address.

NetIPv4_IsValidAddrSubnetMask()

Validate an IPv4 address subnet mask.

IPv6#

Function Name

Description

NetIPv6_AddrAutoCfgDis()

Disables the IPv6 Stateless Address Auto-Configuration procedure.

NetIPv6_AddrAutoCfgEn()

Enables the IPv6 Stateless Address Auto-Configuation procedure.

NetIPv6_AddrMask()

Applies IPv6 mask on an address.

NetIPv6_AddrMaskByPrefixLen()

Gets the IPv6 address masked with the prefix length.

NetIPv6_AddrSubscribe()

Configures the IPv6 Address Configuration hook function.

NetIPv6_AddrUnsubscribe()

Removes a configured IPv6 host address and multicast solicited mode address from an interface.

NetIPv6_CfgAddrAdd()

Adds a statically-configured IPv6 host address to an interface.

NetIPv6_AddrTypeValidate()

Validates the type of an IPv6 address.

NetIPv6_CfgAddrRemove()

Removes a configured IPv6 host address and multicast solicited mode address from an interface.

NetIPv6_CfgAddrRemoveAll()

Removes all configured IPv6 host address(s) from an interface.

NetIPv6_CfgFragReasmTimeout()

Configures the IPv6 fragment reassembly timeout.

NetIPv6_CreateAddrFromID()

Creates an IPv6 address from a prefix and an identifier.

NetIPv6_CreateIF_ID()

Creates an IPv6 interface identifier.

NetIPv6_GetAddrHost()

Gets an interface's IPv6 host address(es).

NetIPv6_GetAddrSrc()

Finds the best matched source address in the IPv6 configured host addresses for the specified destination address.

NetIPv6_GetAddrMatchingLen()

Computes the number of identical most significant bits of two IPv6 addresses.

NetIPv6_GetAddrScope()

Gets the scope of a specific IPv6 address.

NetIPv6_IsAddrHostCfgd()

Validates an IPv6 address as a configured IPv6 host address on an enabled interface.

NetIPv6_IsAddrsCfgdOnIF()

Checks if any IPv6 host addresses are configured on a specific interface.

NetIPv6_IsValidAddrHost()

Validates an IPv6 host address.

NetIPv6_IsAddrLinkLocal()

Validates an IPv6 address as a link-local IPv6 address.

NetIPv6_IsAddrSiteLocal()

Validates an IPv6 address as a site-local address.

NetIPv6_IsAddrMcast()

Validates an IPv6 address as a multicast address.

NetIPv6_IsAddrMcastAllRouters()

Validates an IPv6 address as the all routers multicast address.

NetIPv6_IsAddrMcastAllNodes()

Validates an IPv6 address as the all nodes multicast address.

NetIPv6_IsAddrMcastSolNode()

Validates an IPv6 address as a solicited node multicast address.

NetIPv6_IsAddrMcastRsvd()

Validates an IPv6 address as a reserved multicast IPv6 address.

NetIPv6_IsAddrUnspecified()

Validates an IPv6 address as the unspecified IPv6 address.

NetIPv6_IsAddrLoopback()

Validates an IPv6 address as the IPv6 loopback address.

TCP#

Function Name

Description

NetTCP_ConnCfgIdleTimeout()

Configures the TCP connection’s idle timeout.

NetTCP_ConnCfgMaxSegSizeLocal()

Configures the TCP connection’s local maximum segment size.

NetTCP_ConnCfgMSL_Timeout()

Configures the TCP connection's maximum segment lifetime (MSL) timeout.

NetTCP_ConnCfgReTxMaxTh()

Configures the TCP connection’s maximum number of same segment retransmissions.

NetTCP_ConnCfgReTxMaxTimeout()

Configures the TCP connection’s maximum retransmission timeout.

NetTCP_ConnCfgRxWinSize()

Configures the TCP connection’s receive window size.

NetTCP_ConnCfgTxAckDlyTimeout()

Configures the TCP connection's transmit acknowledgment delay timeout.

NetTCP_ConnCfgTxAckImmedRxdPushEn()

Configures the TCP connection’s transmit immediate acknowledgment for received and pushed TCP segments.

NetTCP_ConnCfgTxKeepAliveEn()

Configures the TCP connection's transmit keep-alive enable.

NetTCP_ConnCfgTxKeepAliveRetryTimeout()

Configures the TCP connection's transmit keep-alive retry timeout.

NetTCP_ConnCfgTxKeepAliveTh()

Configures the TCP connection's maximum number of consecutive keep-alives to transmit.

NetTCP_ConnCfgTxNagleEn()

Configures the TCP connection's transmit Nagle algorithm enable.

NetTCP_ConnCfgTxWinSize()

Configures the TCP connection’s transmit window size.

NetTCP_ConnPoolStatGet()

Gets the TCP connections’ statistics pool.

NetTCP_ConnPoolStatResetMaxUsed()

Resets the TCP connections’ statistics pool’s maximum number of entries used.

NetTCP_ConnStateGet()

Retrieves the TCP Connection State.

Socket Functions#

Function Name

Description

NET_SOCK_DESC_CLR()

Remove a socket file descriptor ID as a member of a file descriptor set.

NET_SOCK_DESC_COPY()

Copy a file descriptor set to another file descriptor set.

NET_SOCK_DESC_INIT()

Initialize/zero-clear a file descriptor set.

NET_SOCK_DESC_IS_SET()

Check if a socket file descriptor ID is a member of a file descriptor set.

NET_SOCK_DESC_SET()

Add a socket file descriptor ID as a member of a file descriptor set.

NetSock_Accept()

Wait for new socket connections on a listening server socket.

NetSock_Bind()

Assign network addresses to sockets.

NetSock_CfgBlock()

Configure a socket’s blocking mode.

NetSock_CfgConnChildQ_SizeGet()

Get socket's connection child queue size value.

NetSock_CfgConnChildQ_SizeSet()

Configure socket's child connection queue size.

NetSock_CfgIF()

Configure the interface that must be used by the socket.

NetSock_CfgRxQ_Size()

Configure socket's receive queue size.

NetSock_CfgSecure()

Configure a socket’s secure mode.

NetSock_CfgSecureClientCertKeyInstall()

Install certificate and key that must be used by a client for mutual authentication.

NetSock_CfgSecureClientCommonName()

Configure client socket's common name.

NetSock_CfgSecureClientTrustCallBack()

Configure client socket's trust call back function.

NetSock_CfgSecureServerCertKeyInstall()

Install certificate (CERT) and private key (KEY) from a buffer which must be used by a server.

NetSock_CfgTimeoutConnAcceptDflt()

Set socket’s connection accept timeout to configured-default value.

NetSock_CfgTimeoutConnAcceptGet_ms()

Get socket’s connection accept timeout value.

NetSock_CfgTimeoutConnAcceptSet()

Set socket’s connection accept timeout value.

NetSock_CfgTimeoutConnCloseDflt()

Set socket’s connection close timeout to configured-default value.

NetSock_CfgTimeoutConnCloseGet_ms()

Get socket’s connection close timeout value.

NetSock_CfgTimeoutConnCloseSet()

Set socket’s connection close timeout value.

NetSock_CfgTimeoutConnReqDflt()

Set socket’s connection request timeout to configured-default value.

NetSock_CfgTimeoutConnReqGet_ms()

Get socket’s connection request timeout value.

NetSock_CfgTimeoutConnReqSet()

Set socket’s connection request timeout value.

NetSock_CfgTimeoutRxQ_Dflt()

Set socket’s connection receive queue timeout to configured-default value.

NetSock_CfgTimeoutRxQ_Get_ms()

Get socket’s receive queue timeout value.

NetSock_CfgTimeoutRxQ_Set()

Set socket’s connection receive queue timeout value.

NetSock_CfgTimeoutTxQ_Dflt()

Set socket’s connection transmit queue timeout to configured-default value.

NetSock_CfgTimeoutTxQ_Get_ms()

Get socket’s transmit queue timeout value.

NetSock_CfgTimeoutTxQ_Set()

Set socket’s connection transmit queue timeout value.

NetSock_CfgTxIP_TOS() (IPv4 only)

Configure socket's transmit IPv4 Type of Service (TOS).

NetSock_CfgTxIP_TTL_Multicast() (IPv4 only)

Configure socket's transmit IPv4 multicast Time to live (TTL).

NetSock_CfgTxIP_TTL() (IPv4 only)

Configure socket's transmit IPv4 Time to Live (TTL).

NetSock_CfgTxQ_Size()

Configure socket's transmit queue size.

NetSock_Close()

Terminate communication and free a socket.

NetSock_Conn()

Connect a local socket to a remote socket address.

NetSock_GetConnTransportID()

Gets a socket’s transport layer connection handle ID (e.g., TCP connection ID) if available.

NetSock_GetLocalIPAddr()

Gets the local IP address used in the socket connection.

NetSock_IsConn()

Check if a socket is connected to a remote socket.

NetSock_Listen()

Set a socket to accept incoming connections.

NetSock_Open()

Create a datagram (i.e., UDP) or stream (i.e., TCP) type socket.

NetSock_OptGet()

Get the specified socket option from the sock_id socket.

NetSock_OptSet()

Set the specified socket option to the sock_id socket.

NetSock_PoolStatGet()

Get Network Sockets’ statistics pool.

NetSock_PoolStatResetMaxUsed()

Reset Network Sockets’ statistics pool’s maximum number of entries used.

NetSock_RxData() / NetSock_RxDataFrom()

Copy up to a specified number of bytes received from a remote socket into an application memory buffer.

NetSock_Sel()

Check if any sockets are ready for available read or write operations or error conditions.

NetSock_SelAbort()

Abort any tasks that are pending on a socket using the select functionality.

NetSock_TxData() / NetSock_TxDataTo()

Copy bytes from an application memory buffer into a socket to send to a remote socket.

BSD Sockets Functions#

Function Name

Description

accept()

Wait for new socket connections on a listening server socket.

bind()

Assign network addresses to sockets.

close()

Terminate communication and free a socket.

connect()

Connect a local socket to a remote socket address.

FD_CLR()

Remove a socket file descriptor ID as a member of a file descriptor set.

FD_ISSET()

Check if a socket file descriptor ID is a member of a file descriptor set.

FD_SET()

Add a socket file descriptor ID as a member of a file descriptor set.

FD_ZERO()

Initialize/zero-clear a file descriptor set.

getsockopt()

Get a specific option value on a specific TCP socket.

htonl()

Convert 32-bit integer values from CPU host-order to network-order.

htons()

Convert 16-bit integer values from CPU host-order to network-order.

inet_addr()

Convert a string of an IPv4 address in dotted-decimal notation to an IPv4 address in host-order.

inet_aton()

Convert an IPv4 address in ASCII dotted-decimal notation to a network protocol IPv4 address in network-order.

inet_ntoa()

Convert an IPv4 address in host-order into an IPv4 dotted-decimal notation ASCII strin

inet_ntop()

Converts an IPv4 or IPv6 Internet network address into a string in Internet standard format.

inet_pton()

Converts an IPv4 or IPv6 Internet network address in its standard text presentation form into its numeric binary form.

getaddrinfo()

Converts human-readable text strings representing hostnames or IP addresses into a dynamically allocated linked list of struct addrinfo structures.

freeaddrinfo()

Frees addrinfo structures information that getaddrinfo() has allocated.

listen()

Set a socket to accept incoming connections.

ntohl()

Convert 32-bit integer values from network-order to CPU host-order.

ntohs()

Convert 16-bit integer values from network-order to CPU host-order.

recv() / recvfrom()

Copy up to a specified number of bytes received from a remote socket into an application memory buffer.

select()

Check if any sockets are ready for available read or write operations or error conditions.

send() / sentto()

Copy bytes from an application memory buffer into a socket to send to a remote socket.

setsockopt()

Set a specific option on a specific TCP socket.

socket()

Create a datagram (i.e., UDP) or stream (i.e., TCP) type socket.

Network Application Interface#

Function Name

Description

NetApp_ClientDatagramOpen()

Open a UDP datagram using IPv4 or IPv6 address.

NetApp_ClientDatagramOpenByHostname()

Open a UDP datagram to a server using the server's hostname (select remote address using DNS)

NetApp_ClientStreamOpen()

Open and connect a TCP Stream to a server

NetApp_ClientStreamOpenByHostname()

Open and connect a TCP Stream to a server using the server's hostname (select remote address using DNS)

NetApp_SockOpen()

Open an application socket.

NetApp_SockClose()

Close an application socket.

NetApp_SockBind()

Bind an application socket to a local address.

NetApp_SockConn()

Connect an application socket to a remote address.

NetApp_SockListen()

Set an application socket to listen for connection requests.

NetApp_SockAccept()

Return a new application socket accepted from a listen application socket.

NetApp_SockRx()

Receive application data via socket.

NetApp_SockTx()

Transmit application data via socket.

NetApp_SetSockAddr()

Setup a socket address from an IPv4 or an IPv6 address.

NetApp_TimeDly_ms()

Delay for specified time, in milliseconds.

Network Initialization API#

Function Name

Description

Net_Init()

Initializes Network stack

Net_ConfigureCoreTaskStk()

Configures the Network core task's stack.

Net_ConfigureCoreSvcTaskStk()

Configures the Network service task's stack. The service task is used for core modules like DHCP.

Net_ConfigureMemSeg()

Configures the memory segment to use when allocating control data for the network core.

Net_ConfigureDNS_Client()

Configure the DNS Client module parameters.

Net_CoreTaskPrioSet()

Assigns a new priority to the Network core task.

Net_CoreSvcTaskPrioSet()

Assigns a new priority to the Network core service task.

Net_Init()#

Description#

Initializes Network stack.

Files#

net.h/net.c

Prototype#

void Net_Init (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of these return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

  1. Net_Init() must be called:

    (a) Only once from a product's application.

    (b) After product's OS has been initialized.

Net_ConfigureCoreTaskStk()#

Description#

Configures the Network core task's stack.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureCoreTaskStk (CPU_INT32U   stk_size_elements,
                                void        *p_stk)

Arguments#

stk_size_elements

Size, in stack elements, of the task's stack.

p_stk

Pointer to base of the task's stack. If DEF_NULL, stack will be allocated from Common's memory segment.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the Network module is initialized via the Net_Init() function.

  3. In order to change the priority of the Network core task, use the function Net_CoreTaskPrioSet() .

Net_ConfigureCoreSvcTaskStk()#

Description#

Configures the Network service task's stack. The service task is used for core modules like DHCP.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureCoreSvcTaskStk (CPU_INT32U   stk_size_elements,
                                   void        *p_stk)

Arguments#

stk_size_elements

Size, in stack elements, of the task's stack.

p_stk

Pointer to base of the task's stack. If DEF_NULL, stack will be allocated from Common's memory segment.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the Network module is initialized via the Net_Init() function.

  3. In order to change the priority of the Network core task, use the function Net_SvcTaskPrioSet().

Net_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data for the network core.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. DEF_NULL means general purpose heap segment.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the Network module is initialized via the Net_Init() function.

Net_ConfigureDNS_Client()#

Description#

Configure the DNS Client module parameters.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureDNS_Client(DNSc_CFG  *p_cfg)

Arguments#

p_cfg

Pointer to the structure containing the new DNS client parameters.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the Network module is initialized via the Net_Init() function.

Net_CoreTaskPrioSet()#

Description#

Assigns a new priority to the Network core task.

Files#

net.h/net.c

Prototype#

void  Net_CoreTaskPrioSet(CPU_INT08U   prio,
                          RTOS_ERR    *p_err)

Arguments#

prio

New priority of the the Network core task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

  1. This function cannot be called before the Network module has been initialized via the Net_Init() function.

Net_CoreSvcTaskPrioSet()#

Description#

Assigns a new priority to the Network core service task.

Files#

net.h/net.c

Prototype#

void  Net_CoreSvcTaskPrioSet(CPU_INT08U   prio,
                             RTOS_ERR    *p_err)

Arguments#

prio

New priority of the the Network core service task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

  1. This function cannot be called before the Network module has been initialized via the Net_Init() function.

General Network Utilities API#

Function Name

Description

NET_UTIL_HOST_TO_NET_16()

Convert 16-bit integer values from CPU host-order to network-order.

NET_UTIL_HOST_TO_NET_32()

Convert 32-bit integer values from CPU host-order to network-order.

NET_UTIL_NET_TO_HOST_16()

Convert 16-bit integer values from network-order to CPU host- order.

NET_UTIL_NET_TO_HOST_32()

Convert 32-bit integer values from network-order to CPU host- order.

NetUtil_TS_Get_ms()

Get current millisecond timestamp.

NetUtil_TS_Get()

Get the current Internet Timestamp.

NetUtil_TS_Get()#

Description#

Gets the current Internet Timestamp.

Files#

net_util.h/net_util.c

Prototype#

NET_TS  NetUtil_TS_Get (void)

Arguments#

Returned Value#

Internet Timestamp.

Notes / Warnings#

  1. "The Timestamp is a right-justified, 32-bit timestamp in milliseconds since midnight UT [Universal Time]" (RFC #791, Section 3.1 'Options : Internet Timestamp').

  2. The developer is responsible for providing a real-time clock with correct time-zone configuration to implement the Internet Timestamp, if possible.

NetUtil_TS_Get_ms()#

Description#

Gets the current millisecond timestamp.

Files#

net_util.h/net_util.c

Prototype#

NET_TS_MS  NetUtil_TS_Get_ms (void)

Arguments#

Returned Value#

Timestamp (in milliseconds).

Notes / Warnings#

  1. (a)

    1. Although RFC #2988, Section 4 states that "there is no requirement for the clock granularity G used for computing [TCP] RTT measurements ... experience has shown that finer clock granularities (<= 100 msec) perform somewhat better than more coarse granularities".

    2. (a) RFC #2988, Section 2.4 states that "whenever RTO is computed, if it is less than 1 second then the RTO SHOULD be rounded up to 1 second".

      (b) RFC #1122, Section 4.2.3.1 states that "the recommended ... RTO ... upper bound should be 2*MSL" where RFC #793, Section 3.3 'Sequence Numbers : Knowing When to Keep Quiet' states that "the Maximum Segment Lifetime (MSL) is ... to be 2 minutes".

      (c) Therefore, the developer is responsible for providing a timestamp clock with adequate resolution to satisfy the clock granularity (see Note #1(a)) & adequate range to satisfy the minimum/maximum TCP RTO values (see Note #1(b)).

      Therefore, the required upper bound is :

      2 * MSL = 2 * 2 minutes = 4 minutes = 240 seconds

    (b) Therefore, the developer is responsible for providing a timestamp clock with adequate resolution to satisfy the clock granularity (see Note #1(a)) & adequate range to satisfy the minimum/maximum TCP RTO values (see Note #1(b)).

NET_UTIL_HOST_TO_NET_16()#

Convert 16-bit integer values from CPU host-order to network-order.

Files#

net_util.h

Prototype#

          NET_UTIL_HOST_TO_NET_16(val);

Arguments#

val

16-bit integer data value to convert.

Returned Value#

16-bit integer value in network-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 16-bit integer must start on appropriately-aligned CPU addresses. This means that all 16-bit words must start on addresses that are multiples of 2 bytes.

NET_UTIL_HOST_TO_NET_32()#

Convert 32-bit integer values from CPU host-order to network-order.

Files#

net_util.h

Prototype#

          NET_UTIL_HOST_TO_NET_32(val);

Arguments#

val

32-bit integer data value to convert.

Returned Value#

32-bit integer value in network-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 32-bit integer must start on appropriately-aligned CPU addresses. This means that all 32-bit words must start on addresses that are multiples of 4 bytes.

NET_UTIL_NET_TO_HOST_16()#

Convert 16-bit integer values from network-order to CPU host- order.

Files#

net_util.h

Prototype#

          NET_UTIL_NET_TO_HOST_16(val);

Arguments#

val

16-bit integer data value to convert.

Returned Value#

16-bit integer value in CPU host-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 16-bit integer must start on appropriately-aligned CPU addresses. This means that all 16-bit words must start on addresses that are multiples of 2 bytes.

NET_UTIL_NET_TO_HOST_32()#

Convert 32-bit integer values from network-order to CPU host- order.

Files#

net_util.h

Prototype#

          NET_UTIL_NET_TO_HOST_32(val);

Arguments#

val

32-bit integer data value to convert.

Returned Value#

32-bit integer value in CPU host-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 32-bit integer must start on appropriately-aligned CPU addresses. This means that all 32-bit words must start on addresses that are multiples of 4 bytes.

ASCII Functions API#

Function Name

Description

NetASCII_IPv4_to_Str()

Convert an IPv4 address in host-order into an IPv4 dotted-decimal notation ASCII string.

NetASCII_IPv6_to_Str()

Convert an IPv6 address into an IPv6 colon-decimal notation ASCII string.

NetASCII_MAC_to_Str()

Convert a Media Access Control (MAC) address into a hexadecimal address string.

NetASCII_Str_to_IP()

Convert a string of an IPv4 or IPv6 address in their respective decimal notation to an IPv4 or IPv6 address.

NetASCII_Str_to_IPv4()

Convert a string of an IPv4 address in dotted-decimal notation to an IPv4 address in host-order.

NetASCII_Str_to_IPv6()

Convert a string of an IPv6 address in common-decimal notation to an IPv6 address.

NetASCII_Str_to_MAC()

Convert an hexadecimal address string to a Media Access Control (MAC) address.

NetASCII_IPv4_to_Str()#

Description#

Converts a network protocol IPv4 address in host-order into an IPv4 address ASCII string in dotted-decimal notation.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_IPv4_to_Str (NET_IPv4_ADDR   addr_ip,
                            CPU_CHAR       *p_addr_ip_ascii,
                            CPU_BOOLEAN     lead_zeros,
                            RTOS_ERR       *p_err)

Arguments#

addr_ip

IPv4 address.

p_addr_ip_ascii

Pointer to an ASCII character array that will receive the return IPv4.

lead_zeros

  • DEF_NO Do NOT prepend leading zeros to each decimal octet value.

  • DEF_YES Prepend leading zeros to each decimal octet value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. (a)

    1. RFC #1983 states that "dotted decimal notation ... refers [to] IPv4 addresses of the form A.B.C.D; where each letter represents (in decimal) one byte of a four byte IP address."

    2. In other words, the dotted-decimal IP address notation separates four decimal octet values by the dot, or period, character ('.'). Each decimal value represents one octet of the IP address starting with the most significant octet in network-order.

      IP Address Examples : 192.168.1.64 = 0xC0A80140

    (b)

    1. The return dotted-decimal IPv4 address ASCII string formats EXACTLY four decimal values separated by EXACTLY three dot characters and terminated with the NULL character.

    2. The size of the ASCII character array that will receive the returned IP address ASCII string SHOULD be greater than or equal to NET_ASCII_LEN_MAX_ADDR_IP.

  2. (a) Leading zeros option prepends leading '0's prior to the first non-zero digit in each decimal octet value. The number of leading zeros is such that the decimal octet's number of decimal digits is equal to the maximum number of digits (3).

    (b) If leading zeros option DISABLED and the decimal value of the octet is zero, then one digit of '0' value is formatted.

NetASCII_IPv6_to_Str()#

Description#

Converts a network protocol IPv6 address in host-order into an IPv6 address ASCII string in dotted-decimal notation.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_IPv6_to_Str (NET_IPv6_ADDR  *p_addr_ip,
                            CPU_CHAR       *p_addr_ip_ascii,
                            CPU_BOOLEAN     hex_lower_case,
                            CPU_BOOLEAN     lead_zeros,
                            RTOS_ERR       *p_err)

Arguments#

p_addr_ip

Pointer to IPv6 address.

p_addr_ip_ascii

Pointer to an ASCII character array that will receive the return IPv6 address.

hex_lower_case

  • DEF_YES, hexadecimal value will be in lower case

  • DEF_NO, otherwise.

lead_zeros

Prepend leading zeros option (see Note #2) :

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

NetASCII_MAC_to_Str()#

Description#

Converts an Ethernet MAC address into an Ethernet MAC address ASCII string.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_MAC_to_Str (CPU_INT08U   *p_addr_mac,
                           CPU_CHAR     *p_addr_mac_ascii,
                           CPU_BOOLEAN   hex_lower_case,
                           CPU_BOOLEAN   hex_colon_sep,
                           RTOS_ERR     *p_err)

Arguments#

p_addr_mac

Pointer to a memory buffer that contains the MAC address.

p_addr_mac_ascii

Pointer to an ASCII character array that will receive the return MAC

hex_lower_case

  • DEF_NO Format alphabetic hexadecimal characters in upper case.

  • DEF_YES Format alphabetic hexadecimal characters in lower case.

hex_colon_sep

  • DEF_NO Separate hexadecimal values with a hyphen character.

  • DEF_YES Separate hexadecimal values with a colon character.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. (a)

    1. RFC #1700, Section 'ETHERNET VENDOR ADDRESS COMPONENTS' states that "Ethernet addresses ... should be written hyphenated by octets (e.g., 12-34-56-78-9A-BC)".

    2. In other words, the (Ethernet) MAC address notation separates six hexadecimal octet values by the hyphen character ('-') or by the colon character (':'). Each hexadecimal value represents one octet of the MAC address starting with the most significant octet in network-order.

    (b)

    1. The return MAC address ASCII string formats EXACTLY six hexadecimal values separated by EXACTLY five hyphen characters or colon characters and terminated with the NULL character.

    2. The size of the ASCII character array that will receive the returned MAC address ASCII string MUST be greater than or equal to NET_ASCII_LEN_MAX_ADDR_MAC.

  2. (a) The size of the memory buffer that contains the MAC address SHOULD be greater than or equal to NET_ASCII_NBR_OCTET_ADDR_MAC.

NetASCII_Str_to_IP()#

Description#

Converts a string representation of an IP address (IPv4 or IPv6) to its TCP/IP stack intern representation.

Files#

net_ascii.h/net_ascii.c

Prototype#

NET_IP_ADDR_FAMILY  NetASCII_Str_to_IP (CPU_CHAR    *p_addr_ip_ascii,
                                        void        *p_addr,
                                        CPU_INT08U   addr_max_len,
                                        RTOS_ERR    *p_err)

Arguments#

p_addr_ip_ascii

Pointer to an ASCII string that contains a decimal IP address.

p_addr

Pointer to the variable that will received the converted IP address.

addr_max_len

Size of the variable that will received the converted IP address:

  • NET_IPv4_ADDR_SIZE

  • NET_IPv6_ADDR_SIZE

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

The IP family of the converted address, if no errors:

  • NET_IP_ADDR_FAMILY_IPv4

  • NET_IP_ADDR_FAMILY_IPv6

Otherwise,

NET_IP_ADDR_FAMILY_UNKNOWN

Notes / Warnings#

None.

NetASCII_Str_to_IPv4()#

Description#

Converts an IPv4 address ASCII string in dotted-decimal notation to a network protocol IPv4 address in host-order.

Files#

net_ascii.h/net_ascii.c

Prototype#

NET_IPv4_ADDR  NetASCII_Str_to_IPv4 (CPU_CHAR  *p_addr_ip_ascii,
                                     RTOS_ERR  *p_err)

Arguments#

p_addr_ip_ascii

Pointer to an ASCII string that contains a dotted-decimal IPv4 address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

Host-order IPv4 address represented by ASCII string, if NO error(s). NET_IPv4_ADDR_NONE, otherwise.

Notes / Warnings#

  1. (a)

    1. RFC #1983 states that "dotted decimal notation ... refers [to] IP addresses of the form A.B.C.D; where each letter represents, in decimal, one byte of a four byte IP address".

    2. In other words, the dotted-decimal IP address notation separates four decimal octet values by the dot (or period) character ('.'). Each decimal value represents one octet of the IP address starting with the most significant octet in network-order.

      IP Address Examples : 192.168.1.64 = 0xC0A80140

    (b) Therefore, the dotted-decimal IP address ASCII string MUST :

    1. Include ONLY decimal values and the dot, or period, character ('.') ; ALL other characters are trapped as invalid, including any leading or trailing characters.

    2. Include UP TO four decimal values separated by UP TO three dot characters and MUST be terminated with the NULL character.

    3. Ensure that each decimal value's number of decimal digits, including leading zeros, does NOT exceed the maximum number of digits(10).

      (A) However, any decimal value's number of decimal digits, including leading zeros, MAY be less than the maximum number of digits.

    4. Ensure that each decimal value does NOT exceed the maximum value for its form:

      1. a.b.c.d - 255.255.255.255

      2. a.b.c - 255.255.65535

      3. a.b - 255.16777215

      4. a - 4294967295

  2. To avoid possible integer arithmetic overflow, the IP address octet arithmetic result MUST be declared as an integer data type with a greater resolution (i.e., greater number of bits) than the IP address octet data type(s).

NetASCII_Str_to_IPv6()#

Description#

Converts an IPv6 address ASCII string in common-decimal notation to a network protocol IPv6 address in host-order.

Files#

net_ascii.h/net_ascii.c

Prototype#

NET_IPv6_ADDR  NetASCII_Str_to_IPv6 (CPU_CHAR  *p_addr_ip_ascii,
                                     RTOS_ERR  *p_err)

Arguments#

p_addr_ip_ascii

Pointer to an ASCII string that contains a common-decimal IPv6 address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

Host-order IPv6 address represented by ASCII string, if NO error(s). NET_IPv6_ADDR_NONE, otherwise.

Notes / Warnings#

None.

NetASCII_Str_to_MAC()#

Description#

Converts an Ethernet MAC address ASCII string to an Ethernet MAC address.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_Str_to_MAC (CPU_CHAR    *p_addr_mac_ascii,
                           CPU_INT08U  *p_addr_mac,
                           RTOS_ERR    *p_err)

Arguments#

p_addr_mac_ascii

Pointer to an ASCII string that contains a MAC address.

p_addr_mac

Pointer to a memory buffer that will receive the converted MAC address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

None.

Notes / Warnings#

  1. (a)

    1. RFC #1700, Section 'ETHERNET VENDOR ADDRESS COMPONENTS' states that "Ethernet addresses ... should be written hyphenated by octets (e.g., 12-34-56-78-9A-BC)".

    2. In other words, the (Ethernet) MAC address notation separates six hexadecimal octet values by the hyphen character ('-') or by the colon character (':'). Each hexadecimal value represents one octet of the MAC address starting with the most significant octet in network-order.

    (b) Therefore, the MAC address ASCII string MUST :

    1. Include ONLY hexadecimal values and the hyphen character ('-') or the colon character (':') ; ALL other characters are trapped as invalid, including any leading or trailing characters.

    2. Include EXACTLY six hexadecimal values separated by EXACTLY five hyphen characters or colon characters and MUST be terminated with the NULL character.

    3. Ensure that each hexadecimal value's number of digits does NOT exceed the maximum number of digits (2.).

      (A) However, any hexadecimal value's number of digits MAY be less than the maximum number of digits.

  2. (a) The size of the memory buffer that will receive the converted MAC address MUST be greater than or equal to NET_ASCII_NBR_OCTET_ADDR_MAC.

    (b) MAC address memory buffer array accessed by octets.

    (c) MAC address memory buffer array cleared in case of any error(s).

Network Buffer API#

Function Name

Description

NetBuf_PoolStatGet()

Get an interface’s Network Buffers’ statistics pool.

NetBuf_PoolStatResetMaxUsed()

Reset an interface’s Network Buffers’ statistics pool’s maximum number of entries used.

NetBuf_RxLargePoolStatGet()

Get an interface’s large receive buffers’ statistics pool.

NetBuf_RxLargePoolStatResetMaxUsed()

Reset an interface’s large receive buffers’ statistics pool’s maximum number of entries used.

NetBuf_TxLargePoolStatGet()

Get an interface’s large transmit buffers’ statistics pool.

NetBuf_TxLargePoolStatResetMaxUsed()

Reset an interface’s large transmit buffers’ statistics pool’s maximum number of entries used.

NetBuf_TxSmallPoolStatGet()

Get an interface’s small transmit buffers’ statistics pool.

NetBuf_TxSmallPoolStatResetMaxUsed()

Reset an interface’s small transmit buffers’ statistics pool’s maximum number of entries used.

NetBuf_PoolStatGet()#

Description#

Gets the network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_PoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

  • Network buffer statistics pool, if NO error(s).

  • NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_PoolStatResetMaxUsed()#

Description#

Resets the network buffer statistics pool's maximum number of used entries.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_PoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

NetBuf_RxLargePoolStatGet()#

Description#

Gets the large receive network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_RxLargePoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

Large receive network buffer statistics pool, if NO error(s). NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_RxLargePoolStatResetMaxUsed()#

Description#

Resets the large receive network buffer statistics pool's maximum number of entries used.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_RxLargePoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

NetBuf_TxLargePoolStatGet()#

Description#

Gets the large transmit network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_TxLargePoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

  • Large transmit network buffer statistics pool, if NO error(s).

  • NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_TxLargePoolStatResetMaxUsed()#

Description#

Resets the large receive network buffer statistics pool's maximum number of entries used.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_TxLargePoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

NetBuf_TxSmallPoolStatGet()#

Description#

Gets the small transmit network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_TxSmallPoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

  • Small transmit network buffer statistics pool, if NO error(s).

  • NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_TxSmallPoolStatResetMaxUsed()#

Description#

Resets the small transmit network buffer statistics pool's maximum number of entries used.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_TxSmallPoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

Network Connection API#

Function Name

Description

NetConn_CfgAccessedTh()

Configure network connection access promotion threshold.

NetConn_PoolStatGet()

Get Network Connections’ statistics pool.

NetConn_PoolStatResetMaxUsed()

Reset Network Connections’ statistics pool’s maximum number of entries used.

NetConn_CfgAccessedTh()#

Description#

Configures the network connection access promotion threshold.

Files#

net_conn.h/net_conn.c

Prototype#

CPU_BOOLEAN  NetConn_CfgAccessedTh (CPU_INT16U  nbr_access)

Arguments#

nbr_access

Desired number of accesses before network connection is promoted.

Returned Value#

  • DEF_OK, network connection access promotion threshold configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetConn_PoolStatGet()#

Description#

Gets the network connection statistics pool.

Files#

net_conn.h/net_conn.c

Prototype#

NET_STAT_POOL  NetConn_PoolStatGet (void)

Arguments#

Returned Value#

  • Network connection statistics pool, if NO error(s).

  • NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetConn_PoolStatResetMaxUsed()#

Description#

Resets the network connection statistics pool's maximum number of entries used.

Files#

net_conn.h/net_conn.c

Prototype#

void  NetConn_PoolStatResetMaxUsed (void)

Arguments#

Returned Value#

None.

Notes / Warnings#

None.

Network Timer API#

Function Name

Description

NetTmr_PoolStatGet()

Gets the network timer statistics pool.

NetTmr_PoolStatResetMaxUsed()

Resets the network timer statistics pool's maximum number of entries used.

NetTmr_PoolStatGet()#

Description#

Gets the network timer statistics pool.

Files#

net_tmr.h/net_tmr.c

Prototype#

NET_STAT_POOL  NetTmr_PoolStatGet (void)

Arguments#

Returned Value#

Network timer statistics pool, if NO error(s). NULL statistics pool, otherwise.

Notes / Warnings#

  1. NetTmr_PoolStatGet() blocked until network initialization completes.

  2. 'NetTmr_PoolStat' MUST ALWAYS be accessed exclusively in critical sections.

NetTmr_PoolStatResetMaxUsed()#

Description#

Resets the network timer statistics pool's maximum number of entries used.

Files#

net_tmr.h/net_tmr.c

Prototype#

void  NetTmr_PoolStatResetMaxUsed (void)

Arguments#

Returned Value#

None.

Notes / Warnings#

  1. NetTmr_PoolStatResetMaxUsed() blocked until network initialization completes.

    However, since 'NetTmr_PoolStat' is reset when network initialization completes; NO error is returned.

Network Interface API#

Function Name

Description

NetIF_Add()

Add a network device and hardware as a network interface.

NetIF_AddrHW_Get()

Get network interface’s hardware address.

NetIF_AddrHW_IsValid()

Validate a network interface hardware address.

NetIF_AddrHW_Set()

Set network interface’s hardware address.

NetIF_CfgPerfMonPeriod()

Configure the network interface Performance Monitor Handler timeout.

NetIF_CfgPhyLinkPeriod()

Configure network interface Physical Link State Handler timeout.

NetIF_GetExtAvailCtr()

Returns the number of external interface configured.

NetIF_GetNbrBaseCfgd()

Gets the interface base number (first interface ID).

NetIF_GetRxDataAlignPtr()

Get an aligned pointer into a receive application data buffer.

NetIF_GetTxDataAlignPtr()

Get an aligned pointer into a transmit application data buffer.

NetIF_TypeGet()

Get the network interface type.

NetIF_IO_Ctrl()

Handle network interface and/or device specific (I/O) control(s).

NetIF_IsEn()

Validate network interface as enabled.

NetIF_IsEnCfgd()

Validate configured network interface as enabled.

NetIF_ISR_Handler()

Handle a network interface’s device interrupts.

NetIF_IsValid()

Validate network interface number.

NetIF_IsValidCfgd()

Validate configured network interface number.

NetIF_LinkStateGet()

Get network interface’s last known physical link state.

NetIF_LinkStateSubscribe()

Subscribe to get notified when an interface link state changes.

NetIF_LinkStateUnsubscribe()

Unsubscribe to get notified when interface link state changes.

NetIF_LinkStateWaitUntilUp()

Wait for a network interface's physical link state to be UP .

NetIF_MTU_Get()

Get network interface’s MTU.

NetIF_MTU_Set()

Set network interface’s MTU.

NetIF_Start()

Start a network interface.

NetIF_Stop()

Stop a network interface.

NetIF_TxSuspendTimeoutGet_ms()

Gets the network interface transmit suspend timeout value.

NetIF_TxSuspendTimeoutSet()

Sets the network interface transmit suspend timeout value.

NetIF_WaitSetupReady()

Wait for the network interface setup to be complete.

NetIF_Add()#

This function is DEPRECATED and will be removed in a future version of this product. Instead, use NetIF_Ether_Add() or NetIF_WiFi_Add().

Description#

Add & initialize a specific instance of a network interface.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_NBR  NetIF_Add (void      *p_if_api,
                       void      *p_dev_api,
                       void      *p_dev_bsp,
                       void      *p_dev_cfg,
                       void      *p_ext_api,
                       void      *p_ext_cfg,
                       RTOS_ERR  *p_err)

Arguments#

p_if_api

Pointer to specific network interface API.

p_dev_api

Pointer to specific network device driver API.

p_dev_bsp

Pointer to specific network device board-specific API.

p_dev_cfg

Pointer to specific network device hardware configuration.

p_ext_api

Pointer to specific network extension layer API.

p_ext_cfg

Pointer to specific network extension layer configuration.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

  • Interface number of the added interface, if NO error(s).

  • NET_IF_NBR_NONE, otherwise.

Notes / Warnings#

The first network interface added and started is the default interface used for all default communication.

When a PHY layer is present, the PHY API and configuration need to be indicate in the p_ext_api and p_ext_cfg arguments.

NetIF_AddrHW_Get()#

Description#

Gets the network interface's hardware address.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_AddrHW_Get (NET_IF_NBR   if_nbr,
                        CPU_INT08U  *p_addr_hw,
                        CPU_INT08U  *p_addr_len,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get the hardware address.

p_addr_hw

Pointer to a variable that will receive the hardware address.

p_addr_len

Pointer to a variable that will receive the address length.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

The hardware address is returned in network-order; i.e., the pointer to the hardware address points to the highest-order octet.

NetIF_AddrHW_IsValid()#

Description#

Validates the network interface's hardware address.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_AddrHW_IsValid (NET_IF_NBR   if_nbr,
                                   CPU_INT08U  *p_addr_hw,
                                   RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to validate the hardware address.

p_addr_hw

Pointer to an interface's hardware address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, if hardware address is valid.

  • DEF_NO, otherwise.

Notes / Warnings#

The hardware address MUST be in network-order; i.e., the pointer to the hardware address MUST point to the highest-order octet.

NetIF_AddrHW_Set()#

Description#

Sets the network interface's hardware address.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_AddrHW_Set (NET_IF_NBR   if_nbr,
                        CPU_INT08U  *p_addr_hw,
                        CPU_INT08U   addr_len,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to set the hardware address.

p_addr_hw

Pointer to the hardware address.

addr_len

Length of the hardware address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

  1. The hardware address MUST be in network-order; i.e., the pointer to the hardware address MUST point to the highest-order octet.

  2. The interface MUST be stopped BEFORE setting a new hardware address, which does NOT take effect until the interface is re-started.

NetIF_CfgPerfMonPeriod()#

Description#

Configures the Network Interface Performance Monitor Handler time (i.e., scheduling period).

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_CfgPerfMonPeriod (CPU_INT16U  time_ms)

Arguments#

time_ms

Desired value for Network Interface Performance Monitor Handler time (in milliseconds).

Returned Value#

  • DEF_OK, Network Interface Performance Monitor Handler time is configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured time does NOT reschedule the next performance monitor handling; it configures the scheduling of all subsequent performance monitor handling.

NetIF_CfgPhyLinkPeriod()#

Description#

Configures the Network Interface Physical Link State Handler time (i.e., scheduling period).

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_CfgPhyLinkPeriod (CPU_INT16U  time_ms)

Arguments#

time_ms

Desired value for Network Interface Physical Link State Handler time (in milliseconds).

Returned Value#

  • DEF_OK, Network Interface Physical Link State Handler timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured time does NOT reschedule the next physical link state handling; it configures the scheduling of all subsequent physical link state handling.

NetIF_GetExtAvailCtr()#

Description#

Returns the number of external interface configured.

Files#

net_if.h/net_if.c

Prototype#

CPU_INT08U  NetIF_GetExtAvailCtr (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

Number of external interfaces available.

Notes / Warnings#

None.

NetIF_GetNbrBaseCfgd()#

Description#

Gets the interface base number (first interface ID).

Files#

net_if.h/net_if.c

Prototype#

NET_IF_NBR  NetIF_GetNbrBaseCfgd (void)

Arguments#

None.

Returned Value#

Interface base number.

Notes / Warnings#

None.

NetIF_GetRxDataAlignPtr()#

Description#

Gets and places aligned pointer into a receive application data buffer.

Files#

net_if.h/net_if.c

Prototype#

void  *NetIF_GetRxDataAlignPtr (NET_IF_NBR   if_nbr,
                                void        *p_data,
                                RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get a receive application buffer's aligned data pointer.

p_data

Pointer to receive application data buffer to get an aligned pointer into.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • Pointer to aligned receive application data buffer address, if NO error(s).

  • Pointer to NULL, otherwise.

Notes / Warnings#

  1. (a)

    1. (A) Optimal alignment between application data buffer(s) and network interface's network buffer data area(s) is NOT guaranteed and is only possible if the following condition is true :

      1. Network interface's network buffer data area(s) MUST be aligned to a multiple of the CPU's data word size.

      (B) Otherwise, a single and fixed alignment between application data buffer(s) and network interface's buffer data area(s) is NOT possible.

    2. (A) Even when application data buffers and network buffer data areas are aligned in the best case; optimal alignment is NOT guaranteed for every read/write of data to/from application data buffers and network buffer data areas.

      For any single read/write of data to/from application data buffers and network buffer data areas, optimal alignment only occurs if the following conditions are true :

      1. Data read/written to/from application data buffer(s) to network buffer data area(s) MUST start on addresses with the same relative offset from CPU word-aligned addresses.

        In other words, the modulus of the specific read/write address in the application data buffer with the CPU's data word size MUST be equal to the modulus of the specific read/write address in the network buffer data area with the CPU's data word size.

        This condition MIGHT NOT be satisfied whenever :

        1. Data is read/written to/from fragmented packets

        2. Data is NOT maximally read/written to/from stream-type packets (e.g., TCP data segments)

        3. Packets include variable number of header options (e.g., IP options)

      (B) However, even though optimal alignment between application data buffers and network buffer data areas is NOT guaranteed for every read/write; optimal alignment SHOULD occur more frequently leading to improved network data throughput.

    (b) Since the first aligned address in the application data buffer may be 0 to (CPU_CFG_DATA_SIZE - 1) octets after the application data buffer's starting address, the application data buffer SHOULD allocate and reserve an additional (CPU_CFG_DATA_SIZE - 1) number of octets.

    However, the application data buffer's effective, usable size is still limited to its original declared size (before reserving additional octets) and SHOULD NOT be increased by the additional, reserved octets.

NetIF_GetTxDataAlignPtr()#

Description#

Gets and places the aligned pointer into a transmit application data buffer.

Files#

net_if.h/net_if.c

Prototype#

void  *NetIF_GetTxDataAlignPtr (NET_IF_NBR   if_nbr,
                                void        *p_data,
                                RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get a transmit application buffer's aligned data pointer.

p_data

Pointer to transmit the application data buffer into which to get an aligned pointer.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • Pointer to aligned transmit application data buffer address, if NO error(s).

  • Pointer to NULL, otherwise.

Notes / Warnings#

  1. (a)

    1. (A) Optimal alignment between application data buffer(s) and network interface's network buffer data area(s) is NOT guaranteed and is only possible if the following condition is true :

      1. Network interface's network buffer data area(s) MUST be aligned to a multiple of the CPU's data word size.

      (B) Otherwise, a single and fixed alignment between application data buffer(s) and network interface's buffer data area(s) is NOT possible.

    2. (A) Even when application data buffers and network buffer data areas are aligned in the best case; optimal alignment is NOT guaranteed for every read/write of data to/from application data buffers and network buffer data areas.

      For any single read/write of data to/from application data buffers and network buffer data areas, optimal alignment only occurs if all of the following conditions are true :

      1. Data read/written to/from application data buffer(s) to network buffer data area(s) MUST start on addresses with the same relative offset from CPU word-aligned addresses.

      In other words, the modulus of the specific read/write address in the application data buffer with the CPU's data word size MUST be equal to the modulus of the specific read/write address in the network buffer data area with the CPU's data word size.

      This condition MIGHT NOT be satisfied whenever :

      1. Data is read/written to/from fragmented packets

      2. Data is NOT maximally read/written to/from stream-type packets (e.g. TCP data segments)

      3. Packets include variable number of header options (e.g. IP options)

      (B) However, even though optimal alignment between application data buffers and network buffer data areas is NOT guaranteed for every read/write; optimal alignment SHOULD occur more frequently leading to improved network data throughput.

    (b) Since the first aligned address in the application data buffer may be 0 to (CPU_CFG_DATA_SIZE - 1) octets after the application data buffer's starting address, the application data buffer SHOULD allocate and reserve an additional (CPU_CFG_DATA_SIZE - 1) number of octets.

NetIF_IO_Ctrl()#

Description#

  1. Handles the network interface and/or device specific (I/O) control(s) :

    (a) Device link :

    1. Get the device link info

    2. Get the device link state

    3. Update the device link state

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_IO_Ctrl (NET_IF_NBR   if_nbr,
                     CPU_INT08U   opt,
                     void        *p_data,
                     RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to handle the (I/O) controls.

opt

Desired I/O control option code to perform. Additional control options may be defined by the device driver :

  • NET_IF_IO_CTRL_LINK_STATE_GET Get the device's current physical link state, 'UP' or 'DOWN'.

  • NET_IF_IO_CTRL_LINK_STATE_GET_INFO Get the device's detailed physical link state information.

  • NET_IF_IO_CTRL_LINK_STATE_UPDATE Update the device's current physical link state.

  • NET_IF_IO_CTRL_EEE_GET_INFO Retrieve information if EEE is enabled or not.

  • NET_IF_IO_CTRL_EEE Enable/Disable EEE support on the interface.

p_data

Pointer to variable that will receive possible I/O control data.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

  1. 'p_data' MUST point to a variable or memory buffer that is sufficiently sized AND aligned to receive any return data. The options are as follows :

    (a) NET_IF_IO_CTRL_LINK_STATE_GET:

    1. For Ethernet or Wireless interface: p_data MUST point to a CPU_BOOLEAN variable.

    (b) NET_IF_IO_CTRL_LINK_STATE_GET_INFO NET_IF_IO_CTRL_LINK_STATE_UPDATE

    1. For an Ethernet interface: p_data MUST point to a variable of data type NET_DEV_LINK_ETHER.

    2. For a Wireless interface: p_data MUST point to a variable of data type NET_DEV_LINK_WIFI.

NetIF_ISR_Handler()#

Description#

Handle network interface's device interrupt service routine (ISR) function(s).

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_ISR_Handler (NET_IF_NBR         if_nbr,
                         NET_DEV_ISR_TYPE   type,
                         RTOS_ERR          *p_err)

Arguments#

if_nbr

Network interface number to handle ISR(s).

type

Device interrupt type(s) to handle :

  • NET_DEV_ISR_TYPE_UNKNOWN Handle unknown device ISR(s).

  • NET_DEV_ISR_TYPE_RX Handle device receive ISR(s).

  • NET_DEV_ISR_TYPE_RX_OVERRUN Handle device receive overrun ISR(s).

  • NET_DEV_ISR_TYPE_TX_RDY Handle device transmit ready ISR(s).

  • NET_DEV_ISR_TYPE_TX_COMPLETE Handle device transmit complete ISR(s).

p_err

Pointer to variable that will receive the return error code from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

none.

Notes / Warnings#

Device driver(s)' Board Support Package (BSP) Interrupt Service Routine (ISR) handler(s). This function is a network interface (IF) to network device function & SHOULD be called only by appropriate network device driver ISR handler function(s).

NetIF_IsEn()#

Description#

Validates the network interface as enabled.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsEn (NET_IF_NBR   if_nbr,
                         RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, network interface is valid and enabled.

  • DEF_NO, network interface is invalid or disabled.

Notes / Warnings#

None.

NetIF_IsEnCfgd()#

Description#

Validates the configured network interface as enabled.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsEnCfgd (NET_IF_NBR   if_nbr,
                             RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, network interface is valid and enabled.

  • DEF_NO, network interface is invalid or disabled.

Notes / Warnings#

None.

NetIF_IsValid()#

Description#

Validates the network interface number.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsValid (NET_IF_NBR   if_nbr,
                            RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

  • DEF_YES, network interface number is valid.

  • DEF_NO, network interface number is invalid / NOT yet configured.

Notes / Warnings#

None.

NetIF_IsValidCfgd()#

Description#

Validates the configured network interface number.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsValidCfgd (NET_IF_NBR   if_nbr,
                                RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

  • DEF_YES, network interface number is valid.

  • DEF_NO, network interface number is invalid / NOT yet configured or reserved.

Notes / Warnings#

None.

NetIF_LinkStateGet()#

Description#

Gets the network interface's last known physical link state.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_LINK_STATE  NetIF_LinkStateGet (NET_IF_NBR   if_nbr,
                                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get last known physical link state.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • NET_IF_LINK_UP, if NO error(s) and network interface's last known physical link state was 'UP'.

  • NET_IF_LINK_DOWN, otherwise.

Notes / Warnings#

NetIF_LinkStateGet() only returns a network interface's last known physical link state since enabled network interfaces' physical link states are only periodically updated.

NetIF_LinkStateSubscribe()#

Description#

Subscribes to get notified when an interface link state changes.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_LinkStateSubscribe (NET_IF_NBR                    if_nbr,
                                NET_IF_LINK_SUBSCRIBER_FNCT   fcnt,
                                RTOS_ERR                     *p_err)

Arguments#

if_nbr

Network interface number to check the link state.

fcnt

Function to call when the link changes.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

NetIF_LinkStateUnsubscribe()#

Description#

Removes the subscribe function from the link state changes subscription list.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_LinkStateUnsubscribe (NET_IF_NBR                    if_nbr,
                                  NET_IF_LINK_SUBSCRIBER_FNCT   fcnt,
                                  RTOS_ERR                     *p_err)

Arguments#

if_nbr

Specify the Network Interface number to remove the link state check function.

fcnt

Function to remove from subscription list.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_FULL

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_LinkStateWaitUntilUp()#

Description#

Waits for a network interface's link state to be 'UP'.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_LinkStateWaitUntilUp (NET_IF_NBR   if_nbr,
                                         CPU_INT16U   retry_max,
                                         CPU_INT32U   time_dly_ms,
                                         RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to check link state.

retry_max

Maximum number of consecutive wait retries.

time_dly_ms

Transitory delay value, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_IF_LINK_DOWN

Returned Value#

  • NET_IF_LINK_UP, if NO error(s) and network interface's link state is 'UP'.

  • NET_IF_LINK_DOWN, otherwise.

Notes / Warnings#

If a non-zero number of retries is requested, a non-zero time delay SHOULD also be requested; otherwise, all retries will likely fail immediately since no time will elapse to allow the network interface's link state to successfully be 'UP'.

NetIF_MTU_Get()#

Description#

Gets the network interface's MTU.

Files#

net_if.h/net_if.c

Prototype#

NET_MTU  NetIF_MTU_Get (NET_IF_NBR   if_nbr,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get MTU.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • Network interface's MTU, if NO error(s).

  • 0, otherwise.

Notes / Warnings#

None.

NetIF_MTU_Set()#

Description#

Sets the network interface's MTU.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_MTU_Set (NET_IF_NBR   if_nbr,
                     NET_MTU      mtu,
                     RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to set MTU.

mtu

Desired maximum transmission unit size to configure.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_NbrGetFromName()#

Description#

Get network interface number from it's name.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_NBR  NetIF_NbrGetFromName (CPU_CHAR  *p_name)

Arguments#

p_name

Pointer to a string containing interface controller's name.

Returned Value#

Network interface number associated with controller name.

Notes / Warnings#

None.

NetIF_Start()#

This function is DEPRECATED and will be removed in a future version of this product. Instead, use NetIF_Ether_Start() or NetIF_WiFi_Start() .

Description#

Start a network interface.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_Start (NET_IF_NBR   if_nbr,
                   RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to start.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_RX

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

NetIF_Stop()#

Description#

Stop a network interface.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_Stop (NET_IF_NBR   if_nbr,
                  RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to stop.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

none.

Notes / Warnings#

None.

NetIF_TxSuspendTimeoutGet_ms()#

Description#

Gets the network interface transmit suspend timeout value.

Files#

net_if.h/net_if.c

Prototype#

CPU_INT32U  NetIF_TxSuspendTimeoutGet_ms (NET_IF_NBR   if_nbr,
                                          RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to get timeout value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • Network transmit suspend timeout value (in milliseconds), if NO error(s).

  • 0, otherwise.

Notes / Warnings#

None.

NetIF_TxSuspendTimeoutSet()#

Description#

Sets the network interface transmit suspend timeout value.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_TxSuspendTimeoutSet (NET_IF_NBR   if_nbr,
                                 CPU_INT32U   timeout_ms,
                                 RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to set timeout value.

timeout_ms

Timeout value (in milliseconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_TypeGet()#

Description#

Gets the network interface's type.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_TYPE  NetIF_TypeGet (NET_IF_NBR   if_nbr,
                            RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get the type.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

Network interface's type :

  • NET_IF_TYPE_ETHER

  • NET_IF_TYPE_WIFI

  • NET_IF_TYPE_NONE, in case of error

Notes / Warnings#

None.

NetIF_WaitSetupReady()#

Description#

Wait for the network interface setup to be complete.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_WaitSetupReady (NET_IF_NBR        if_nbr,
                            NET_IF_APP_INFO  *p_info,
                            CPU_INT32U        timeout_ms,
                            RTOS_ERR         *p_err)

Arguments#

if_nbr

Network interface number on which to wait.

p_info

Pointer to structure in which the setup information will be copied. DEF_NULL, to not receive the setup information.

timeout_ms

Timeout, in milliseconds. A value of 0 will never timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_ABORT

Returned Value#

None.

Notes / Warnings#

None.

Ethernet Network Interface API#

Macro Name

Description

NET_CTRLR_ETHER_REG()

Registers an Ethernet controller to the platform manager.

Function Name

Description

NetIF_Ether_Add()

Add & initialize a specific instance of a network Ethernet interface.

NetIF_Ether_Start()

Start an Ethernet type interface

NET_CTRLR_ETHER_REG()#

Description#

Registers a Ethernet controller to the platform manager.

Files#

net_if_ether.h

Prototype#

NET_CTRLR_ETHER_REG(name, ctlr_info_ptr)

Arguments#

name

Unique name for the Ethernet controller. It is recommended to follow the standard "etherX" where X is a digit.

ctlr_info_ptr

Pointer to the Ethernet controller information structure of type NET_IF_ETHER_CTRLR_INFO.

Returned Value#

None.

Notes / Warnings#

This macro should normally be called from the BSP.

NetIF_Ether_Add()#

Description#

Add & initialize a specific instance of a network Ethernet interface.

Files#

net_if_ether.h/net_if_ether.c

Prototype#

NET_IF_NBR  NetIF_Ether_Add (CPU_CHAR        *p_name,
                             NET_IF_BUF_CFG  *p_buf_cfg,
                             MEM_SEG         *p_mem_seg,
                             RTOS_ERR        *p_err)

Arguments#

p_name

String identifier for the Ethernet interface to add.

p_buf_cfg

Pointer to buffer configuration.

p_mem_seg

Memory segment from which internal data will be allocated. If DEF_NULL, it will be allocated from the global heap.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

Interface number of the added interface, if NO error(s). NET_IF_NBR_NONE, otherwise.

Notes / Warnings#

When a non-null buffer configuration is passed, a copy of the device configuration that come from the BSP is completed. It is recommended to reduce the memory usage to modify the static configuration specified in the BSP.

NetIF_Ether_Start()#

Description#

Start an Ethernet type interface :

Files#

net_if_ether.h/net_if_ether.c

Prototype#

void  NetIF_Ether_Start (NET_IF_NBR         if_nbr,
                         NET_IF_ETHER_CFG  *p_cfg,
                         RTOS_ERR          *p_err)

Arguments#

if_nbr

Network interface number to start.

p_cfg

Pointer to interface configuration. DEF_NULL, to just start the interface without Address or DHCP setup.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_FAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_STR_ADDR_INVALID

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_IS_OWNER

Returned Value#

None.

Notes / Warnings#

None.

Wireless Network Interface API#

Macro Name

Description

NET_CTRLR_WIFI_SPI_REG()

Registers an external WiFi controller connected via SPI to the platform manager.

Function Name

Description

NetIF_WiFi_Add()

Add & initialize a specific instance of a network WiFi interface.

NetIF_WiFi_CreateAP()

Create a wireless ad-hoc access point.

NetIF_WiFi_GetPeerInfo()

Gets the peer info connected to the access point (when acting as an access point).

NetIF_WiFi_Join()

Join a wireless access point.

NetIF_WiFi_Leave()

Leave the access point previously joined.

NetIF_WiFi_Scan()

Scan available wireless access point.

NetIF_WiFi_Start()

Start a Wi-Fi-type interface.

NET_CTRLR_WIFI_SPI_REG()#

Description#

Registers a WiFi controller to the platform manager. Those kind of WiFi Controllers are outside the MCU and connected via a SPI interface to the MCU.

Files#

net_if_wifi.h

Prototype#

NET_CTRLR_WIFI_SPI_REG(part_name, spi_name, part_info_ptr, bsp_api_ptr, slave_id)

Arguments#

part_name

Unique name for the WiFi controller/part. It is recommended to follow the standard "wifiX" where X is a digit.

spi_name

Unique name for the SPI bus to use for the WiFi slave. The SPI bus must already have been registered to the Platform Manager. It is recommended to follow the standard "spiX" where X is a digit.

part_info_ptr

Pointer to the WiFi part hardware information structure of type NET_IF_WIFI_PART_INFO.

bsp_api_ptr

Pointer to the BSP API structure for the WiFi controller.

slave_id

Slave ID of the WiFi controller on the SPI bus.

Returned Value#

None.

Notes / Warnings#

This macro should normally be called from the BSP.

NetIF_WiFi_Add()#

Description#

Add & initialize a specific instance of a network WiFi interface.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

NET_IF_NBR  NetIF_WiFi_Add (       CPU_CHAR        *p_name,
                            const  NET_IF_BUF_CFG  *p_cfg,
                                   void            *p_ext_cfg,
                                   MEM_SEG         *p_mem_seg,
                                   RTOS_ERR        *p_err)

Arguments#

p_name

String identifier for the WiFi interface to add.

p_cfg

Pointer to buffer configuration.

p_ext_cfg

Pointer to extended configuration. DEF_NULL, if not need by WiFi part.

p_mem_seg

Memory segment from which internal data will be allocated. If DEF_NULL, it will be allocated from the global heap.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

  • Interface number of the added interface, if NO error(s).

  • NET_IF_NBR_NONE, otherwise.

Notes / Warnings#

None.

NetIF_WiFi_CreateAP()#

Description#

Creates a wireless access point.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_CreateAP (NET_IF_NBR                  if_nbr,
                           NET_IF_WIFI_NET_TYPE        net_type,
                           NET_IF_WIFI_DATA_RATE       data_rate,
                           NET_IF_WIFI_SECURITY_TYPE   security_type,
                           NET_IF_WIFI_PWR_LEVEL       pwr_level,
                           NET_IF_WIFI_CH              ch,
                           NET_IF_WIFI_SSID            ssid,
                           NET_IF_WIFI_PSK             psk,
                           RTOS_ERR                   *p_err)

Arguments#

if_nbr

Wireless network interface number.

net_type

Wireless network type:

  • NET_IF_WIFI_NET_TYPE_INFRASTRUCTURE

  • NET_IF_WIFI_NET_TYPE_ADHOC

data_rate

Wireless date rate to configure:

  • NET_IF_WIFI_DATA_RATE_AUTO

  • NET_IF_WIFI_DATA_RATE_1_MBPS

  • NET_IF_WIFI_DATA_RATE_2_MBPS

  • NET_IF_WIFI_DATA_RATE_5_5_MBPS

  • NET_IF_WIFI_DATA_RATE_6_MBPS

  • NET_IF_WIFI_DATA_RATE_9_MBPS

  • NET_IF_WIFI_DATA_RATE_11_MBPS

  • NET_IF_WIFI_DATA_RATE_12_MBPS

  • NET_IF_WIFI_DATA_RATE_18_MBPS

  • NET_IF_WIFI_DATA_RATE_24_MBPS

  • NET_IF_WIFI_DATA_RATE_36_MBPS

  • NET_IF_WIFI_DATA_RATE_48_MBPS

  • NET_IF_WIFI_DATA_RATE_54_MBPS

  • NET_IF_WIFI_DATA_RATE_MCS0

  • NET_IF_WIFI_DATA_RATE_MCS1

  • NET_IF_WIFI_DATA_RATE_MCS2

  • NET_IF_WIFI_DATA_RATE_MCS3

  • NET_IF_WIFI_DATA_RATE_MCS4

  • NET_IF_WIFI_DATA_RATE_MCS5

  • NET_IF_WIFI_DATA_RATE_MCS6

  • NET_IF_WIFI_DATA_RATE_MCS7

  • NET_IF_WIFI_DATA_RATE_MCS8

  • NET_IF_WIFI_DATA_RATE_MCS9

  • NET_IF_WIFI_DATA_RATE_MCS10

  • NET_IF_WIFI_DATA_RATE_MCS11

  • NET_IF_WIFI_DATA_RATE_MCS12

  • NET_IF_WIFI_DATA_RATE_MCS13

  • NET_IF_WIFI_DATA_RATE_MCS14

  • NET_IF_WIFI_DATA_RATE_MCS15

security_type

Wireless security type:

  • NET_IF_WIFI_SECURITY_OPEN

  • NET_IF_WIFI_SECURITY_WEP

  • NET_IF_WIFI_SECURITY_WPA

  • NET_IF_WIFI_SECURITY_WPA2

pwr_level

Wireless radio power to configure:

  • NET_IF_WIFI_PWR_LEVEL_LO

  • NET_IF_WIFI_PWR_LEVEL_MED

  • NET_IF_WIFI_PWR_LEVEL_HI

ch

Channel of the wireless network to create:

  • NET_IF_WIFI_CH_1

  • NET_IF_WIFI_CH_2

  • NET_IF_WIFI_CH_3

  • NET_IF_WIFI_CH_4

  • NET_IF_WIFI_CH_5

  • NET_IF_WIFI_CH_6

  • NET_IF_WIFI_CH_7

  • NET_IF_WIFI_CH_8

  • NET_IF_WIFI_CH_9

  • NET_IF_WIFI_CH_10

  • NET_IF_WIFI_CH_11

  • NET_IF_WIFI_CH_12

  • NET_IF_WIFI_CH_13

  • NET_IF_WIFI_CH_14

ssid

SSID of the access point to create.

psk

Pre-shared key of the access point.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_WiFi_GetPeerInfo()#

Description#

Gets the peer info connected to the access point (when acting as an access point).

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

CPU_INT16U  NetIF_WiFi_GetPeerInfo (NET_IF_NBR          if_nbr,
                                    NET_IF_WIFI_PEER   *p_buf_peer,
                                    CPU_INT16U          buf_peer_len_max,
                                    RTOS_ERR           *p_err)

Arguments#

if_nbr

Wireless network interface number.

p_buf_peer

Pointer to the buffer to save the peer information.

buf_peer_len_max

Length in bytes of p_buf_peer.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

Number of peers on the network and that are set in the buffer.

Notes / Warnings#

None.

NetIF_WiFi_Join()#

Description#

Joins a wireless access point.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_Join (NET_IF_NBR                  if_nbr,
                       NET_IF_WIFI_NET_TYPE        net_type,
                       NET_IF_WIFI_DATA_RATE       data_rate,
                       NET_IF_WIFI_SECURITY_TYPE   security_type,
                       NET_IF_WIFI_PWR_LEVEL       pwr_level,
                       NET_IF_WIFI_SSID            ssid,
                       NET_IF_WIFI_PSK             psk,
                       RTOS_ERR                   *p_err)

Arguments#

if_nbr

Wireless network interface number.

net_type

Wireless network type:

  • NET_IF_WIFI_NET_TYPE_INFRASTRUCTURE

  • NET_IF_WIFI_NET_TYPE_ADHOC

data_rate

Wireless date rate to configure:

  • NET_IF_WIFI_DATA_RATE_AUTO

  • NET_IF_WIFI_DATA_RATE_1_MBPS

  • NET_IF_WIFI_DATA_RATE_2_MBPS

  • NET_IF_WIFI_DATA_RATE_5_5_MBPS

  • NET_IF_WIFI_DATA_RATE_6_MBPS

  • NET_IF_WIFI_DATA_RATE_9_MBPS

  • NET_IF_WIFI_DATA_RATE_11_MBPS

  • NET_IF_WIFI_DATA_RATE_12_MBPS

  • NET_IF_WIFI_DATA_RATE_18_MBPS

  • NET_IF_WIFI_DATA_RATE_24_MBPS

  • NET_IF_WIFI_DATA_RATE_36_MBPS

  • NET_IF_WIFI_DATA_RATE_48_MBPS

  • NET_IF_WIFI_DATA_RATE_54_MBPS

  • NET_IF_WIFI_DATA_RATE_MCS0

  • NET_IF_WIFI_DATA_RATE_MCS1

  • NET_IF_WIFI_DATA_RATE_MCS2

  • NET_IF_WIFI_DATA_RATE_MCS3

  • NET_IF_WIFI_DATA_RATE_MCS4

  • NET_IF_WIFI_DATA_RATE_MCS5

  • NET_IF_WIFI_DATA_RATE_MCS6

  • NET_IF_WIFI_DATA_RATE_MCS7

  • NET_IF_WIFI_DATA_RATE_MCS8

  • NET_IF_WIFI_DATA_RATE_MCS9

  • NET_IF_WIFI_DATA_RATE_MCS10

  • NET_IF_WIFI_DATA_RATE_MCS11

  • NET_IF_WIFI_DATA_RATE_MCS12

  • NET_IF_WIFI_DATA_RATE_MCS13

  • NET_IF_WIFI_DATA_RATE_MCS14

  • NET_IF_WIFI_DATA_RATE_MCS15

security_type

Wireless security type:

  • NET_IF_WIFI_SECURITY_OPEN

  • NET_IF_WIFI_SECURITY_WEP

  • NET_IF_WIFI_SECURITY_WPA

  • NET_IF_WIFI_SECURITY_WPA2

pwr_level

Wireless radio power to configure:

  • NET_IF_WIFI_PWR_LEVEL_LO

  • NET_IF_WIFI_PWR_LEVEL_MED

  • NET_IF_WIFI_PWR_LEVEL_HI

ssid

SSID of the access point to join.

psk

Pre-shared key of the access point.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

Before join an access point, the access point should have been found during a previous scan.

NetIF_WiFi_Leave()#

Description#

Leaves the access point previously joined.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_Leave (NET_IF_NBR   if_nbr,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Wireless network interface number.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_WiFi_Scan()#

Description#

Scans the available wireless access point.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

CPU_INT16U  NetIF_WiFi_Scan (       NET_IF_NBR         if_nbr,
                                    NET_IF_WIFI_AP    *p_buf_scan,
                                    CPU_INT16U         buf_scan_len_max,
                             const  NET_IF_WIFI_SSID  *p_ssid,
                                    NET_IF_WIFI_CH     ch,
                                    RTOS_ERR          *p_err)

Arguments#

if_nbr

Wireless network interface number.

p_buf_scan

Pointer to a buffer that will receive available access point.

buf_scan_len_max

Maximum number of access point that can be stored

p_ssid

Pointer to a strubg that contains the SSID to scan. DEF_NULL to scan for all access point.

ch

Channel number:

  • NET_IF_WIFI_CH_ALL

  • NET_IF_WIFI_CH_1

  • NET_IF_WIFI_CH_2

  • NET_IF_WIFI_CH_3

  • NET_IF_WIFI_CH_4

  • NET_IF_WIFI_CH_5

  • NET_IF_WIFI_CH_6

  • NET_IF_WIFI_CH_7

  • NET_IF_WIFI_CH_8

  • NET_IF_WIFI_CH_9

  • NET_IF_WIFI_CH_10

  • NET_IF_WIFI_CH_11

  • NET_IF_WIFI_CH_12

  • NET_IF_WIFI_CH_13

  • NET_IF_WIFI_CH_14

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NOT_READY

Returned Value#

Number of wireless access points found.

Notes / Warnings#

None.

NetIF_WiFi_Start()#

Description#

Start an WiFi type interface

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_Start (NET_IF_NBR        if_nbr,
                        NET_IF_WIFI_CFG  *p_cfg,
                        RTOS_ERR         *p_err)

Arguments#

if_nbr

Network interface number to start.

p_cfg

Pointer to interface configuration. DEF_NULL, to just start the interface without Address or DHCP setup.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_FAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_STR_ADDR_INVALID

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_IS_OWNER

Returned Value#

None.

Notes / Warnings#

None.

DHCP Client API#

Function Name

Description

DHCPc_IF_Add

Attaches an interface to the DHCP module and starts the DHCP process on this interface.

DHCPc_IF_Reboot

Reboots the DHCP Client process.

DHCPc_IF_Remove

Stops and removes the DHCP operation on the given network interface.

DHCPc_IF_Add()#

Description#

Attaches an interface to the DHCP module and starts the DHCP process on this interface.

Files#

dhcp_client.h/dhcp_client.c

Prototype#

void  DHCPc_IF_Add (NET_IF_NBR   if_nbr,
                    DHCPc_CFG   *p_cfg,
                    RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number on which DHCP must be performed.

p_cfg

Pointer to the DHCP configuration for the given interface.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

DHCPc_IF_Reboot()#

Description#

Reboots the DHCP Client process.

Files#

dhcp_client.h/dhcp_client.c

Prototype#

void  DHCPc_IF_Reboot (NET_IF_NBR   if_nbr,
                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number on which the DHCP process must be rebooted.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

The reboot process will be completed automatically by the DHCP client process when an interface link state changes. This API is provided if more flexibility is required by the customer application.

DHCPc_IF_Remove()#

Description#

Stops and removes the DHCP operation on the given network interface.

Files#

dhcp_client.h/dhcp_client.c

Prototype#

void  DHCPc_IF_Remove (NET_IF_NBR   if_nbr,
                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number on which the DHCP process must be stopped.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

DNS Client API#

Function Name

Description

DNSc_CacheClrAll

Flushes the DNS cache.

DNSc_CacheClrHost

Removes a host from the cache.

DNSc_CfgServerByAddr

Configures the DNS server to use by default with an address structure.

DNSc_CfgServerByStr

Configures the DNS server to use by default using a string.

DNSc_GetServerByAddr

Gets the default DNS server in an address object format.

DNSc_GetServerByStr

Gets the default DNS server in string format.

DNSc_GetHost

Converts a string representation of a host name to its corresponding IP address using DNS service.

DNSc_GetHostAddrs()

Get a list of IP addresses assigned to a host.

DNSc_FreeHostAddrs()

Free Host addresses allocated by DNS_HostAddrsGet().

DNSc_CacheClrAll()#

Description#

Flushes the DNS cache.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CacheClrAll (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

Returned Value#

None.

Notes / Warnings#

None.

DNSc_CacheClrHost()#

Description#

Removes a host from the cache.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CacheClrHost (CPU_CHAR  *p_host_name,
                         RTOS_ERR  *p_err)

Arguments#

p_host_name

Pointer to a string that contains the host name to remove from the cache.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_NOT_FOUND

Returned Value#

None.

Notes / Warnings#

None.

DNSc_CfgServerByAddr()#

Description#

Configures the DNS server to use by default with an address structure.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CfgServerByAddr (NET_IP_ADDR_OBJ  *p_addr,
                            RTOS_ERR         *p_err)

Arguments#

p_addr

Pointer to the structure that contains the IP address of the DNS server.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

DNSc_CfgServerByStr()#

Description#

Configures the DNS server to use by default using a string.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CfgServerByStr (CPU_CHAR  *p_server,
                           RTOS_ERR  *p_err)

Arguments#

p_server

Pointer to a string that contains the IP address of the DNS server.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

None.

Notes / Warnings#

None.

DNSc_GetHost()#

Description#

Converts a string representation of a host name to its corresponding IP address using DNS service.

Files#

dns_client.h/dns_client.c

Prototype#

DNSc_STATUS  DNSc_GetHost (CPU_CHAR         *p_host_name,
                           NET_IP_ADDR_OBJ  *p_addr_tbl,
                           CPU_INT08U       *p_addr_nbr,
                           DNSc_FLAGS        flags,
                           DNSc_REQ_CFG     *p_cfg,
                           RTOS_ERR         *p_err)

Arguments#

p_host_name

Pointer to a string that contains the host name.

p_addr_tbl

Pointer to the array that will receive the IP address(es).

p_addr_nbr

Pointer to a variable that contains how many addresses can be contained in the array.

flags

DNS client flag:

DNSc_FLAG_NONE

By default, this function is blocking.

DNSc_FLAG_NO_BLOCK

Do not block (only possible if DNSc's task is enabled).

DNSc_FLAG_FORCE_CACHE

Take host from the cache, do not send new DNS request.

DNSc_FLAG_FORCE_RENEW

Force DNS request and remove existing entry in the cache.

DNSc_FLAG_FORCE_RESOLUTION

Force DNS to resolve given host name.

DNSc_FLAG_IPv4_ONLY

Return only the IPv4 address(es).

DNSc_FLAG_IPv6_ONLY

Return only the IPv6 address(es).

p_cfg

Pointer to a request configuration. Should be set to overwrite the default DNS configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

Resolution status: DNSc_STATUS_PENDING Host resolution is pending, call again to see the status. (Processed by DNSc's task) DNSc_STATUS_RESOLVED Host is resolved. DNSc_STATUS_FAILED Host resolution has failed.

  • DNSc_STATUS_PENDING: Host resolution is pending, call again to see the status. (Processed by DNSc's task)

  • DNSc_STATUS_RESOLVED: Host is resolved.

  • DNSc_STATUS_FAILED: Host resolution has failed.

Notes / Warnings#

None.

DNSc_GetHostAddrs()#

Description#

Get a list of IP addresses assigned to a host.

Files#

dns_client.h/dns_client.c

Prototype#

DNSc_STATUS DNSc_GetHostAddrs (CPU_CHAR          *p_host_name,
                               NET_HOST_IP_ADDR **p_addrs,
                               CPU_INT08U        *p_addr_nbr,
                               DNSc_FLAGS         flags,
                               DNSc_REQ_CFG      *p_cfg,
                               RTOS_ERR          *p_err)

Arguments#

p_host_name

Pointer to a string that contains the host name.

p_addrs

Pointer to link list that will receive the IP address(es).

p_addr_nbr

Pointer to a variable that contains how many addresses can be returned.

flags

DNS client flag:

DNSc_FLAG_NONE

By default, this function is blocking.

DNSc_FLAG_NO_BLOCK

Do not block (only possible if DNSc's task is enabled).

DNSc_FLAG_FORCE_CACHE

Take host from the cache, do not send new DNS request.

DNSc_FLAG_FORCE_RENEW

Force DNS request and remove existing entry in the cache.

DNSc_FLAG_FORCE_RESOLUTION

Force DNS to resolve given host name.

DNSc_FLAG_IPv4_ONLY

Return only the IPv4 address(es).

DNSc_FLAG_IPv6_ONLY

Return only the IPv6 address(es).

p_cfg

Pointer to a request configuration. Should be set to overwrite the default DNS configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

DNSc_FreeHostAddrs()#

Description#

Free Host addresses allocated by DNSc_GetHostAddrs() .

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CacheClrAll (RTOS_ERR  *p_err)

Arguments#

p_addr

Pointer to the host addresses link-list to free.

Returned Value#

None.

Notes / Warnings#

None.

DNSc_GetServerByAddr#

Description#

Gets the default DNS server in a address object format.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_GetServerByAddr (NET_IP_ADDR_OBJ  *p_addr,
                            RTOS_ERR    *p_err)

Arguments#

p_addr

Pointer to the structure that will receive the IP address of the DNS server.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

Returned Value#

None.

Notes / Warnings#

None.

DNSc_GetServerByStr()#

Description#

Gets the default DNS server in string format.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_GetServerByStr (CPU_CHAR    *p_str,
                           CPU_INT08U   str_len_max,
                           RTOS_ERR    *p_err)

Arguments#

p_addr

Pointer to the structure that will receive the IP address of the DNS server.

str_len_max

Maximum string length.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

Returned Value#

None.

Notes / Warnings#

None.

ARP API#

Function Name

Description

NetARP_CacheGetAddrHW()

Get the hardware address corresponding to a specific ARP cache’s protocol address.

NetARP_CachePoolStatGet()

Get ARP caches’ statistics pool.

NetARP_CachePoolStatResetMaxUsed()

Reset ARP caches’ statistics pool’s maximum number of entries used.

NetARP_CacheProbeAddrOnNet()

Transmit an ARP request to probe the local network for a specific protocol address.

NetARP_CfgAddrFilterEn()

Configures the ARP address filter feature

NetARP_CfgCacheAccessedTh()

Configure ARP cache access promotion threshold.

NetARP_CfgCacheTimeout()

Configure ARP cache timeout for ARP Cache List.

NetARP_CfgCacheTxQ_MaxTh()

Configures the ARP cache maximum number of transmit packet buffers to enqueue.

NetARP_CfgPendReqMaxRetries()

Configure maximum number of ARP request retries for ARP cache in PEND state.

NetARP_CfgPendReqTimeout()

Configure timeout between ARP request timeouts for ARP cache in PEND state.

NetARP_CfgRenewReqMaxRetries()

Configure maximum number of ARP request retries for ARP cache in RENEW state.

NetARP_CfgRenewReqTimeout()

Configure timeout between ARP request timeouts for ARP cache in RENEW state.

NetARP_IsAddrProtocolConflict()

Check interface’s protocol address conflict status between this interface’s ARP host protocol address(es) and any other host(s) on the local network.

NetARP_TxReqGratuitous()

Prepares and transmits an unrequested ARP Request into the local network.

NetARP_CacheGetAddrHW()#

Description#

  1. Gets the hardware address that corresponds to a specific ARP cache's protocol address by following these steps :

    (a) Acquire the network lock.

    (b) Search the ARP Cache List for ARP cache with the desired protocol address.

    (c) If the corresponding ARP cache is found, get/return the hardware address.

    (d) Release network lock.

Files#

net_arp.h/net_arp.c

Prototype#

NET_CACHE_ADDR_LEN  NetARP_CacheGetAddrHW (NET_IF_NBR           if_nbr,
                                           CPU_INT08U          *p_addr_hw,
                                           NET_CACHE_ADDR_LEN   addr_hw_len_buf,
                                           CPU_INT08U          *p_addr_protocol,
                                           NET_CACHE_ADDR_LEN   addr_protocol_len,
                                           RTOS_ERR            *p_err)

Arguments#

if_nbr

Network interface number.

p_addr_hw

Pointer to a memory buffer that will receive the hardware address :

addr_hw_len_buf

Length of hardware address memory buffer (in octets).

p_addr_protocol

Pointer to the specific protocol address to search for corresponding hardware address.

addr_protocol_len

Length of protocol addresses (in octets).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_ADDR_UNRESOLVED

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • Length of returned hardware address, if available.

  • 0, otherwise.

Notes / Warnings#

  1. (a)

    1. The size of the memory buffer that will receive the returned hardware address MUST be greater than or equal to NET_IF_HW_ADDR_LEN_MAX.

    2. The length of any returned hardware address is equal to NET_IF_HW_ADDR_LEN_MAX.

    3. Address memory buffer array cleared in case of any error(s).

      (A) Address memory buffer array SHOULD be initialized to return a NULL address PRIOR to all validation or function handling in case of any error(s).

    (b) The length of the protocol address MUST be equal to NET_IPv4_ADDR_SIZE and is included for correctness and completeness.

  2. ARP addresses handled in network-order :

    (a) 'p_addr_hw' returns a hardware address in network-order.

    (b) 'p_addr_protocol' MUST points to a protocol address in network-order.

  3. While an ARP cache is in 'PENDING' state, the hardware address is NOT yet resolved, but it MAY be resolved in the near future by an awaited ARP Reply.

NetARP_CachePoolStatGet()#

Description#

Gets the ARP statistics pool.

Files#

net_arp.h/net_arp.c

Prototype#

NET_STAT_POOL  NetARP_CachePoolStatGet (void)

Arguments#

Returned Value#

  • ARP statistics pool, if NO error(s).

  • NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetARP_CachePoolStatResetMaxUsed()#

Description#

Resets ARP statistics pool's maximum number of entries used.

Files#

net_arp.h/net_arp.c

Prototype#

void  NetARP_CachePoolStatResetMaxUsed (void)

Arguments#

None.

Returned Value#

None.

Notes / Warnings#

None.

NetARP_CacheProbeAddrOnNet()#

Description#

  1. Transmits an ARP Request to probe the local network for a specific protocol address :

    (a) Acquire network lock.

    (b) Remove the ARP cache with desired protocol address from ARP Cache List, if available.

    (c) Configure the ARP cache :

    1. Get the default-configured ARP cache

    2. ARP cache state

    (d) Transmit the ARP Request to probe local network for desired protocol address.

    (e) Release the network lock.

  2. NetARP_CacheProbeAddrOnNet() SHOULD be used in conjunction with NetARP_CacheGetAddrHW() to determine if a specific protocol address is available on the local network :

    (a) After successfully transmitting an ARP Request to probe the local network.

    (b) After some time delay(s) [on the order of ARP Request timeouts & retries].

    (c) Check ARP Cache for the hardware address of a host on the local network that corresponds to the desired protocol address.

    See also NetARP_CacheGetAddrHW() and NetARP_TxReqGratuitous() .

Files#

net_arp.h/net_arp.c

Prototype#

void NetARP_CacheProbeAddrOnNet (NET_PROTOCOL_TYPE     protocol_type,
                                 CPU_INT08U           *p_addr_protocol_sender,
                                 CPU_INT08U           *p_addr_protocol_target,
                                 NET_CACHE_ADDR_LEN    addr_protocol_len,
                                 RTOS_ERR             *p_err)

Arguments#

protocol_type

Address protocol type.

p_addr_protocol_sender

Pointer to the protocol address to send the probe from (see Note #5a1).

p_addr_protocol_target

Pointer to the protocol address to probe the local network (see Note #1.a.2).

addr_protocol_len

Length of the protocol address (in octets) [see Note #1.b].

p_err Pointer to the variable that will receive one of the following error code(s) from this function :

  • _NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

  1. (a)

    1. 'p_addr_protocol_sender' MUST point to a valid protocol address in network-order, configured on a valid interface.

    2. 'p_addr_protocol_target' MUST point to a valid protocol address in network-order.

    (b) The length of the protocol address MUST be equal to NET_IPv4_ADDR_SIZE and is included for correctness and completeness.

NetARP_CfgAddrFilterEn()#

Description#

Configures the ARP address filter feature.

Files#

net_arp.h/net_arp.c

Prototype#

void  NetARP_CfgAddrFilterEn (CPU_BOOLEAN  en)

Arguments#

en

Set Filter to enabled or disabled:

  • DEF_ENABLED Enable filtering feature.

  • DEF_DISABLED Disable filtering feature.

Returned Value#

None.

Notes / Warnings#

None.

NetARP_CfgCacheAccessedTh()#

Description#

Configures the ARP cache access promotion threshold.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgCacheAccessedTh (CPU_INT16U  nbr_access)

Arguments#

nbr_access

Desired number of ARP cache accesses before ARP cache is promoted.

Returned Value#

  • DEF_OK, ARP cache access promotion threshold configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetARP_CfgCacheTimeout()#

Description#

Configures the ARP cache timeout from ARP Cache List.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgCacheTimeout (CPU_INT16U  timeout_sec)

Arguments#

timeout_sec

Desired value for the ARP cache timeout (in seconds).

Returned Value#

  • DEF_OK, ARP cache timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. RFC #1122, Section 2.3.2.1 states that "an implementation of the Address Resolution Protocol (ARP) ... MUST provide a mechanism to flush out-of-date cache entries. If this mechanism involves a timeout, it SHOULD be possible to configure the timeout value."

  2. The configured timeout does NOT reschedule any current ARP cache timeout in progress, but becomes effective the next time an ARP cache sets its timeout.

NetARP_CfgCacheTxQ_MaxTh()#

Description#

Configures the ARP cache maximum number of transmit packet buffers to enqueue.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgCacheTxQ_MaxTh (NET_BUF_QTY  nbr_buf_max)

Arguments#

nbr_buf_max

Desired maximum number of transmit packet buffers to enqueue.

Returned Value#

  • DEF_OK, ARP cache transmit packet buffer threshold configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetARP_CfgPendReqMaxRetries()#

Description#

Configures the ARP Request maximum number of requests for ARP cache in PEND state.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgPendReqMaxRetries (CPU_INT08U  max_nbr_retries)

Arguments#

max_nbr_retries

Desired maximum number of ARP Request attempts.

Returned Value#

  • DEF_OK, ARP Request maximum number of request attempts configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. An ARP cache monitors the number of ARP Requests transmitted before receiving an ARP Reply. In other words, an ARP cache monitors the number of attempted ARP Requests.

    However, the maximum number of ARP Requests that each ARP cache is allowed to transmit is configured in terms of retries. The total number of attempts is equal to the configured number of retries, plus one (1.).

NetARP_CfgPendReqTimeout()#

Description#

Configures the timeout between ARP Request retries for ARP cache in PEND state.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgPendReqTimeout (CPU_INT08U  timeout_sec)

Arguments#

timeout_sec

Desired value for ARP Request pending ARP Reply timeout (in seconds).

Returned Value#

  • DEF_OK, ARP Request timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current ARP Request timeouts in progress but becomes effective the next time an ARP Request is transmitted with timeout.

NetARP_CfgRenewReqMaxRetries()#

Description#

Configures the ARP Request maximum number of requests for ARP cache in RENEW state.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgRenewReqMaxRetries (CPU_INT08U  max_nbr_retries)

Arguments#

max_nbr_retries

Desired maximum number of ARP Request attempts.

Returned Value#

  • DEF_OK, ARP Request maximum number of request attempts configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. An ARP cache monitors the number of ARP Requests transmitted before receiving an ARP Reply. In other words, an ARP cache monitors the number of attempted ARP Requests.

    However, the maximum number of ARP Requests that each ARP cache is allowed to transmit is configured in terms of retries. The total number of attempts is equal to the configured number of retries, plus one (1.).

NetARP_CfgRenewReqTimeout()#

Description#

Configures the timeout between ARP Request retries for ARP cache in RENEW state.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_CfgRenewReqTimeout (CPU_INT08U  timeout_sec)

Arguments#

timeout_sec

Desired value for ARP Request pending ARP Reply timeout (in seconds).

Returned Value#

  • DEF_OK, ARP Request timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current ARP Request timeouts in progress but becomes effective the next time an ARP Request is transmitted with timeout.

NetARP_IsAddrProtocolConflict()#

Description#

Gets the interface's protocol address conflict status between this interface's ARP host protocol address(s) and the other host(s) on the local network.

Files#

net_arp.h/net_arp.c

Prototype#

CPU_BOOLEAN  NetARP_IsAddrProtocolConflict (NET_IF_NBR   if_nbr,
                                            RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to get protocol address conflict status.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, if the address conflict is detected.

  • DEF_NO, otherwise.

Notes / Warnings#

RFC #3927, Section 2.5 states that :

"If a host receives an ARP packet (request *or* reply) on an interface where the 'sender hardware address' does not match the hardware address of that interface, but the 'sender IP address' is a IP address the host has configured for that interface, then this is a conflicting ARP packet, indicating an address conflict."

NetARP_TxReqGratuitous()#

Description#

  1. Prepares and transmits an unrequested ARP Request into the local network by following these steps :

    (a) Acquire the network lock.

    (b) Get the network interface's hardware address.

    (c) Prepare the ARP Request packet :

    1. Configure the sender's hardware address as this interface's hardware address.

    2. Configure the target's hardware address as NULL.

    3. Configure the sender's protocol address as this interface's protocol address.

    4. Configure the target's protocol address as this interface's protocol address.

    5. Configure the ARP operation as an ARP Request.

    (d) Transmit the ARP Request.

    (e) Release the network lock.

  2. NetARP_TxReqGratuitous() COULD be used in conjunction with NetARP_IsAddrProtocolConflict() to determine if the host's protocol address is already present on the local network, as follows :

    (a) After successfully transmitting a gratuitous ARP Request onto the local network.

    (b) After a time delay(s) [on the order of ARP Request timeouts & retries].

    (c) After checking this host's ARP protocol address conflict flag to see if any other host(s) are configured with this host's ARP protocol address.

Files#

net_arp.h/net_arp.c

Prototype#

void NetARP_TxReqGratuitous (NET_PROTOCOL_TYPE    protocol_type,
                             CPU_INT08U          *p_addr_protocol,
                             NET_CACHE_ADDR_LEN   addr_protocol_len,
                             RTOS_ERR            *p_err)

Arguments#

protocol_type

Address protocol type.

p_addr_protocol

Pointer to protocol address used to transmit gratuitous request (see Note #5).

addr_protocol_len

Length of protocol address (in octets).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. 'p_addr_protocol' MUST point to a valid protocol address in network-order.

  2. RFC #3927, Section 2.4 states that one purpose for transmitting a gratuitous ARP Request is for a host to "announce its [claim] ... [on] a unique address ... by broadcasting ... an ARP Request ... to make sure that other hosts on the link do not have stale ARP cache entries left over from some other host that may previously have been using the same address".

    "The ... ARP Request ... announcement ... sender and target IP addresses are both set to the host's newly selected ... address."

NDP API#

Function Name

Description

NetNDP_CfgNeighborCacheTimeout()

Configure NDP neighbor cache timeout for NDP Neighbor Cache List.

NetNDP_CfgReachabilityTimeout()

Configure one of the NDP neighbor timeouts associated with the Neighbors Unreachability Detection.

NetNDP_CfgSolicitMaxNbr()

Configure one of the NDP neighbor maximum solicitations number.

NetNDP_CfgNeighborCacheTimeout()#

Description#

Configures the NDP Neighbor timeout from NDP Neighbor cache list.

Files#

net_ndp.h/net_ndp.c

Prototype#

CPU_BOOLEAN  NetNDP_CfgNeighborCacheTimeout (CPU_INT16U  timeout_sec)

Arguments#

timeout_sec

Desired value for NDP neighbor timeout (in seconds).

Returned Value#

  • DEF_OK, NDP neighbor cache timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetNDP_CfgReachabilityTimeout()#

Description#

Configures possible NDP Neighbor reachability timeouts.

Files#

net_ndp.h/net_ndp.c

Prototype#

CPU_BOOLEAN NetNDP_CfgReachabilityTimeout (NET_NDP_TIMEOUT   timeout_type,
                                           CPU_INT16U        timeout_sec)

Arguments#

timeout_type

NDP timeout type :

  • NET_NDP_TIMEOUT_REACHABLE

  • NET_NDP_TIMEOUT_DELAY

  • NET_NDP_TIMEOUT_SOLICIT

timeout_sec

Desired value for NDP neighbor reachable timeout (in seconds).

Returned Value#

  • DEF_OK, NDP neighbor cache timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

multicast.

NetNDP_CfgSolicitMaxNbr()#

Description#

Configures the NDP maximum number of NDP Solicitation sent for the given type of solicitation.

Files#

net_ndp.h/net_ndp.c

Prototype#

CPU_BOOLEAN NetNDP_CfgSolicitMaxNbr (NET_NDP_SOLICIT solicit_type,
                                     CPU_INT08U      max_nbr)

Arguments#

solicit_type

NDP Solicitation message type :

  • NET_NDP_SOLICIT_MULTICAST

  • NET_NDP_SOLICIT_UNICAST

  • NET_NDP_SOLICIT_DAD

max_nbr

Desired maximum number of NDP solicitation attempts.

Returned Value#

  • DEF_OK, NDP Request maximum number of solicitation attempts configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

multicast.

IGMP API#

Function Name

Description

NetIGMP_HostGrpJoin()

Join a host group.

NetIGMP_HostGrpLeave()

Leave a host group.

NetIGMP_HostGrpJoin()#

Description#

Joins a host group.

Files#

net_igmp.h/net_igmp.c

Prototype#

CPU_BOOLEAN  NetIGMP_HostGrpJoin (NET_IF_NBR      if_nbr,
                                  NET_IPv4_ADDR   addr_grp,
                                  RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to join host group.

addr_grp

IP address of host group to join.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if host group successfully joined.

  • DEF_FAIL, otherwise.

Notes / Warnings#

IP host group address MUST be in host-order.

NetIGMP_HostGrpLeave()#

Description#

Leaves a host group.

Files#

net_igmp.h/net_igmp.c

Prototype#

CPU_BOOLEAN  NetIGMP_HostGrpLeave (NET_IF_NBR      if_nbr,
                                   NET_IPv4_ADDR   addr_grp,
                                   RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to leave host group.

addr_grp

IP address of host group to leave.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

Returned Value#

  • DEF_OK, if host group successfully left.

  • DEF_FAIL, otherwise.

Notes / Warnings#

IP host group address MUST be in host-order.

MLDP API#

Function Name

Description

NetMLDP_HostGrpJoin()

Join a MLDP Multicast host group.

NetMLDP_HostGrpLeave()

Leave a MLDP host group.

NetMLDP_HostGrpJoin()#

Description#

Joins an IPv6 MLDP group associated with a multicast address.

Files#

net_mldp.h/net_mldp.c

Prototype#

CPU_BOOLEAN  NetMLDP_HostGrpJoin (NET_IF_NBR      if_nbr,
                                  NET_IPv6_ADDR  *p_addr,
                                  RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number associated with the MDLP host group.

p_addr

Pointer to the IPv6 address of host group to join.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_RX

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Pointer to MLDP Host Group object added to the MLDP list.

  • DEF_NULL, otherwise.

Notes / Warnings#

None.

NetMLDP_HostGrpLeave()#

Description#

Leaves MDLP group associated with the received IPv6 multicast address.

Files#

net_mldp.h/net_mldp.c

Prototype#

CPU_BOOLEAN  NetMLDP_HostGrpLeave (NET_IF_NBR      if_nbr,
                                   NET_IPv6_ADDR  *p_addr,
                                   RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number associated with host group.

p_addr

Pointer to the IPv6 address of host group to leave.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • DEF_OK, if host group successfully left.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

ICMP API#

Function Name

Description

NetICMP_TxEchoReq()

Send ICMPv4 or ICMPv6 Echo Request message to a network host.

NetICMP_TxEchoReq()#

Description#

Transmits an ICMPv4 or an ICMPv6 echo request message.

Files#

net_icmp.h/net_icmp.c

Prototype#

CPU_BOOLEAN  NetICMP_TxEchoReq (CPU_INT08U       *p_addr_dest,
                                NET_IP_ADDR_LEN   addr_len,
                                CPU_INT32U        timeout_ms,
                                void             *p_data,
                                CPU_INT16U        data_len,
                                RTOS_ERR         *p_err)

Arguments#

p_addr_dest

Pointer to the IP destination address to send the ICMP echo request.

addr_len

IP address length :

  • NET_IPv4_ADDR_SIZE

  • NET_IPv6_ADDR_SIZE

timeout_ms

Timeout value to wait for ICMP echo response.

p_data

Pointer to the data buffer to include in the ICMP echo request.

data_len

Number of data buffer octets to include in the ICMP echo request.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_NET_ICMP_ECHO_REPLY_DATA_CMP

  • RTOS_ERR_TIMEOUT

Returned Value#

  • DEF_OK, if ICMP echo request message successfully sent to remote host.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

IPv4 API#

Function Name

Description

NetIPv4_AddrLinkLocalCfg()

Start the IPv4 Link Local process on the given interface.

NetIPv4_AddrLinkLocalCfgRemove()

Stop the IPv4 Link Local process on the given interface and remove the link local address if one has already been configured.

NetIPv4_CfgAddrAdd()

Add a statically-configured IPv4 host address, subnet mask, and default gateway to an interface.

NetIPv4_CfgAddrAddDynamic()

Add a dynamically-configured IPv4 host address, subnet mask, and default gateway to an interface.

NetIPv4_CfgAddrAddDynamicStart()

Start dynamic IPv4 address configuration for an interface.

NetIPv4_CfgAddrAddDynamicStop()

Stop dynamic IPv4 address configuration for an interface.

NetIPv4_CfgAddrRemove()

Remove a configured IPv4 host address from an interface.

NetIPv4_CfgAddrRemoveAll()

Remove all configured IPv4 host address(es) from an interface.

NetIPv4_CfgFragReasmTimeout()

Configure IPv4 fragment reassembly timeout.

NetIPv4_GetAddrDfltGateway()

Get the default gateway IPv4 address for a host’s configured IPv4 address.

NetIPv4_GetAddrHost()

Get an interface’s configured IPv4 host address(es).

NetIPv4_GetAddrSrc()

Get corresponding configured IPv4 host address for a remote IPv4 address to use as source address.

NetIPv4_GetAddrSubnetMask()

Get the IPv4 address subnet mask for a host’s configured IPv4 address.

NetIPv4_IsAddrBroadcast()

Validate an IPv4 address as the limited broadcast IPv4 address.

NetIPv4_IsAddrClassA()

Validate an IPv4 address as a Class-A IPv4 address.

NetIPv4_IsAddrClassB()

Validate an IPv4 address as a Class-B IPv4 address.

NetIPv4_IsAddrClassC()

Validate an IPv4 address as a Class-C IPv4 address.

NetIPv4_IsAddrHost()

Validate an IPv4 address as one the host’s IPv4 address(es).

NetIPv4_IsAddrHostCfgd()

Validate an IPv4 address as one the host’s configured IPv4 address(es).

NetIPv4_IsAddrLocalHost()

Validate an IPv4 address as a Localhost IPv4 address.

NetIPv4_IsAddrLocalLink()

Validate an IPv4 address as a link-local IPv4 address.

NetIPv4_IsAddrMulticast()

Validate an IPv4 address as a multicast IP address.

NetIPv4_IsAddrsCfgdOnIF()

Check if any IPv4 address(es) are configured on an interface.

NetIPv4_IsAddrThisHost()

Validate an IPv4 address as the ‘This Host’ initialization IPv4 address.

NetIPv4_IsValidAddrHost()

Validate an IPv4 address as a valid IPv4 host address.

NetIPv4_IsValidAddrHostCfgd()

Validate an IPv4 address as a valid, configurable IPv4 host address.

NetIPv4_IsValidAddrSubnetMask()

Validate an IPv4 address subnet mask.

NetIPv4_AddrLinkLocalCfg()#

Description#

Start the IPv4 Link Local process on the given interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

void  NetIPv4_AddrLinkLocalCfg (NET_IF_NBR                          if_nbr,
                                NET_IPv4_LINK_LOCAL_COMPLETE_HOOK   hook,
                                RTOS_ERR                           *p_err)

Arguments#

if_nbr

Interface number on which the IPv4 Link Local process will be started.

hook

Hook function to be notified when the process is completed.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

An IPv4 link local address will only be configured if no other IPv4 addresses are configured on the interface.

NetIPv4_AddrLinkLocalCfgRemove()#

Description#

Stop the IPv4 Link Local process on the given interface and remove the link local address if one has already been configured.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

void  NetIPv4_AddrLinkLocalCfgRemove (NET_IF_NBR  if_nbr,
                                      RTOS_ERR   *p_err)

Arguments#

if_nbr

Interface number.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None

NetIPv4_CfgAddrAdd()#

Description#

Adds a statically-configured IPv4 host address, subnet mask, and default gateway to an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN NetIPv4_CfgAddrAdd (NET_IF_NBR      if_nbr,
                                NET_IPv4_ADDR   addr_host,
                                NET_IPv4_ADDR   addr_subnet_mask,
                                NET_IPv4_ADDR   addr_dflt_gateway,
                                RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to configure.

addr_host

Desired IPv4 address to add to this interface.

addr_subnet_mask

Desired IPv4 address subnet mask to configure.

addr_dflt_gateway

Desired IPv4 default gateway address to configure.

DEF_NULL or empty string if no gateway to configure.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if valid IPv4 address, subnet mask, and default gateway configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. IPv4 addresses MUST be in host-order.

  2. (a) A host on an isolated network should be able to correctly operate and communicate with all other hosts on its local network without need of a gateway or configuration of a gateway.

    (b) However, a configured gateway MUST be on the same network as the host's IPv4 address (i.e. the network portion of the configured IPv4 address and the configured gateway addresses MUST be identical).

NetIPv4_CfgAddrAddDynamic()#

Description#

Adds a dynamically-configured IPv4 host address, subnet mask, and default gateway to an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_CfgAddrAddDynamic (NET_IF_NBR      if_nbr,
                                        NET_IPv4_ADDR   addr_host,
                                        NET_IPv4_ADDR   addr_subnet_mask,
                                        NET_IPv4_ADDR   addr_dflt_gateway,
                                        RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to configure.

addr_host

Desired IPv4 address to add to this interface.

addr_subnet_mask

Desired IPv4 address subnet mask to configure.

addr_dflt_gateway

Desired IPv4 default gateway address to configure.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if valid IPv4 address, subnet mask, and default gateway configured.

  • DEF_FAIL , otherwise.

Notes / Warnings#

  1. Application calls to dynamic address configuration functions MUST be sequenced as follows :

    (a) NetIPv4_CfgAddrAddDynamicStart() MUST precede NetIPv4_CfgAddrAddDynamic().

  2. IPv4 addresses MUST be in host-order.

NetIPv4_CfgAddrAddDynamicStart()#

Description#

Starts the dynamic address configuration for an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_CfgAddrAddDynamicStart (NET_IF_NBR   if_nbr,
                                             RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to start dynamic address configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if dynamic configuration successfully started.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. Application calls to dynamic address configuration functions MUST be sequenced as follows:

    (a) NetIPv4_CfgAddrAddDynamicStart() MUST precede NetIPv4_CfgAddrAddDynamic().

NetIPv4_CfgAddrAddDynamicStop()#

Description#

Stops the dynamic address configuration for an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_CfgAddrAddDynamicStop (NET_IF_NBR   if_nbr,
                                            RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to stop dynamic address configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_FULL

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if dynamic configuration successfully stopped.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. Application calls to dynamic address configuration functions MUST be sequenced as follows :

    (a) NetIPv4_CfgAddrAddDynamicStop()MUST followNetIPv4_CfgAddrAddDynamicStart() , if and ONLY if the dynamic address initialization fails.

NetIPv4_CfgAddrRemove()#

Description#

Removes a configured IPv4 host address, subnet mask, and default gateway from an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_CfgAddrRemove (NET_IF_NBR      if_nbr,
                                    NET_IPv4_ADDR   addr_host,
                                    RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to remove address configuration.

addr_host

IPv4 address to remove.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if IPv4 address configuration removed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_CfgAddrRemoveAll()#

Description#

Removes all configured IPv4 host address(s) from an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_CfgAddrRemoveAll (NET_IF_NBR   if_nbr,
                                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to remove address configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if ALL interface's configured IP host address(s) successfully removed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetIPv4_CfgFragReasmTimeout()#

Description#

Configures the IPv4 fragment reassembly timeout.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_CfgFragReasmTimeout (CPU_INT08U  timeout_sec)

Arguments#

timeout_sec

Desired value for IPv4 fragment reassembly timeout (in seconds).

Returned Value#

  • DEF_OK, IPv4 fragment reassembly timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current IP fragment reassembly timeout in progress, but becomes effective the next time IP fragments reassemble with timeout.

NetIPv4_GetAddrDfltGateway()#

Description#

Gets the default gateway IPv4 address for a configured IPv4 host address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

NET_IPv4_ADDR  NetIPv4_GetAddrDfltGateway (NET_IPv4_ADDR   addr,
                                           RTOS_ERR       *p_err)

Arguments#

addr

Configured IPv4 host address to get the default gateway.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

Returned Value#

  • Configured IPv4 host address's default gateway in host-order, if NO error(s).

  • NET_IPv4_ADDR_NONE, otherwise.

Notes / Warnings#

IPv4 address returned in host-order.

NetIPv4_GetAddrHost()#

Description#

Gets an interface's IPv4 host address(s).

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_GetAddrHost (NET_IF_NBR         if_nbr,
                                  NET_IPv4_ADDR     *p_addr_tbl,
                                  NET_IP_ADDRS_QTY  *p_addr_tbl_qty,
                                  RTOS_ERR          *p_err)

Arguments#

if_nbr

Interface number to get IPv4 host address(s).

p_addr_tbl

Pointer to IPv4 address table that will receive the IPv4 host address(s).

p_addr_tbl_qty

Pointer to a variable to pass the table size and will return the number of address added to the table.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if interface's IPv4 host address(s) successfully returned.

  • DEF_FAIL, otherwise.

Notes / Warnings#

IPv4 address(s) returned in host-order.

NetIPv4_GetAddrSrc()#

Description#

Gets the corresponding configured IPv4 host address for a remote IPv4 address (to use as source address).

Files#

net_ipv4.h/net_ipv4.c

Prototype#

NET_IPv4_ADDR  NetIPv4_GetAddrSrc (NET_IPv4_ADDR   addr_remote,
                                   RTOS_ERR       *p_err)

Arguments#

addr_remote

Remote address to get configured IPv4 host address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • Configured IPv4 host address, if available.

  • NET_IPv4_ADDR_NONE, otherwise.

Notes / Warnings#

IPv4 addresses MUST be in host-order.

NetIPv4_GetAddrSubnetMask()#

Description#

Gets the IPv4 address subnet mask for a configured IPv4 host address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

NET_IPv4_ADDR  NetIPv4_GetAddrSubnetMask (NET_IPv4_ADDR   addr,
                                          RTOS_ERR       *p_err)

Arguments#

addr

Configured IPv4 host address to get the subnet mask.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

Returned Value#

  • Configured IPv4 host address's subnet mask in host-order, if NO error(s).

  • NET_IPv4_ADDR_NONE, otherwise.

Notes / Warnings#

IPv4 address returned in host-order.

NetIPv4_IsAddrBroadcast()#

Description#

Validates an IPv4 address as a limited broadcast IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrBroadcast (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a limited broadcast IP address.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrClassA()#

Description#

Validates an IPv4 address as a Class-A IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrClassA (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a Class-A IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

  1. IPv4 address MUST be in host-order.

NetIPv4_IsAddrClassB()#

Description#

Validates an IPv4 address as a Class-B IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrClassB (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a Class-B IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrClassC()#

Description#

Validates an IPv4 address as a Class-C IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrClassC (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a Class-C IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrClassD()#

Description#

Validates an IPv4 address as a Class-D IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrClassD (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a Class-D IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrHost()#

Description#

Validates an IPv4 address as an IPv4 host address :

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrHost (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is one of the host's IPv4 addresses.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrHostCfgd()#

Description#

Validates an IPv4 address as a configured IPv4 host address on an enabled interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrHostCfgd (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is one of the host's configured IPv4 addresses.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrLocalHost()#

Description#

Validates an IPv4 address as a 'Localhost' IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrLocalHost (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a 'Localhost' IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrLocalLink()#

Description#

Validates an IPv4 address as a link-local IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrLocalLink (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a link-local IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

  1. IPv4 address MUST be in host-order.

NetIPv4_IsAddrMulticast()#

Description#

Validates an IPv4 address as a multicast IP address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrMulticast (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a multicast IP address.

  • DEF_NO, otherwise.

Notes / Warnings#

  1. IPv4 address MUST be in host-order.

NetIPv4_IsAddrThisHost()#

Description#

Validates an IPv4 address as a 'This Host' initialization IPv4 address.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrThisHost (NET_IPv4_ADDR  addr)

Arguments#

addr

IPv4 address to validate.

Returned Value#

  • DEF_YES, if IPv4 address is a 'This Host' initialization IPv4 address.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsAddrsCfgdOnIF()#

Description#

Checks if any IPv4 host address(s) configured on an interface.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsAddrsCfgdOnIF (NET_IF_NBR   if_nbr,
                                      RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to check for configured IPv4 host address(s).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, if any IP host address(s) configured on interface.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv4_IsValidAddrHost()#

Description#

  1. Validates an IPv4 host address :

    (a) MUST NOT be one of the following :

    1. This Host RFC #1122, Section 3.2.1.3.(a)

    2. Specified Host RFC #1122, Section 3.2.1.3.(b)

    3. Limited Broadcast RFC #1122, Section 3.2.1.3.(c)

    4. Directed Broadcast RFC #1122, Section 3.2.1.3.(d)

    5. Localhost RFC #1122, Section 3.2.1.3.(g)

    6. Multicast host address RFC #1112, Section 7.2

    (b) 1. RFC #3927, Section 2.1 specifies the "IPv4 Link-Local address" :

    1. "Range ... inclusive" ...

      1. "from 169.254.1.0" ...

      2. "to 169.254.254.255".

  2. ONLY validates typical IPv4 host addresses, since 'This Host' and 'Specified Host' IPv4 host addresses are ONLY valid during a host's initialization.

    This function CANNOT be used to validate any 'This Host' or 'Specified Host' host addresses.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsValidAddrHost (NET_IPv4_ADDR  addr_host)

Arguments#

addr_host

IPv4 host address to validate (see Note #4).

Returned Value#

  • DEF_YES, if IPv4 host address is valid.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 address MUST be in host-order.

NetIPv4_IsValidAddrHostCfgd()#

Description#

  1. Validates an IPv4 address for a configured IPv4 host address :

    (a) MUST NOT be one of the following :

    1. This Host RFC #1122, Section 3.2.1.3.(a)

    2. Specified Host RFC #1122, Section 3.2.1.3.(b)

    3. Limited Broadcast RFC #1122, Section 3.2.1.3.(c)

    4. Directed Broadcast RFC #1122, Section 3.2.1.3.(d)

    5. Subnet Broadcast RFC #1122, Section 3.2.1.3.(e)

    6. Localhost RFC #1122, Section 3.2.1.3.(g)

    7. Multicast host address RFC #1112, Section 7.2

  2. ONLY validates this host's IPv4 address, since 'This Host' and 'Specified Host' IPv4 host addresses are ONLY valid during a host's initialization (see Notes #1a1 and #1a4). This function CANNOT be used to validate any 'This Host' or 'Specified Host' host addresses.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsValidAddrHostCfgd (NET_IPv4_ADDR  addr_host,
                                          NET_IPv4_ADDR  addr_subnet_mask)

Arguments#

addr_host

IPv4 host address to validate.

addr_subnet_mask

IPv4 address subnet mask.

Returned Value#

  • DEF_YES, if this host's IPv4 address is valid.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 addresses MUST be in host-order.

NetIPv4_IsValidAddrSubnetMask()#

Description#

  1. Validates an IPv4 address subnet mask :

    (a) RFC #1122, Section 3.2.1.3 states that :

      1. "IP addresses are not permitted to have the value 0 or -1 for any of the ... \<Subnet-number\> fields" ...
      2. "This implies that each of these fields will be at least two bits long."

    (b) RFC #950, Section 2.1 'Special Addresses' reiterates that "the values of all zeros and all ones in the subnet field should not be assigned to actual (physical) subnets".

    (c) RFC #950, Section 2.1 also states that "the bits that identify the subnet ... need not be adjacent in the address. However, we recommend that the subnet bits be contiguous and located as the most significant bits of the local address".

    Therefore, it is assumed that at least the most significant bit of the network portion of the subnet address SHOULD be set.

Files#

net_ipv4.h/net_ipv4.c

Prototype#

CPU_BOOLEAN  NetIPv4_IsValidAddrSubnetMask (NET_IPv4_ADDR  addr_subnet_mask)

Arguments#

addr_subnet_mask

IPv4 address subnet mask to validate.

Returned Value#

  • DEF_YES, if IPv4 address subnet mask is valid.

  • DEF_NO, otherwise.

Notes / Warnings#

IPv4 addresses MUST be in host-order.

IPv6 API#

Function Name

Description

NetIPv6_AddrAutoCfgDis()

Disables the IPv6 Stateless Address Auto-Configuration procedure.

NetIPv6_AddrAutoCfgEn()

Enables the IPv6 Stateless Address Auto-Configuation procedure.

NetIPv6_AddrMask()

Applies IPv6 mask on an address.

NetIPv6_AddrMaskByPrefixLen()

Gets the IPv6 address masked with the prefix length.

NetIPv6_AddrSubscribe()

Configures the IPv6 Address Configuration hook function.

NetIPv6_AddrUnsubscribe()

Removes a configured IPv6 host address and multicast solicited mode address from an interface.

NetIPv6_CfgAddrAdd()

Adds a statically-configured IPv6 host address to an interface.

NetIPv6_AddrTypeValidate()

Validates the type of an IPv6 address.

NetIPv6_CfgAddrRemove()

Removes a configured IPv6 host address and multicast solicited mode address from an interface.

NetIPv6_CfgAddrRemoveAll()

Removes all configured IPv6 host address(s) from an interface.

NetIPv6_CfgFragReasmTimeout()

Configures the IPv6 fragment reassembly timeout.

NetIPv6_CreateAddrFromID()

Creates an IPv6 address from a prefix and an identifier.

NetIPv6_CreateIF_ID()

Creates an IPv6 interface identifier.

NetIPv6_GetAddrHost()

Gets an interface's IPv6 host address(es).

NetIPv6_GetAddrSrc()

Finds the best matched source address in the IPv6 configured host addresses for the specified destination address.

NetIPv6_GetAddrMatchingLen()

Computes the number of identical most significant bits of two IPv6 addresses.

NetIPv6_GetAddrScope()

Gets the scope of a specific IPv6 address.

NetIPv6_IsAddrHostCfgd()

Validates an IPv6 address as a configured IPv6 host address on an enabled interface.

NetIPv6_IsAddrsCfgdOnIF()

Checks if any IPv6 host addresses are configured on a specific interface.

NetIPv6_IsValidAddrHost()

Validates an IPv6 host address.

NetIPv6_IsAddrLinkLocal()

Validates an IPv6 address as a link-local IPv6 address.

NetIPv6_IsAddrSiteLocal()

Validates an IPv6 address as a site-local address.

NetIPv6_IsAddrMcast()

Validates an IPv6 address as a multicast address.

NetIPv6_IsAddrMcastAllRouters()

Validates an IPv6 address as the all routers multicast address.

NetIPv6_IsAddrMcastAllNodes()

Validates an IPv6 address as the all nodes multicast address.

NetIPv6_IsAddrMcastSolNode()

Validates an IPv6 address as a solicited node multicast address.

NetIPv6_IsAddrMcastRsvd()

Validates an IPv6 address as a reserved multicast IPv6 address.

NetIPv6_IsAddrUnspecified()

Validates an IPv6 address as the unspecified IPv6 address.

NetIPv6_IsAddrLoopback()

Validates an IPv6 address as the IPv6 loopback address.

NetIPv6_AddrAutoCfgDis()#

Description#

Disables the IPv6 Auto-Configuration.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_AddrAutoCfgDis (NET_IF_NBR   if_nbr,
                                     RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number on which to disabled address auto-configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if the IPv6 Auto-Configuration was disabled successfully.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. After disabling, in a case of a link status change, the auto-configuration will not be called. The Hook function after the Auto-configuration completion will also not occur.

  2. The address previously configured with the auto-configuration will NOT be removed after disabling.

NetIPv6_AddrAutoCfgEn()#

Description#

Enables IPv6 Auto-configuration process. If the link state is UP, the IPv6 Auto-configuration will start. For other states, the Auto-configuration will start when the link becomes UP.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_AddrAutoCfgEn (NET_IF_NBR    if_nbr,
                                    CPU_BOOLEAN   dad_en,
                                    RTOS_ERR     *p_err)

Arguments#

if_nbr

Network interface number to enable the address auto-configuration on.

dad_en

  • DEF_YES, perform the Duplication Address Detection (DAD).

  • DEF_NO , otherwise

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_AVAIL

Returned Value#

  • DEF_OK, if the IPv6 Auto-Configuration is enabled successfully

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetIPv6_AddrSubscribe()#

Description#

Configures the IPv6 Address Configuration hook function. This function will be called each time a IPv6 address has finished being configured.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

void  NetIPv6_AddrSubscribe (NET_IPv6_ADDR_HOOK_FNCT   fnct,
                             RTOS_ERR                 *p_err)

Arguments#

fnct

Pointer to hook function to call when the IPv6 static address configuration ends.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

Returned Value#

None.

Notes / Warnings#

None.

NetIPv6_AddrUnsubscribe()#

Description#

Removes the subscribe hook function for IPv6 address configuration.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

void  NetIPv6_AddrUnsubscribe (NET_IPv6_ADDR_HOOK_FNCT  fnct)

Arguments#

fnct

Pointer to hook function to remove.

Returned Value#

None.

Notes / Warnings#

None.

NetIPv6_CfgAddrAdd()#

Description#

Adds a statically-configured IPv6 host address to an interface.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_CfgAddrAdd (NET_IF_NBR      if_nbr,
                                 NET_IPv6_ADDR  *p_addr,
                                 CPU_INT08U      prefix_len,
                                 NET_FLAGS       flags,
                                 RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to configure.

p_addr

Pointer to desired IPv6 address to add to this interface.

prefix_len

Prefix length of the desired IPv6 address to add to this interface.

flags

Set of flags to select options for the address configuration:

  • NET_IPv6_FLAG_BLOCK_EN Enables blocking mode if set.

  • NET_IPv6_FLAG_DAD_EN Enables DAD if set.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_AVAIL

Returned Value#

  • DEF_OK, if the valid IPv6 address is configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetIPv6_CfgAddrRemove()#

Description#

Removes a configured IPv6 host address and multicast solicited mode address from an interface.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_CfgAddrRemove (NET_IF_NBR      if_nbr,
                                    NET_IPv6_ADDR  *p_addr_host,
                                    RTOS_ERR       *p_err)

Arguments#

if_nbr

Interface number to remove address configuration.

p_addr_host

Pointer to the IPv6 address to remove.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if the IPv6 address is removed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetIPv6_CfgAddrRemoveAll()#

Description#

Removes all configured IPv6 host address(s) from an interface.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_CfgAddrRemoveAll (NET_IF_NBR   if_nbr,
                                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to remove address configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if ALL interface's configured IP host address(s) are successfully removed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetIPv6_CfgFragReasmTimeout()#

Description#

Configures the IPv6 fragment reassembly timeout.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_CfgFragReasmTimeout (CPU_INT08U  timeout_sec)

Arguments#

timeout_sec

Desired value for IPv6 fragment reassembly timeout (in seconds).

Returned Value#

  • DEF_OK, IPv6 fragment reassembly timeout configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

IPv6 fragment reassembly timeout is the maximum time allowed between received IPv6 fragments from the same IPv6 datagram.

NetIPv6_GetAddrHost()#

Description#

Gets an interface's IPv6 host address(es).

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_GetAddrHost (NET_IF_NBR         if_nbr,
                                  NET_IPv6_ADDR     *p_addr_tbl,
                                  NET_IP_ADDRS_QTY  *p_addr_tbl_qty,
                                  RTOS_ERR          *p_err)

Arguments#

if_nbr

Interface number to get IPv6 host address(s).

p_addr_tbl

Pointer to the IPv6 address table that will receive the IPv6 host address(s) in host-order for this interface.

p_addr_tbl_qty

Pointer to a variable to :

  1. Pass the size of the address table, in number of IPv6 addresses, pointed to by 'p_addr_tbl'.

  2. (a) Return the actual number of IPv6 addresses, if NO error(s).

    (b) Return 0, otherwise.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, if the interface's IPv6 host address(s) are successfully returned.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetIPv6_GetAddrSrc()#

Description#

Finds the best matched source address in the IPv6 configured host addresses for the specified destination address.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

const  NET_IPv6_ADDR_OBJ  *NetIPv6_GetAddrSrc (       NET_IF_NBR     *p_if_nbr,
                                               const  NET_IPv6_ADDR  *p_addr_src,
                                               const  NET_IPv6_ADDR  *p_addr_dest,
                                                      NET_IPv6_ADDR  *p_addr_nexthop,
                                                      RTOS_ERR       *p_err)

Arguments#

p_if_nbr

Pointer to given interface number if any. Variable that will received the interface number if none is given.

p_addr_src

Pointer to the IPv6 suggested source address if any. DEF_NULL if no source address is preferred.

p_addr_dest

Pointer to the destination address.

p_addr_nexthop

Pointer to Next Hop IPv6 address that the function will find.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_NEXT_HOP

Returned Value#

Pointer to the IPv6 addresses structure associated with the best source address for the given destination.

Notes / Warnings#

None.

NetIPv6_GetAddrMatchingLen()#

Description#

Computes the number of identical most significant bits of two IPv6 addresses.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_INT08U  NetIPv6_GetAddrMatchingLen (const  NET_IPv6_ADDR  *p_addr_1,
                                        const  NET_IPv6_ADDR  *p_addr_2,
                                               RTOS_ERR       *p_err)

Arguments#

p_addr_1

First IPv6 address for comparison.

p_addr_2

Second IPv6 address for comparison.

Returned Value#

  • Number of matching bits, if any.

  • 0, otherwise.

Notes / Warnings#

  1. The returned number is based on the number of matching MSB of both IPv6 addresses:

    (a) Calling the function with the following addresses will return 32 matching bits:

    • p_addr_1 : FE80:ABCD:0000:0000:0000:0000:0000:0000

    • p_addr_2 : FE80:ABCD:F000:0000:0000:0000:0000:0000

    (b) Calling the function with the following addresses will return 127 matching bits:

    • p_addr_1 : FE80:ABCD:0000:0000:0000:0000:0000:0000

    • p_addr_2 : FE80:ABCD:0000:0000:0000:0000:0000:0001

    (c) Calling the function with the following addresses will return 0 matching bits:

    • p_addr_1 : FE80:ABCD:0000:0000:0000:0000:0000:0000

    • p_addr_2 : 7E80:ABCD:0000:0000:0000:0000:0000:0000

    (d) Calling the function with identical addresses will return 128 matching bits.

NetIPv6_GetAddrScope()#

Description#

Gets the scope of the given IPv6 address.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

NET_IPv6_SCOPE  NetIPv6_GetAddrScope (const NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address.

Returned Value#

Scope of the given IPv6 address.

Notes / Warnings#

  1. For an unicast address, the scope is given by the 16 first bits of the address. Three scopes are possible:

    (a) 0xFE80 Link-local

    (b) 0xFEC0 Site-local -> Deprecated

    (c) others Global

  2. For a multicast address, the scope is given by a four bits field inside the address. Current possible scopes are:

    (a) 0x0 reserved

    (b) 0x1 interface-local

    (c) 0x2 link-local

    (d) 0x3 reserved

    (e) 0x4 admin-local

    (f) 0x5 site-local

    (g) 0x6 unassigned

    (h) 0x7 unassigned

    (i) 0x8 organization-local

    (j) 0x9 unassigned

    (k) 0xA unassigned

    (l) 0xB unassigned

    (m) 0xC unassigned

    (n) 0xD unassigned

    (o) 0xE global

    (p) 0xF reserved

NetIPv6_IsAddrHostCfgd()#

Description#

Validates an IPv6 address as a configured IPv6 host address on an enabled interface.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrHostCfgd (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

Returned Value#

  • DEF_YES, if IPv6 address is one of the host's configured IPv6 addresses.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrsCfgdOnIF()#

Description#

Checks if any IPv6 host address(s) configured on an interface.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrsCfgdOnIF (NET_IF_NBR   if_nbr,
                                      RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to check for configured IPv6 host address(s).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, if any IP host address(s) configured on interface.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsValidAddrHost()#

Description#

  1. Validates an IPv6 host address :

    (a) MUST NOT be one of the following :

    1. The unspecified address

    2. The loopback address

    3. A Multicast address

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsValidAddrHost (const  NET_IPv6_ADDR  *p_addr_host)

Arguments#

p_addr_host

Pointer to the IPv6 host address to validate.

Returned Value#

  • DEF_YES, if IPv6 host address valid.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrLinkLocal()#

Description#

  1. Validates an IPv6 address as a link-local IPv6 address.

    (a) In a text representation, it corresponds to the following format:

   FE80:0000:0000:0000:aaaa.bbbb.cccc.dddd        OR:
   FE80::aaaa.bbbb.cccc.dddd                                 WHERE:

      aaaa.bbbb.cccc.dddd is the interface ID.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrLinkLocal (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate

Returned Value#

  • DEF_YES, if IPv6 address is a link-local IPv6 address.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrSiteLocal()#

Description#

  1. Validates an IPv6 address as a site-local address :

    (a) In a text representation, it corresponds to the following format:

       FEC0:AAAA:BBBB:CCCC:DDDD:aaaa.bbbb.cccc.dddd WHERE:
    
       AAAA.BBBB.CCCC.DDDD is the subnet ID AND ...
       aaaa.bbbb.cccc.dddd is the interface ID.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrSiteLocal (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

Returned Value#

  • DEF_YES, if IPv6 address is a site-local IPv6 address.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrMcast()#

Description#

Validates an IPv6 address as a multicast address.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrMcast (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

Returned Value#

  • DEF_YES, if IPv6 address is a multicast IPv6 address.

  • DEF_NO, otherwise.

Notes / Warnings#

Refer to RFC #4291, Section 2.6 for the Multicast IPv6 address format.

NetIPv6_IsAddrMcastAllRouters()#

Description#

  1. Validates that an IPv6 address is a multicast to all routers IPv6 address :

    (a) RFC #4291 Section 2.7.1 specifies that the following IPv6 addresses "identify the group of all IPv6 routers" within their respective scope :

    1. FF01:0000:0000:0000:0000:0000:0000:2 Scope 1 -> Interface-local

    2. FF02:0000:0000:0000:0000:0000:0000:2 Scope 2 -> Link-local

    3. FF05:0000:0000:0000:0000:0000:0000:2 Scope 5 -> Site-local

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrMcastAllRouters (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate (see Note #2).

Returned Value#

  • DEF_YES, if IPv6 address is a multicast to all routers IPv6 address.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrMcastAllNodes()#

Description#

  1. Validates that an IPv6 address is a multicast to all routers IPv6 nodes :

    (a) RFC #4291 Section 2.7.1 specifies that the following IPv6 addresses "identify the group of all IPv6 nodes" within their respective scope :

    1. FF01:0000:0000:0000:0000:0000:0000:1 Scope 1 -> Interface-local

    2. FF02:0000:0000:0000:0000:0000:0000:1 Scope 2 -> Link-local

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrMcastAllNodes (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

Returned Value#

  • DEF_YES, if IPv6 address is a multicast to all nodes IPv6 address.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrMcastSolNode()#

Description#

Validates that an IPv6 address is the solicited node multicast address associated with an IPv6 unicast address.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrMcastSolNode (const  NET_IPv6_ADDR  *p_addr,
                                         const  NET_IPv6_ADDR  *p_addr_input)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

p_addr_input

Pointer to input IPv6 unicast address.

Returned Value#

  • DEF_YES, if IPv6 address is a solicited node multicast IPv6 address.

  • DEF_NO, otherwise.

Notes / Warnings#

  1. RFC #4291 Section 2.7.1 specifies that "Solicited-Node multicast address are computed as a function of a node's unicast and anycast addresses. A Solicited-Node multicast address is formed by taking the low-order 24 bits of an address (unicast or anycast) and appending those bits to the prefix FF02:0:0:0:0:1:FF00::/104 resulting in a multicast address in the range" from :

    (a) FF02:0000:0000:0000:0000:0001:FF00:0000 to

    (b) FF02:0000:0000:0000:0000:0001:FFFF:FFFF"

NetIPv6_IsAddrMcastRsvd()#

Description#

  1. Validates that an IPv6 address is a reserved multicast IPv6 address :

    (a) RFC #4291 Section 2.7.1 specifies that the following addresses "are reserved and shall never be assigned to any multicast group" :

    FF00:0:0:0:0:0:0:0

    FF01:0:0:0:0:0:0:0

    FF02:0:0:0:0:0:0:0

    FF03:0:0:0:0:0:0:0

    FF04:0:0:0:0:0:0:0

    FF05:0:0:0:0:0:0:0

    FF06:0:0:0:0:0:0:0

    FF08:0:0:0:0:0:0:0

    FF09:0:0:0:0:0:0:0

    FF0A:0:0:0:0:0:0:0

    FF0B:0:0:0:0:0:0:0

    FF0C:0:0:0:0:0:0:0

    FF0D:0:0:0:0:0:0:0

    FF0E:0:0:0:0:0:0:0

    FF0F:0:0:0:0:0:0:0

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrMcastRsvd (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate (see Note #2).

Returned Value#

  • DEF_YES, if IPv6 address is a reserved multicast IPv6 addresss.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

NetIPv6_IsAddrUnspecified()#

Description#

  1. Validates that an IPv6 address is the unspecified IPv6 address :

    (a) RFC #4291 Section 2.5.2 specifies that the following unicast address "is called the unspecified address" :

    0000:0000:0000:0000:0000:0000:0000:0000

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrUnspecified (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

Returned Value#

  • DEF_YES, if IPv6 address is the unspecified address.

  • DEF_NO, otherwise.

Notes / Warnings#

This address indicates the absence of an address and MUST NOT be assigned to any physical interface. However, it can be used in some cases in the Source Address field of IPv6 packets sent by a host before it learns its own address.

NetIPv6_IsAddrLoopback()#

Description#

  1. Validates that an IPv6 address is the IPv6 loopback address :

(a) RFC #4291 Section 2.5.3 specifies that the following unicast address "is called the loopback address" :

0000:0000:0000:0000:0000:0000:0000:0001

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_BOOLEAN  NetIPv6_IsAddrLoopback (const  NET_IPv6_ADDR  *p_addr)

Arguments#

p_addr

Pointer to the IPv6 address to validate (see Note #2).

Returned Value#

  • DEF_YES, if IPv6 address is the IPv6 loopback address.

  • DEF_NO, otherwise.

Notes / Warnings#

This address may be used by a node to send an IPv6 packet to itself and MUST NOT be assigned to any physical interface.

NetIPv6_AddrTypeValidate()#

Description#

Validates the type of an IPv6 address.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

NET_IPv6_ADDR_TYPE  NetIPv6_AddrTypeValidate (const  NET_IPv6_ADDR  *p_addr,
                                                     NET_IF_NBR      if_nbr)

Arguments#

p_addr

Pointer to the IPv6 address to validate.

if_nbr

Interface number associated to the address.

Returned Value#

NET_IPv6_ADDR_TYPE_MCAST, if IPv6 address is an unknown type muticast address.

  • NET_IPv6_ADDR_TYPE_MCAST_SOL, if IPv6 address is the multicast solicited node address.

  • NET_IPv6_ADDR_TYPE_MCAST_ROUTERS, if IPv6 address is the multicast all routers address.

  • NET_IPv6_ADDR_TYPE_MCAST_NODES, if IPv6 address is the multicast all nodes address.

  • NET_IPv6_ADDR_TYPE_LINK_LOCAL, if IPv6 address is a link-local address.

  • NET_IPv6_ADDR_TYPE_SITE_LOCAL, if IPv6 address is a site-local address.

  • NET_IPv6_ADDR_TYPE_UNSPECIFIED, if IPv6 address is the unspecified address.

  • NET_IPv6_ADDR_TYPE_LOOPBACK, if IPv6 address is the loopback address.

  • NET_IPv6_ADDR_TYPE_UNICAST, otherwise.

Notes / Warnings#

None.

NetIPv6_CreateIF_ID()#

Description#

Creates an IPv6 interface identifier.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

CPU_INT08U  NetIPv6_CreateIF_ID (NET_IF_NBR              if_nbr,
                                 NET_IPv6_ADDR          *p_addr_id,
                                 NET_IPv6_ADDR_ID_TYPE   id_type,
                                 RTOS_ERR               *p_err)

Arguments#

if_nbr

Network interface number to obtain the link-layer hardware address.

p_addr_id

Pointer to the IPv6 address that will receive the IPv6 interface identifier.

id_type

IPv6 interface identifier type:

NET_IPv6_ADDR_AUTO_CFG_ID_IEEE_48 Universal token from IEEE 802 48-bit MAC

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

  1. Universal interface identifier generated from IEEE 802 48-bit MAC address is the only interface identifier actually supported.

  2. RFC #4291, Appendix A, states that "[EUI-64] actually defines 0xFF and 0xFF as the bits to be inserted to create an IEEE EUI-64 identifier from an IEEE MAC-48 identifier. The 0xFF and 0xFE values are used when starting with an IEEE EUI-48 identifier."

NetIPv6_CreateAddrFromID()#

Description#

  1. Creates an IPv6 address from a prefix and an identifier.

    (a) Validate prefix length.

    (b) Append address ID to IPv6 address prefix.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

void  NetIPv6_CreateAddrFromID (NET_IPv6_ADDR              *p_addr_id,
                                NET_IPv6_ADDR              *p_addr_prefix,
                                NET_IPv6_ADDR_PREFIX_TYPE   prefix_type,
                                CPU_SIZE_T                  prefix_len,
                                RTOS_ERR                   *p_err)

Arguments#

p_addr_id

Pointer to the IPv6 address ID.

p_addr_prefix

Pointer to variable that will receive the created IPv6 address.

prefix_type

Prefix type:

  • NET_IPv6_ADDR_PREFIX_CUSTOM Custom prefix type

  • NET_IPv6_ADDR_PREFIX_LINK_LOCAL Link-local prefix type

prefix_len

Prefix len (in bits).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. If the prefix type is custom, p_addr_prefix SHOULD point on a variable that contain the prefix address. The address ID will be append to this prefix address. If the prefix type is link-local, the content of the variable pointed by p_addr_prefix does not matter and will be overwritten.

  2. If the prefix type is link-local, prefix address SHOULD be initialized to the unspecified IPv6 address to make sure resulting address does not have any uninitialized values (i.e., if any of the lower 8 octets of the ID address are NOT initialized).

NetIPv6_MaskGet()#

Description#

Gets an IPv6 mask based on prefix length.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

void  NetIPv6_MaskGet (NET_IPv6_ADDR  *p_mask_rtn,
                       CPU_INT08U      prefix_len,
                       RTOS_ERR       *p_err)

Arguments#

p_mask_rtn

Pointer to the IPv6 address mask to set.

prefix_len

Length of the prefix mask in bits.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

NetIPv6_AddrMaskByPrefixLen()#

Description#

Gets the IPv6 address masked with the prefix length.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

void  NetIPv6_AddrMaskByPrefixLen (const  NET_IPv6_ADDR  *p_addr,
                                          CPU_INT08U      prefix_len,
                                          NET_IPv6_ADDR  *p_addr_rtn,
                                          RTOS_ERR       *p_err)

Arguments#

p_addr

Pointer to the IPv6 address.

prefix_len

IPv6 address prefix length.

p_addr_rtn

Pointer to the IPv6 address that will receive the masked address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

NetIPv6_AddrMask()#

Description#

Applies IPv6 mask on an address.

Files#

net_ipv6.h/net_ipv6.c

Prototype#

void  NetIPv6_AddrMask (const  NET_IPv6_ADDR   *p_addr,
                        const  NET_IPv6_ADDR   *p_mask,
                               NET_IPv6_ADDR   *p_addr_rtn)

Arguments#

p_addr

Pointer to the IPv6 address to be masked.

p_mask

Pointer to the IPv6 address mask.

p_addr_rtn

Pointer to the IPv6 address that will received the masked address.

Returned Value#

None.

Notes / Warnings#

None.

TCP API#

Function Name

Description

NetTCP_ConnCfgIdleTimeout()

Configures the TCP connection’s idle timeout.

NetTCP_ConnCfgMaxSegSizeLocal()

Configures the TCP connection’s local maximum segment size.

NetTCP_ConnCfgMSL_Timeout()

Configures the TCP connection's maximum segment lifetime (MSL) timeout.

NetTCP_ConnCfgReTxMaxTh()

Configures the TCP connection’s maximum number of same segment retransmissions.

NetTCP_ConnCfgReTxMaxTimeout()

Configures the TCP connection’s maximum retransmission timeout.

NetTCP_ConnCfgRxWinSize()

Configures the TCP connection’s receive window size.

NetTCP_ConnCfgTxAckDlyTimeout()

Configures the TCP connection's transmit acknowledgment delay timeout.

NetTCP_ConnCfgTxAckImmedRxdPushEn()

Configures the TCP connection’s transmit immediate acknowledgment for received and pushed TCP segments.

NetTCP_ConnCfgTxKeepAliveEn()

Configures the TCP connection's transmit keep-alive enable.

NetTCP_ConnCfgTxKeepAliveRetryTimeout()

Configures the TCP connection's transmit keep-alive retry timeout.

NetTCP_ConnCfgTxKeepAliveTh()

Configures the TCP connection's maximum number of consecutive keep-alives to transmit.

NetTCP_ConnCfgTxNagleEn()

Configures the TCP connection's transmit Nagle algorithm enable.

NetTCP_ConnCfgTxWinSize()

Configures the TCP connection’s transmit window size.

NetTCP_ConnPoolStatGet()

Gets the TCP connections’ statistics pool.

NetTCP_ConnPoolStatResetMaxUsed()

Resets the TCP connections’ statistics pool’s maximum number of entries used.

NetTCP_ConnStateGet()

Retrieves the TCP Connection State.

NetTCP_ConnCfgIdleTimeout()#

Description#

Configures the TCP connection's idle timeout.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgIdleTimeout (NET_TCP_CONN_ID       conn_id_tcp,
                                        NET_TCP_TIMEOUT_SEC   timeout_sec,
                                        RTOS_ERR             *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure connection idle timeout.

timeout_sec

Desired value for TCP connection idle timeout (in seconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection idle timeout is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current idle timeout in progress but becomes effective the next time a TCP connection sets its idle timeout.

NetTCP_ConnCfgMSL_Timeout()#

Description#

Configures the TCP connection's maximum segment lifetime (MSL) timeout.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN NetTCP_ConnCfgMSL_Timeout (NET_TCP_CONN_ID      conn_id_tcp,
                                       NET_TCP_TIMEOUT_SEC  msl_timeout_sec,
                                       RTOS_ERR            *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure MSL value.

msl_timeout_sec

Desired value for TCP connection MSL timeout (in seconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection MSL timeout is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetTCP_ConnCfgMaxSegSizeLocal()#

Description#

Configures the TCP connection's local maximum segment size.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgMaxSegSizeLocal (NET_TCP_CONN_ID    conn_id_tcp,
                                            NET_TCP_SEG_SIZE   max_seg_size,
                                            RTOS_ERR          *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure local maximum segment size.

max_seg_size

Desired maximum segment size.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, TCP connection local maximum segment size successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. RFC #793, Section 3.1 'Header Format : Options : Maximum Segment Size' states that a TCP connection advertises its "maximum receive segment size ... only ... in the initial connection request (i.e., in segments with the SYN control bit set)."

    (a) Actively- connected TCP connection

    (b) Passively-connected TCP connection, which is cloned from its previously- configured LISTEN-state TCP connection

NetTCP_ConnCfgReTxMaxTh()#

Description#

Configures the TCP connection's maximum number of same segment retransmissions.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgReTxMaxTh (NET_TCP_CONN_ID   conn_id_tcp,
                                      NET_PKT_CTR       nbr_max_re_tx,
                                      RTOS_ERR         *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure maximum number of same segment retransmissions.

nbr_max_re_tx

Desired maximum number of same segment retransmissions.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection maximum number of same segment retransmissions are successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

RFC #1122, Section 4.2.3.5 states that "when the number of transmissions of the same segment reaches a threshold ... close the connection."

NetTCP_ConnCfgReTxMaxTimeout#

Description#

Configures the TCP connection's maximum retransmission timeout.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN NetTCP_ConnCfgReTxMaxTimeout (NET_TCP_CONN_ID       conn_id_tcp,
                                          NET_TCP_TIMEOUT_SEC   timeout_sec,
                                          RTOS_ERR             *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure maximum retransmission timeout.

timeout_sec

Desired value for TCP connection maximum retransmission timeout (in seconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection maximum retransmission timeout is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. (a) RFC #2988, Section 2.4 states that "a maximum value MAY be placed on RTO provided it is at least 60 seconds."

    (b) RFC #1122, Section 4.2.3.1 states that "the recommended ... RTO ... upper bound should be 2*MSL."

    (c) Stevens, TCP/IP Illustrated, Volume 1, 8th Printing, Section 21.2, Page 299 states that "the timeout value ... [has] an upper limit of 64 seconds."

  2. Configured timeout does NOT reschedule any current re-transmission timeout in progress, but becomes effective the next time a TCP connection sets its re-transmission timeout.

NetTCP_ConnCfgRxWinSize()#

Description#

Configures the TCP connection's receive window size.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgRxWinSize (NET_TCP_CONN_ID    conn_id_tcp,
                                      NET_TCP_WIN_SIZE   win_size,
                                      RTOS_ERR          *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure receive window size.

win_size

Desired receive window size.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, TCP connection receive window size successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. A TCP connection's receive window size SHOULD NOT be updated after the TCP connection is connected. Thus any configuration of the local receive window size MUST be performed by the application layer PRIOR to any TCP connection request/synchronization either from the following :

    (a) Actively- connected TCP connection

    (b) Passively-connected TCP connection, which is cloned from its previously- configured LISTEN-state TCP connection

NetTCP_ConnCfgTxAckDlyTimeout()#

Description#

Configures the TCP connection's transmit acknowledgment delay timeout.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgTxAckDlyTimeout (NET_TCP_CONN_ID      conn_id_tcp,
                                            NET_TCP_TIMEOUT_MS   timeout_ms,
                                            RTOS_ERR            *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit acknowledgment timeout.

timeout_ms

Desired value for TCP connection transmit acknowledgment delay timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection transmit acknowledgment delay timeout is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. (a) RFC #1122, Section 4.2.3.2 states that "an ACK should not be excessively delayed; in particular, the delay MUST be less than 0.5 seconds."

    (b) RFC #2581, Section 4.2 reiterates that "an ACK ... MUST be generated within 500 ms of the arrival of the first unacknowledged packet."

  2. Configured timeout does NOT reschedule any current acknowledgment delay timeout in progress but becomes effective the next time a TCP connection sets an acknowledgment delay timeout.

NetTCP_ConnCfgTxAckImmedRxdPushEn#

Description#

Configures the TCP connection's transmit immediate acknowledgment for received and pushed TCP segments enable.

Files

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN NetTCP_ConnCfgTxAckImmedRxdPushEn (NET_TCP_CONN_ID   conn_id_tcp,
                                               CPU_BOOLEAN       tx_immed_ack_en,
                                               RTOS_ERR         *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit immediate acknowledgment.

tx_immed_ack_en

Desired value for TCP connection transmit immediate acknowledgment.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection transmits immediate acknowledgment for received and pushed TCP segments enable is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

RFC #813, Section 5 states that "the receiver of data will refrain from sending an acknowledgment under certain circumstances ... The most obvious event on which to depend is the arrival of another segment. So, if a segment arrives, postpone sending an acknowledgment if ... the push bit is not set in the segment, since it is a reasonable assumption that there is more data coming in a subsequent segment."

NetTCP_ConnCfgTxKeepAliveEn()#

Description#

Configures the TCP connection's transmit keep-alive algorithm enable.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgTxKeepAliveEn (NET_TCP_CONN_ID   conn_id_tcp,
                                          CPU_BOOLEAN       keep_alive_en,
                                          RTOS_ERR         *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit keep-alive enable.

keep_alive_en

Desired value for TCP connection transmit keep-alive enable.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection transmit keep-alive enable is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

RFC #1122, Section 4.2.3.6 states that "if keep-alives are included, the application MUST be able to turn them on or off for each TCP connection."

NetTCP_ConnCfgTxKeepAliveRetryTimeout#

Description#

Configures the TCP connection's transmit keep-alive retry timeout.

Files

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN NetTCP_ConnCfgTxKeepAliveRetryHandler (NET_TCP_CONN_ID       conn_id_tcp,
                                                   NET_TCP_TIMEOUT_SEC   timeout_sec)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit keep-alive retry timeout.

timeout_sec

Desired value for TCP connection transmit keep-alive retry timeout (in seconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection transmit keep-alive retry timeout is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current keep-alive retry timeout in progress but becomes effective the next time a TCP connection sets its keep-alive retry timeout.

NetTCP_ConnCfgTxKeepAliveTh()#

Description#

Configures the TCP connection's maximum number of consecutive keep-alives to transmit.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgTxKeepAliveTh (NET_TCP_CONN_ID   conn_id_tcp,
                                          NET_PKT_CTR       nbr_max_keep_alive,
                                          RTOS_ERR         *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit keep-alive threshold.

nbr_max_keep_alive

Desired maximum number of consecutive keep-alives to transmit.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection transmit keep-alive threshold successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Stevens, TCP/IP Illustrated, Volume 1, 8th Printing, Section 23.3 'Other End Crashes', Pages 334-335 states "that the [remote host] ... send[s] ... [N] keepalive probes ... before declaring the connection dead."

NetTCP_ConnCfgTxNagleEn()#

Description#

Configures the TCP connection's transmit Nagle algorithm enable.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgTxNagleEn (NET_TCP_CONN_ID   conn_id_tcp,
                                      CPU_BOOLEAN       nagle_en,
                                      RTOS_ERR         *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit Nagle enable.

nagle_en

Desired value for TCP connection transmit Nagle enable :

  • DEF_ENABLED TCP connections delay transmitting next data segment(s) until all unacknowledged data is acknowledged OR an MSS-sized segment can be transmitted.

  • DEF_DISABLED TCP connections transmit all data segment(s) when permitted by local and remote hosts' congestion controls.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, TCP connection transmit Nagle enable is successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

RFC #1122, Section 4.2.3.4 also states that "a TCP SHOULD implement the Nagle Algorithm ... However, there MUST be a way for an application to disable the Nagle algorithm on an individual connection."

NetTCP_ConnCfgTxWinSize()#

Description#

Configures the TCP connection's transmit window size.

Files#

net_tcp.h/net_tcp.c

Prototype#

CPU_BOOLEAN  NetTCP_ConnCfgTxWinSize (NET_TCP_CONN_ID    conn_id_tcp,
                                      NET_TCP_WIN_SIZE   win_size,
                                      RTOS_ERR          *p_err)

Arguments#

conn_id_tcp

Handle identifier of TCP connection to configure transmit window size.

win_size

Desired transmit window size.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, TCP connection transmit window size successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. A TCP connection's transmit window size SHOULD NOT be updated after the TCP connection is connected. Thus any configuration of the local transmit window size MUST be performed by the application layer PRIOR to any TCP connection request/synchronization either from the following :

    (a) Actively- connected TCP connection

    (b) Passively-connected TCP connection, which is cloned from its previously- configured LISTEN-state TCP connection.

NetTCP_ConnPoolStatGet()#

Description#

Gets the TCP connection statistics pool.

Files#

net_tcp.h/net_tcp.c

Prototype#

NET_STAT_POOL  NetTCP_ConnPoolStatGet (void)

Arguments#

Returned Value#

TCP connection statistics pool, if NO error(s). NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetTCP_ConnPoolStatResetMaxUsed()#

Description#

Resets the TCP connection's statistics pool's maximum number of entries used.

Files#

net_tcp.h/net_tcp.c

Prototype#

void  NetTCP_ConnPoolStatResetMaxUsed (void)

Arguments#

Returned Value#

None.

Notes / Warnings#

None.

NetTCP_ConnStateGet()#

Description#

Retrieves the TCP Connection State.

Files#

net_tcp.h/net_tcp.c

Prototype#

NET_TCP_CONN_STATE  NetTCP_ConnStateGet (NET_TCP_CONN_ID  conn_id)

Arguments#

conn_id

TCP Connection ID number.

Returned Value#

TCP Connection State.

Notes / Warnings#

None.

Socket Functions API#

Function Name

Description

NET_SOCK_DESC_CLR()

Remove a socket file descriptor ID as a member of a file descriptor set.

NET_SOCK_DESC_COPY()

Copy a file descriptor set to another file descriptor set.

NET_SOCK_DESC_INIT()

Initialize/zero-clear a file descriptor set.

NET_SOCK_DESC_IS_SET()

Check if a socket file descriptor ID is a member of a file descriptor set.

NET_SOCK_DESC_SET()

Add a socket file descriptor ID as a member of a file descriptor set.

NetSock_Accept()

Wait for new socket connections on a listening server socket.

NetSock_Bind()

Assign network addresses to sockets.

NetSock_CfgBlock()

Configure a socket’s blocking mode.

NetSock_CfgConnChildQ_SizeGet()

Get socket's connection child queue size value.

NetSock_CfgConnChildQ_SizeSet()

Configure socket's child connection queue size.

NetSock_CfgIF()

Configure the interface that must be used by the socket.

NetSock_CfgRxQ_Size()

Configure socket's receive queue size.

NetSock_CfgSecure()

Configure a socket’s secure mode.

NetSock_CfgSecureClientCertKeyInstall()

Install certificate and key that must be used by a client for mutual authentication.

NetSock_CfgSecureClientCommonName()

Configure client socket's common name.

NetSock_CfgSecureClientTrustCallBack()

Configure client socket's trust call back function.

NetSock_CfgSecureServerCertKeyInstall()

Install certificate (CERT) and private key (KEY) from a buffer which must be used by a server.

NetSock_CfgTimeoutConnAcceptDflt()

Set socket’s connection accept timeout to configured-default value.

NetSock_CfgTimeoutConnAcceptGet_ms()

Get socket’s connection accept timeout value.

NetSock_CfgTimeoutConnAcceptSet()

Set socket’s connection accept timeout value.

NetSock_CfgTimeoutConnCloseDflt()

Set socket’s connection close timeout to configured-default value.

NetSock_CfgTimeoutConnCloseGet_ms()

Get socket’s connection close timeout value.

NetSock_CfgTimeoutConnCloseSet()

Set socket’s connection close timeout value.

NetSock_CfgTimeoutConnReqDflt()

Set socket’s connection request timeout to configured-default value.

NetSock_CfgTimeoutConnReqGet_ms()

Get socket’s connection request timeout value.

NetSock_CfgTimeoutConnReqSet()

Set socket’s connection request timeout value.

NetSock_CfgTimeoutRxQ_Dflt()

Set socket’s connection receive queue timeout to configured-default value.

NetSock_CfgTimeoutRxQ_Get_ms()

Get socket’s receive queue timeout value.

NetSock_CfgTimeoutRxQ_Set()

Set socket’s connection receive queue timeout value.

NetSock_CfgTimeoutTxQ_Dflt()

Set socket’s connection transmit queue timeout to configured-default value.

NetSock_CfgTimeoutTxQ_Get_ms()

Get socket’s transmit queue timeout value.

NetSock_CfgTimeoutTxQ_Set()

Set socket’s connection transmit queue timeout value.

NetSock_CfgTxIP_TOS() (IPv4 only)

Configure socket's transmit IPv4 Type of Service (TOS).

NetSock_CfgTxIP_TTL_Multicast() (IPv4 only)

Configure socket's transmit IPv4 multicast Time to live (TTL).

NetSock_CfgTxIP_TTL() (IPv4 only)

Configure socket's transmit IPv4 Time to Live (TTL).

NetSock_CfgTxQ_Size()

Configure socket's transmit queue size.

NetSock_Close()

Terminate communication and free a socket.

NetSock_Conn()

Connect a local socket to a remote socket address.

NetSock_GetConnTransportID()

Gets a socket’s transport layer connection handle ID (e.g., TCP connection ID) if available.

NetSock_GetLocalIPAddr()

Gets the local IP address used in the socket connection.

NetSock_IsConn()

Check if a socket is connected to a remote socket.

NetSock_Listen()

Set a socket to accept incoming connections.

NetSock_Open()

Create a datagram (i.e., UDP) or stream (i.e., TCP) type socket.

NetSock_OptGet()

Get the specified socket option from the sock_id socket.

NetSock_OptSet()

Set the specified socket option to the sock_id socket.

NetSock_PoolStatGet()

Get Network Sockets’ statistics pool.

NetSock_PoolStatResetMaxUsed()

Reset Network Sockets’ statistics pool’s maximum number of entries used.

NetSock_RxData() / NetSock_RxDataFrom()

Copy up to a specified number of bytes received from a remote socket into an application memory buffer.

NetSock_Sel()

Check if any sockets are ready for available read or write operations or error conditions.

NetSock_SelAbort()

Abort any tasks that are pending on a socket using the select functionality.

NetSock_TxData() / NetSock_TxDataTo()

Copy bytes from an application memory buffer into a socket to send to a remote socket.

NET_SOCK_DESC_CLR()#

Remove a socket file descriptor ID as a member of a file descriptor set. See also function NetSock_Sel().

Files#

net_sock.h

Prototype#

NET_SOCK_DESC_CLR(desc_nbr, p_desc_set);

Arguments#

desc_nbr

This is the socket file descriptor ID returned by NetSock_Open()/socket() when the socket was created or by NetSock_Accept()/accept() when a connection was accepted.

p_desc_set

Pointer to a socket file descriptor set.

Returned Value#

None.

Required Configuration#

Available only if NET_SOCK_CFG_SEL_EN is enabled (see section Socket Layer Configuration.

Notes / Warnings#

NetSock_Sel()/select() checks or waits for available operations or error conditions on any of the socket file descriptor members of a socket file descriptor set.

No errors are returned even if the socket file descriptor ID or the file descriptor set is invalid, or the socket file descriptor ID is not set in the file descriptor set.

NET_SOCK_DESC_COPY()#

Copy a file descriptor set to another file descriptor set. See also function NetSock_Sel() .

Files#

net_sock.h

Prototype#

    NET_SOCK_DESC_COPY(p_desc_set_dest, p_desc_set_src);

Arguments#

p_desc_set_dest

Pointer to the destination socket file descriptor set.

p_desc_set_src

Pointer to the source socket file descriptor set to copy.

Returned Value#

None.

Required Configuration#

Available only if NET_SOCK_CFG_SEL_EN is enabled (see section Socket Layer Configuration.

Notes / Warnings#

NetSock_Sel()/select() checks or waits for available operations or error conditions on any of the socket file descriptor members of a socket file descriptor set.

No errors are returned even if either file descriptor set is invalid.

NET_SOCK_DESC_INIT()#

Initialize/zero-clear a file descriptor set. See also function NetSock_Sel() .

Files#

net_sock.h

Prototype#

NET_SOCK_DESC_INIT(p_desc_set);

Arguments#

p_desc_set

Pointer to a socket file descriptor set.

Returned Value#

None.

Required Configuration#

Available only if NET_SOCK_CFG_SEL_EN is enabled (see section Socket Layer Configuration.

Notes / Warnings#

NetSock_Sel()/select() checks or waits for available operations or error conditions on any of the socket file descriptor members of a socket file descriptor set.

No errors are returned even if the file descriptor set is invalid.

NET_SOCK_DESC_IS_SET()#

Check if a socket file descriptor ID is a member of a file descriptor set. See also function NetSock_Sel() .

Files#

net_sock.h

Prototype#

NET_SOCK_DESC_IS_SET(desc_nbr, p_desc_set);

Arguments#

desc_nbr

This is the socket file descriptor ID returned by NetSock_Open()/socket() when the socket was created or by NetSock_Accept()/accept() when a connection was accepted.

p_desc_set

Pointer to a socket file descriptor set.

Returned Value#

  • 1, if the socket file descriptor ID is a member of the file descriptor set;

  • 0, otherwise.

Required Configuration#

Available only if NET_SOCK_CFG_SEL_EN is enabled (see section Socket Layer Configuration.

Notes / Warnings#

NetSock_Sel()/select() checks or waits for available operations or error conditions on any of the socket file descriptor members of a socket file descriptor set.

0 is returned if the socket file descriptor ID or the file descriptor set is invalid.

NET_SOCK_DESC_SET()#

Add a socket file descriptor ID as a member of a file descriptor set. See also function NetSock_Sel() .

Files#

net_sock.h

Prototype#

NET_SOCK_DESC_SET(desc_nbr, p_desc_set);

Arguments#

desc_nbr

This is the socket file descriptor ID returned by NetSock_Open()/socket() when the socket was created or by NetSock_Accept()/accept() when a connection was accepted.

p_desc_set

Pointer to a socket file descriptor set.

Returned Value#

None.

Required Configuration#

Available only if NET_SOCK_CFG_SEL_EN is enabled (see section Socket Layer Configuration.

Notes / Warnings#

NetSock_Sel()/select() checks or waits for available operations or error conditions on any of the socket file descriptor members of a socket file descriptor set.

No errors are returned even if the socket file descriptor ID or the file descriptor set is invalid, or the socket file descriptor ID is not cleared in the file descriptor set.

NetSock_Accept()#

Description#

Returns a new socket accepted from a listen socket.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_ID  NetSock_Accept (NET_SOCK_ID         sock_id,
                             NET_SOCK_ADDR      *p_addr_remote,
                             NET_SOCK_ADDR_LEN  *p_addr_len,
                             RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of listen socket.

p_addr_remote

Pointer to an address buffer that will receive the socket address structure.

p_addr_len

Pointer to a variable to pass the size of the socket address structure and that will received the size of the accepted connection’s socket address structure, if no errors, else a 0 size will be returned.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Socket descriptor/handle identifier of new accepted socket, if NO error(s).

  • NET_SOCK_BSD_ERR_ACCEPT, otherwise.

Notes / Warnings#

  1. Since 'p_addr`_len' argument is both an input and output argument:

    (a) Its input value SHOULD be validated prior to use;

    1. In the case that the 'p_addr_len' argument is passed a null pointer, NO input value is validated or used.

    (b) While its output value MUST be initially configured to return a default value PRIOR to all other validation or function handling in case of any error(s).

  2. Socket accept operation valid for stream-type sockets only.

NetSock_Bind()#

Description#

Binds a network socket to a local address.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_Bind (NET_SOCK_ID         sock_id,
                                 NET_SOCK_ADDR      *p_addr_local,
                                 NET_SOCK_ADDR_LEN   addr_len,
                                 RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to bind to a local address.

p_addr_local

Pointer to socket address structure.

addr_len

Length of socket address structure (in octets).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • NET_SOCK_BSD_ERR_NONE, if NO error(s).

  • NET_SOCK_BSD_ERR_BIND, otherwise.

Notes / Warnings#

  1. Socket address structure 'AddrFamily' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

  2. Socket address structure addresses MUST be configured/converted from host-order to network-order.

NetSock_BlockGet()#

Description#

Gets the blocking mode configuration of the specified socket.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_INT08U  NetSock_BlockGet (NET_SOCK_ID   sock_id,
                              RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket from which to get option.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • NET_SOCK_BLOCK_SEL_NO_BLOCK : Socket is in non-blocking mode.

  • NET_SOCK_BLOCK_SEL_BLOCK : Socket is in blocking mode.

  • NET_SOCK_BLOCK_SEL_NONE : Error in operation.

Notes / Warnings#

None.

NetSock_CfgBlock()#

Description#

Configures the socket's blocking mode.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgBlock (NET_SOCK_ID   sock_id,
                               CPU_INT08U    block,
                               RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure blocking mode.

block

Desired value for socket blocking mode :

  • NET_SOCK_BLOCK_SEL_DFLT

  • NET_SOCK_BLOCK_SEL_BLOCK

  • NET_SOCK_BLOCK_SEL_NO_BLOCK

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket blocking mode successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetSock_CfgConnChildQ_SizeGet()#

Description#

Gets the socket's connection child queue size value.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_Q_SIZE  NetSock_CfgConnChildQ_SizeGet (NET_SOCK_ID   sock_id,
                                                RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure receive queue size.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

Socket's connection child queue size value :

  • NET_SOCK_Q_SIZE_NONE, on any error(s).

  • NET_SOCK_Q_SIZE_UNLIMITED, if unlimited (i.e., NO limit) value is configured.

  • Child connection queue size, otherwise.

Notes / Warnings#

Despite inconsistency with other 'Get' status functions, NetSock_CfgConnChildQ_SizeGet() includes 'Cfg' for consistency with other NetSock_CfgConn&&&() functions.

NetSock_CfgConnChildQ_SizeSet()#

Description#

Configures the socket's child connection queue size.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgConnChildQ_SizeSet (NET_SOCK_ID       sock_id,
                                            NET_SOCK_Q_SIZE   queue_size,
                                            RTOS_ERR         *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure receive queue size.

queue_size

Desired child connection queue size :

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket child connection queue size successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. NetSock_CfgConnChildQ_SizeSet() allows a listen socket to reject new incoming connection when the number of connection already accepted (currently being processed) plus the listen queue reaches the maximum number of child connection.

    (a) It should be used when resources such as number of received buffers are limited.

    (b) It doesn't remove any connection currently accepted. It becomes effective for later connection request.

NetSock_CfgIF()#

Description#

Configures the interface that must be used by the socket.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgIF (NET_SOCK_ID   sock_id,
                            NET_IF_NBR    if_nbr,
                            RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of the socket to configure the interface number.

if_nbr

Interface number to bind to the socket.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, If the interface number was successfully set.

  • DEF_FAIL, Otherwise.

Notes / Warnings#

None.

NetSock_CfgRxQ_Size()#

Description#

Configures the socket's receive queue size.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgRxQ_Size (NET_SOCK_ID          sock_id,
                                  NET_SOCK_DATA_SIZE   size,
                                  RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure receive queue size.

size

Desired receive queue size.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, socket receive queue size successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. For datagram sockets, configured size does NOT :

    (a) Limit or remove any received data currently queued but becomes effective for later received data.

    (b) Partially truncate any received data but instead allows data from exactly one received packet buffer to overflow the configured size since each datagram MUST be received atomically.

  2. For stream sockets, size MAY be required to be configured prior to connecting.

NetSock_CfgSecure()#

Description#

Configures the socket's secure mode.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgSecure (NET_SOCK_ID   sock_id,
                                CPU_BOOLEAN   secure,
                                RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure secure mode.

secure

Desired value for socket secure mode :

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, socket secure mode successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

A socket's secure session ('p_sock-\>SecureSession') will be initialized if a secure port session buffer/object is available.

NetSock_CfgSecureClientCertKeyInstall()#

Description#

Installs the certificate and key that must be used by a client for mutual authentication.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgSecureClientCertKeyInstall (       NET_SOCK_ID                    sock_id,
                                                    const  void                          *p_cert,
                                                           CPU_INT32U                     cert_len,
                                                    const  void                          *p_key,
                                                           CPU_INT32U                     key_len,
                                                           NET_SOCK_SECURE_CERT_KEY_FMT   fmt,
                                                           CPU_BOOLEAN                    cert_chain,
                                                           RTOS_ERR                      *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of server socket to configure secure certificate and key.

p_cert

Pointer to buffer that contains the certificate.

cert_len

Certificate length.

p_key

Pointer to buffer that contains the key.

key_len

Key length.

fmt

Certificate and key format:

  • NET_SOCK_SECURE_CERT_KEY_FMT_PEM

  • NET_SOCK_SECURE_CERT_KEY_FMT_DER

cert_chain

Certificate point to a chain of certificate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, certificate and key successfully installed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

MUST BE CALLED ONLY AFTER NetSock_CfgSecure() has been called.

NetSock_CfgSecureClientCommonName()#

Description#

Configures the client socket's common name.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgSecureClientCommonName (NET_SOCK_ID   sock_id,
                                                CPU_CHAR     *p_common_name,
                                                RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of client socket to configure the common name.

p_common_name

Pointer to string that contain the common name.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, common name successfully installed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

MUST BE CALLED ONLY AFTER NetSock_CfgSecure() has been called.

NetSock_CfgSecureClientTrustCallBack()#

Description#

Configure client socket's trust call back function.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgSecureClientTrustCallBack (NET_SOCK_ID                  sock_id,
                                                   NET_SOCK_SECURE_TRUST_FNCT   call_back_fnct,
                                                   RTOS_ERR                    *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of client socket to configure trust call back function.

call_back_fnct

Pointer to the trust call back function

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, trust call back function successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

MUST BE CALLED ONLY AFTER NetSock_CfgSecure() has been called.

NetSock_CfgSecureServerCertKeyInstall()#

Description#

Installs the certificate and key that must be used by a server socket.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgSecureServerCertKeyInstall (       NET_SOCK_ID                    sock_id,
                                                    const  void                          *p_cert,
                                                           CPU_INT32U                     cert_len,
                                                    const  void                          *p_key,
                                                           CPU_INT32U                     key_len,
                                                           NET_SOCK_SECURE_CERT_KEY_FMT   fmt,
                                                           CPU_BOOLEAN                    cert_chain,
                                                           RTOS_ERR                      *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of server socket to configure secure certificate and key.

p_cert

Pointer to buffer that contains the certificate.

cert_len

Certificate length.

p_key

Pointer to buffer that contains the key.

key_len

Key length.

fmt

Certificate and key format:

  • NET_SOCK_SECURE_CERT_KEY_FMT_PEM

  • NET_SOCK_SECURE_CERT_KEY_FMT_DER

cert_chain

Certificate point to a chain of certificate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, certificate and key successfully installed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

MUST BE CALLED ONLY AFTER NetSock_CfgSecure() has been called.

NetSock_CfgTimeoutConnAcceptDflt()#

Description#

Sets the socket's connection accept configured-default timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutConnAcceptDflt (NET_SOCK_ID   sock_id,
                                               RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set connection accept timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket connection accept configured-default timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket connection accept timeout in progress, but becomes effective the next time a socket pends on a connection accept with timeout.

NetSock_CfgTimeoutConnAcceptGet_ms()#

Description#

Gets the socket's connection accept timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_INT32U  NetSock_CfgTimeoutConnAcceptGet_ms (NET_SOCK_ID   sock_id,
                                                RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get connection accept timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

Socket's connection accept network timeout value :

  • 0, on any error(s).

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is configured.

  • In number of milliseconds, otherwise.

Notes / Warnings#

Despite inconsistency with other 'Get' status functions, NetSock_CfgTimeoutConnAcceptGet_ms() includes 'Cfg' for consistency with other NetSock_CfgTimeout&&&() functions.

NetSock_CfgTimeoutConnAcceptSet()#

Description#

Sets the socket's connection accept timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutConnAcceptSet (NET_SOCK_ID   sock_id,
                                              CPU_INT32U    timeout_ms,
                                              RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set connection accept timeout.

timeout_ms

Desired timeout value :

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is desired.

  • In number of milliseconds, otherwise.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket connection accept timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket connection accept timeout in progress, but becomes effective the next time a socket pends on a connection accept with timeout.

NetSock_CfgTimeoutConnCloseDflt()#

Description#

Sets the socket's connection close configured-default timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutConnCloseDflt (NET_SOCK_ID   sock_id,
                                              RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set connection close timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket connection close configured-default timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket connection close timeout in progress, but becomes effective the next time a socket pends on a connection close with timeout.

NetSock_CfgTimeoutConnCloseGet_ms()#

Description#

Gets the socket's connection close timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_INT32U  NetSock_CfgTimeoutConnCloseGet_ms (NET_SOCK_ID   sock_id,
                                               RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get connection close timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

Socket's connection close network timeout value :

  • 0, on any error(s).

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is configured.

  • In number of milliseconds, otherwise.

Notes / Warnings#

Despite inconsistency with other 'Get' status functions, NetSock_CfgTimeoutConnCloseGet_ms() includes 'Cfg' for consistency with other NetSock_CfgTimeout&&&() functions.

NetSock_CfgTimeoutConnCloseSet()#

Description#

Sets the socket's connection close timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutConnCloseSet (NET_SOCK_ID   sock_id,
                                             CPU_INT32U    timeout_ms,
                                             RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set connection close timeout.

timeout_ms

Desired timeout value :

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket connection close timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket connection close timeout in progress, but becomes effective the next time a socket pends on a connection close with timeout.

NetSock_CfgTimeoutConnReqDflt()#

Description#

Sets the socket's connection request configured-default timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutConnReqDflt (NET_SOCK_ID   sock_id,
                                            RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set connection request timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket connection request configured-default timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket connection request timeout in progress, but becomes effective the next time a socket pends on a connection request with timeout.

NetSock_CfgTimeoutConnReqGet_ms()#

Description#

Gets the socket's connection request timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_INT32U  NetSock_CfgTimeoutConnReqGet_ms (NET_SOCK_ID   sock_id,
                                             RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get connection request timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

Socket's connection request network timeout value :

  • 0, on any error(s).

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is configured.

  • In number of milliseconds, otherwise.

Notes / Warnings#

  1. Despite inconsistency with other 'Get' status functions, NetSock_CfgTimeoutConnReqGet_ms() includes 'Cfg' for consistency with other NetSock_CfgTimeout&&&() functions.

NetSock_CfgTimeoutConnReqSet()#

Description#

Sets the socket's connection request timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutConnReqSet (NET_SOCK_ID   sock_id,
                                           CPU_INT32U    timeout_ms,
                                           RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set connection request timeout.

timeout_ms

Desired timeout value :

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is desired.

  • In number of milliseconds, otherwise.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_OK, socket connection request timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket connection request timeout in progress, but becomes effective the next time a socket pends on a connection request with timeout.

NetSock_CfgTimeoutRxQ_Dflt()#

Description#

Sets the socket's receive queue configured-default timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutRxQ_Dflt (NET_SOCK_ID   sock_id,
                                         RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set the configured receive queue.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

  • DEF_OK, socket receive queue configured-default timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket receive queue timeout in progress, but becomes effective the next time a socket pends on its receive queue with timeout.

NetSock_CfgTimeoutRxQ_Get_ms()#

Description#

Gets the socket's receive queue timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_INT32U  NetSock_CfgTimeoutRxQ_Get_ms (NET_SOCK_ID   sock_id,
                                          RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get receive queue timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

Socket's receive queue network timeout value :

  • 0, on any error(s).

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is configured.

  • In number of milliseconds, otherwise.

Notes / Warnings#

  1. Despite inconsistency with other 'Get' status functions, NetSock_CfgTimeoutRxQ_Get_ms() includes 'Cfg' for consistency with other NetSock_CfgTimeout&&&() functions.

NetSock_CfgTimeoutRxQ_Set()#

Description#

Sets the socket's receive queue timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutRxQ_Set (NET_SOCK_ID   sock_id,
                                        CPU_INT32U    timeout_ms,
                                        RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set receive queue timeout.

timeout_ms

Desired timeout value :

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is desired.

  • In number of milliseconds, otherwise.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

  • DEF_OK, socket receive queue timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket receive queue timeout in progress, but becomes effective the next time a socket pends on its receive queue with timeout.

NetSock_CfgTimeoutTxQ_Dflt()#

Description#

  1. Sets the socket's transmit queue configured-default timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutTxQ_Dflt (NET_SOCK_ID   sock_id,
                                         RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set transmit queue configured-default timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

  • DEF_OK, socket transmit queue configured-default timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket transmit queue timeout in progress, but becomes effective the next time a socket pends on its transmit queue with timeout.

NetSock_CfgTimeoutTxQ_Get_ms()#

Description#

  1. Gets the socket's transmit queue timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_INT32U  NetSock_CfgTimeoutTxQ_Get_ms (NET_SOCK_ID   sock_id,
                                          RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get transmit queue timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

Socket's transmit queue network timeout value :

  • 0, on any error(s).

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is configured.

  • In number of milliseconds, otherwise.

Notes / Warnings#

Despite inconsistency with other 'Get' status functions, NetSock_CfgTimeoutTxQ_Get_ms() includes 'Cfg' for consistency with other NetSock_CfgTimeout&&&() functions.

NetSock_CfgTimeoutTxQ_Set()#

Description#

  1. Sets the socket's transmit queue timeout value.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTimeoutTxQ_Set (NET_SOCK_ID   sock_id,
                                        CPU_INT32U    timeout_ms,
                                        RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set transmit queue timeout.

timeout_ms

Desired timeout value :

  • NET_TMR_TIME_INFINITE, if an infinite (i.e., NO timeout) value is desired.

  • In number of milliseconds, otherwise.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

  • DEF_OK, socket transmit queue timeout successfully set.

  • DEF_FAIL, otherwise.

Notes / Warnings#

Configured timeout does NOT reschedule any current socket transmit queue timeout in progress, but becomes effective the next time a socket pends on its transmit queue with timeout.

NetSock_CfgTxIP_TOS() (IPv4 only)#

Description#

Configures the socket's transmit IP TOS.

Files#

net_sock.h/net_sock.c

Prototype#

#ifdef  NET_IPv4_MODULE_EN

CPU_BOOLEAN  NetSock_CfgTxIP_TOS (NET_SOCK_ID    sock_id,
                                  NET_IPv4_TOS   ip_tos,
                                  RTOS_ERR      *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure transmit IP TOS.

ip_tos

Desired transmit IP TOS.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, socket transmit IP TOS successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetSock_CfgTxIP_TTL() (IPv4 only)#

Description#

Configures the socket's transmit IP TTL.

Files#

net_sock.h/net_sock.c

Prototype#

#ifdef  NET_IPv4_MODULE_EN

CPU_BOOLEAN  NetSock_CfgTxIP_TTL (NET_SOCK_ID    sock_id,
                                  NET_IPv4_TTL   ip_ttl,
                                  RTOS_ERR      *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure transmit IP TTL.

ip_ttl

Desired transmit IP TTL :

  • NET_IPv4_TTL_MIN Minimum TTL transmit value (1)

  • NET_IPv4_TTL_MAX Maximum TTL transmit value (255)

  • NET_IPv4_TTL_DFLT Default TTL transmit value (128)

  • NET_IPv4_TTL_NONE Replace with default TTL

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, socket transmit IP TTL successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetSock_CfgTxIP_TTL_Multicast() (IPv4 only)#

Description#

Configures the socket's transmit IP multicast TTL.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN NetSock_CfgTxIP_TTL_Multicast (NET_SOCK_ID    sock_id,
                                           NET_IPv4_TTL   ip_ttl,
                                           RTOS_ERR      *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure transmit IP multicast TTL.

ip_ttl

Desired transmit IP multicast TTL:

  • NET_IPv4_TTL_MIN Minimum TTL transmit value (1)

  • NET_IPv4_TTL_MAX Maximum TTL transmit value (255)

  • NET_IPv4_TTL_DFLT Default TTL transmit value (1)

  • NET_IPv4_TTL_NONE Replace with default TTL

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, socket transmit IP multicast TTL successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetSock_CfgTxQ_Size()#

Description#

Configures the socket's transmit queue size.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_CfgTxQ_Size (NET_SOCK_ID          sock_id,
                                  NET_SOCK_DATA_SIZE   size,
                                  RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to configure transmit queue size.

size

Desired transmit queue size.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • DEF_OK, socket transmit queue size successfully configured.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. For datagram sockets, configured size does NOT :

    (a) Partially truncate any received data. Instead, it allows data from exactly one received packet buffer to overflow the configured size since each datagram MUST be received atomically.

  2. For stream sockets, size MAY be required to be configured prior to connecting.

NetSock_Close()#

Description#

Closes a network socket.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_Close (NET_SOCK_ID   sock_id,
                                  RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to close.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_RETRY_MAX

  • RTOS_ERR_NET_SOCK_CLOSED

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

Returned Value#

  • NET_SOCK_BSD_ERR_NONE, if NO error(s).

  • NET_SOCK_BSD_ERR_CLOSE, otherwise.

Notes / Warnings#

  1. Once an application closes its socket, NO further operations on the socket are allowed and the application MUST NOT continue to access the socket.

  2. NO BSD socket error is returned for any internal error while closing the socket.

NetSock_Conn()#

Description#

Connects a network socket to a remote host.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_Conn (NET_SOCK_ID         sock_id,
                                 NET_SOCK_ADDR      *p_addr_remote,
                                 NET_SOCK_ADDR_LEN   addr_len,
                                 RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to connect.

p_addr_remote

Pointer to socket address structure.

addr_len

Length of socket address structure (in octets).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • NET_SOCK_BSD_ERR_NONE, if NO error(s).

  • NET_SOCK_BSD_ERR_CONN, otherwise.

Notes / Warnings#

  1. Socket address structure 'AddrFamily' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

  2. Socket address structure addresses MUST be configured/converted from host-order to network-order.

NetSock_GetConnTransportID()#

Description#

Get a socket's transport layer handle identifier.

Files#

net_sock.h/net_sock.c

Prototype#

NET_CONN_ID  NetSock_GetConnTransportID (NET_SOCK_ID   sock_id,
                                         RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get transport layer handle identifier.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

  • Socket's transport layer handle identifier, if NO error(s).

  • NET_CONN_ID_NONE, otherwise.

Notes / Warnings#

None.

NetSock_GetLocalIPAddr()#

Description#

Gets the local IP address used in the socket connection.

Files#

net_sock.h/net_sock.c

Prototype#

void  NetSock_GetLocalIPAddr (NET_SOCK_ID        sock_id,
                              CPU_INT08U        *p_buf_addr,
                              NET_SOCK_FAMILY   *p_family,
                              RTOS_ERR          *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier.

p_buf_addr

Pointer to a buffer to return the local IP address.

p_family

Pointer to the variable that will receive the connection family type of the local IP address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

None.

Notes / Warnings#

'p_buf_addr' must be a buffer at least of NET_CONN_ADDR_LEN_MAX bytes large.

NetSock_IsConn()#

Description#

Validates the socket currently in use and connected.

Files#

net_sock.h/net_sock.c

Prototype#

CPU_BOOLEAN  NetSock_IsConn (NET_SOCK_ID   sock_id,
                             RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

  • DEF_YES, socket valid and connected.

  • DEF_NO, socket invalid or NOT connected.

Notes / Warnings#

None.

NetSock_Listen()#

Description#

Sets socket to listen for connection requests.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_Listen (NET_SOCK_ID       sock_id,
                                   NET_SOCK_Q_SIZE   sock_q_size,
                                   RTOS_ERR         *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to listen.

sock_q_size

Maximum number of connection requests to accept and queue on listen socket.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • NET_SOCK_BSD_ERR_NONE, if NO error(s).

  • NET_SOCK_BSD_ERR_LISTEN, otherwise.

Notes / Warnings#

Socket listen operation valid for stream-type sockets only.

NetSock_Open()#

Description#

Opens a network socket.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_ID  NetSock_Open (NET_SOCK_PROTOCOL_FAMILY   protocol_family,
                           NET_SOCK_TYPE              sock_type,
                           NET_SOCK_PROTOCOL          protocol,
                           RTOS_ERR                  *p_err)

Arguments#

protocol_family

Socket protocol family :

  • NET_SOCK_PROTOCOL_FAMILY_IP_V4

  • NET_SOCK_PROTOCOL_FAMILY_IP_V6

sock_type

Socket type :

  • NET_SOCK_TYPE_DATAGRAM

  • NET_SOCK_TYPE_STREAM

protocol

Socket protocol :

  • NET_SOCK_PROTOCOL_DFLT

  • NET_SOCK_PROTOCOL_TCP

  • NET_SOCK_PROTOCOL_UDP

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

Returned Value#

  • Socket descriptor/handle identifier, if NO error(s).

  • NET_SOCK_BSD_ERR_OPEN, otherwise.

Notes / Warnings#

None.

NetSock_OptGet()#

Description#

Gets the specified socket option from the sock_id socket.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_OptGet (NET_SOCK_ID         sock_id,
                                   NET_SOCK_PROTOCOL   level,
                                   NET_SOCK_OPT_NAME   opt_name,
                                   void               *p_opt_val,
                                   NET_SOCK_OPT_LEN   *p_opt_len,
                                   RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket from which to get the option.

level

Protocol level from which to retrieve the socket option.

opt_name

Socket option to get the value.

p_opt_val

Pointer to a socket option value buffer.

p_opt_len

Pointer to a socket option value buffer length.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

Returned Value#

  • NET_SOCK_BSD_ERR_NONE, if NO error(s).

  • NET_SOCK_BSD_ERR_OPT_GET, otherwise.

Notes / Warnings#

  1. The supported options are:

    (a) Level NET_SOCK_PROTOCOL_SOCK:

    • NET_SOCK_OPT_SOCK_TYPE

    • NET_SOCK_OPT_SOCK_KEEP_ALIVE

    • NET_SOCK_OPT_SOCK_ACCEPT_CONN

    • NET_SOCK_OPT_SOCK_TX_BUF_SIZE

    • NET_SOCK_OPT_SOCK_RX_BUF_SIZE

    • NET_SOCK_OPT_SOCK_TX_TIMEOUT

    • NET_SOCK_OPT_SOCK_RX_TIMEOUT

    (b) Level NET_SOCK_PROTOCOL_IP:

    • NET_SOCK_OPT_IP_TOS

    • NET_SOCK_OPT_IP_TTL

    • NET_SOCK_OPT_IP_RX_IF

    (c) Level NET_SOCK_PROTOCOL_TCP:

    • NET_SOCK_OPT_TCP_NO_DELAY

    • NET_SOCK_OPT_TCP_KEEP_CNT

    • NET_SOCK_OPT_TCP_KEEP_IDLE

    • NET_SOCK_OPT_TCP_KEEP_INTVL

NetSock_OptSet()#

Description#

Sets the specified socket option of the socket to a specified value.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_OptSet (NET_SOCK_ID         sock_id,
                                   NET_SOCK_PROTOCOL   level,
                                   NET_SOCK_OPT_NAME   opt_name,
                                   void               *p_opt_val,
                                   NET_SOCK_OPT_LEN    opt_len,
                                   RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket from which to get the option.

level

Protocol level at which the option resides.

opt_name

Name of the single option to set.

p_opt_val

Pointer to the value to set to the socket option.

opt_len

Option length.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

Returned Value#

  • NET_SOCK_BSD_ERR_NONE, if NO error(s).

  • NET_SOCK_BSD_ERR_OPT_SET, otherwise.

Notes / Warnings#

  1. The size of the p_opt_val and the value of opt_len must be equal to the size of the socket option requested to be set.

  2. The supported options are:

    (a) Level NET_SOCK_PROTOCOL_SOCK:

    • NET_SOCK_OPT_SOCK_KEEP_ALIVE

    • NET_SOCK_OPT_SOCK_TX_BUF_SIZE

    • NET_SOCK_OPT_SOCK_RX_BUF_SIZE

    • NET_SOCK_OPT_SOCK_TX_TIMEOUT

    • NET_SOCK_OPT_SOCK_RX_TIMEOUT

    (b) Level NET_SOCK_PROTOCOL_IP:

    • NET_SOCK_OPT_IP_TOS

    • NET_SOCK_OPT_IP_TTL

    • NET_SOCK_OPT_IP_ADD_MEMBERSHIP

    • NET_SOCK_OPT_IP_DROP_MEMBERSHIP

    (c) Level NET_SOCK_PROTOCOL_TCP:

    • NET_SOCK_OPT_TCP_NO_DELAY

    • NET_SOCK_OPT_TCP_KEEP_CNT

    • NET_SOCK_OPT_TCP_KEEP_IDLE

    • NET_SOCK_OPT_TCP_KEEP_INTVL

NetSock_PoolStatGet()#

Description#

Gets the socket statistics pool.

Files#

net_sock.h/net_sock.c

Prototype#

NET_STAT_POOL  NetSock_PoolStatGet (void)

Arguments#

Returned Value#

  • Socket statistics pool, if NO error(s).

  • NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetSock_PoolStatResetMaxUsed()#

Description#

Resets the socket statistics pool's maximum number of entries used.

Files#

net_sock.h/net_sock.c

Prototype#

void  NetSock_PoolStatResetMaxUsed (void)

Arguments#

Returned Value#

None.

Notes / Warnings#

None.

NetSock_RxData()#

Description#

Receive data from a network socket.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_RxData (NET_SOCK_ID          sock_id,
                                   void                *p_data_buf,
                                   CPU_INT16U           data_buf_len,
                                   NET_SOCK_API_FLAGS   flags,
                                   RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to receive data.

p_data_buf

Pointer to an application data buffer that will receive the socket's received data.

data_buf_len

Size of the application data buffer (in octets).

flags

Flags to select receive options; bit-field flags logically OR'd :

  • NET_SOCK_FLAG_NONE No socket flags selected.

  • NET_SOCK_FLAG_RX_DATA_PEEK Receive socket data without consuming the socket data; i.e., socket data NOT removed from application receive queue(s).

  • NET_SOCK_FLAG_RX_NO_BLOCK Receive socket data without blocking.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_NET_CONN_CLOSE_RX

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_WOULD_OVF

Returned Value#

  • Number of positive data octets received, if NO error(s).

  • NET_SOCK_BSD_RTN_CODE_CONN_CLOSED, if socket connection closed.

  • NET_SOCK_BSD_ERR_RX, otherwise.

Notes / Warnings#

  1. (a)

    1. Datagram-type sockets transmit and receive all data atomically -- i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram.

    2. Thus if the socket's type is datagram and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data but the remaining data octets are discarded & RTOS_ERR_WOULD_OVF error is returned.

    (b)

    1. (A) Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      (B) Thus if the socket's type is stream and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data and the remaining data octets remain queued for later application-socket receives.

    2. Thus it is typical, but NOT absolutely required, that a single application task ONLY receive or request to receive data from a stream-type socket.

  2. Only some socket receive flag options are implemented. If other flag options are requested, NetSock_RxData() handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

NetSock_RxDataFrom()#

Description#

Receive data from a network socket.

This must be used with Datagram socket to know which remote host sent the data when there is no connection established for the Datagram type socket. This can be used for Stream type Socket, but it is not mandatory.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE NetSock_RxDataFrom (NET_SOCK_ID          sock_id,
                                      void                *p_data_buf,
                                      CPU_INT16U           data_buf_len,
                                      NET_SOCK_API_FLAGS   flags,
                                      NET_SOCK_ADDR       *p_addr_remote,
                                      NET_SOCK_ADDR_LEN   *p_addr_len,
                                      void                *p_ip_opts_buf,
                                      CPU_INT08U           ip_opts_buf_len,
                                      CPU_INT08U          *p_ip_opts_len,
                                      RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to receive data.

p_data_buf

Pointer to an application data buffer that will receive the socket's received data.

data_buf_len

Size of the application data buffer (in octets).

flags

Flags to select receive options; bit-field flags logically OR'd :

  • NET_SOCK_FLAG_NONE No socket flags selected.

  • NET_SOCK_FLAG_RX_DATA_PEEK Receive socket data without consuming the socket data; i.e., socket data NOT removed from application receive queue(s).

  • NET_SOCK_FLAG_RX_NO_BLOCK Receive socket data without blocking.

p_addr_remote

Pointer to an address buffer that will receive the socket address structure.

p_addr_len

Pointer to a variable to pass the size of the socket address structure and that will received the size of the accepted connection’s socket address structure, if no errors. Otherwise, a 0 size is returned.

p_ip_opts_buf

Pointer to buffer to receive possible IP options, if NO error(s).

ip_opts_buf_len

Size of IP options receive buffer (in octets).

p_ip_opts_len

Pointer to variable that will receive the return size of any received IP options, if NO error(s).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_NET_CONN_CLOSE_RX

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_WOULD_OVF

Returned Value#

  • Number of positive data octets received, if NO error(s).

  • NET_SOCK_BSD_RTN_CODE_CONN_CLOSED, if socket connection closed.

  • NET_SOCK_BSD_ERR_RX, otherwise.

Notes / Warnings#

  1. (a)

    1. Datagram-type sockets transmit and receive all data atomically -- i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram.

    2. Thus if the socket's type is datagram and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data but the remaining data octets are discarded and RTOS_ERR_WOULD_OVF error is returned.

    (b)

    1. A) Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      (B) Thus if the socket's type is stream and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data and the remaining data octets remain queued for later application-socket receives.

    2. Thus it is typical, but NOT absolutely required, that a single application task ONLY receive or request to receive data from a stream-type socket.

  2. Only some socket receive flag options are implemented. If other flag options are requested, NetSock_RxData() handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

  3. (a) If :

    1. NO IP options were received OR

    2. NO IP options receive buffer is provided OR

    3. IP options receive buffer NOT large enough for the received IP options then NO IP options are returned and any received IP options are silently discarded.

    (b) The IP options receive buffer size SHOULD be large enough to receive the maximum IP options size, NET_IPv4_HDR_OPT_SIZE_MAX.

    (c) Received IP options should be provided/decoded via appropriate IP layer API.

  4. IP options arguments may NOT be necessary (remove if unnecessary).

NetSock_Sel()#

Description#

Checks multiple sockets for available resources &/or operations.

Files#

net_sock.h/net_sock.c

Prototype#

#if (NET_SOCK_CFG_SEL_EN == DEF_ENABLED)

NET_SOCK_RTN_CODE  NetSock_Sel (NET_SOCK_QTY       sock_nbr_max,
                                NET_SOCK_DESC     *p_sock_desc_rd,
                                NET_SOCK_DESC     *p_sock_desc_wr,
                                NET_SOCK_DESC     *p_sock_desc_err,
                                NET_SOCK_TIMEOUT  *p_timeout,
                                RTOS_ERR          *p_err)

Arguments#

sock_nbr_max

Maximum number of socket descriptors/handle identifiers in the socket descriptor sets.

p_sock_desc_rd

Pointer to a set of socket descriptors/handle identifiers to :

  1. Check for available read operation(s).

  2. (a) Return the actual socket descriptors/handle identifiers ready for available read operation(s), if NO error(s).

    (b) Return the initial, non-modified set of socket descriptors/handle identifiers, on any error(s).

    (c) Return a null-valued (i.e., zero-cleared) descriptor set, if any timeout expires.

p_sock_desc_wr

Pointer to a set of socket descriptors/handle identifiers to :

  1. Check for available write operation(s).

  2. (a) Return the actual socket descriptors/handle identifiers ready for available write operation(s), if NO error(s).

    (b) Return the initial, non-modified set of socket descriptors/handle identifiers, on any error(s).

    (c) Return a null-valued (i.e., zero-cleared) descriptor set, if any timeout expires.

p_sock_desc_err

Pointer to a set of socket descriptors/handle identifiers to :

  1. Check for any error(s) and/or exception(s).

  2. (a) Return the actual socket descriptors/handle identifiers flagged with any error(s) &/or exception(s), if NO non-descriptor-related error(s).

    (b) Return the initial, non-modified set of socket descriptors/handle identifiers, on any error(s).

    (c) Return a null-valued (i.e., zero-cleared) descriptor set, if any timeout expires.

p_timeout

Pointer to a timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_ABORT

Returned Value#

  • Number of socket descriptors with available resources &/or operations, if any.

  • NET_SOCK_BSD_RTN_CODE_TIMEOUT, on timeout.

  • NET_SOCK_BSD_ERR_SEL, otherwise.

Notes / Warnings#

  1. (a) IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that :

    1. (A) "select() ... shall support" the following file descriptor types :

      1. "regular files," ...

      2. "terminal and pseudo-terminal devices," ...

      3. "STREAMS-based files," ...

      4. "FIFOs," ...

      5. "pipes," ...

      6. "sockets."

      (B) "The behavior of ... select() on ... other types of ... file descriptors ... is unspecified."

    2. Network Socket Layer supports BSD 4.x select() functionality with the following restrictions/constraints :

      (A) ONLY supports the following file descriptor types :

      1. Sockets

    (b) IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that :

    1. (A) "The 'nfds' argument ('sock_nbr_max') specifies the range of descriptors to be tested. The first 'nfds' descriptors shall be checked in each set. that is, the [following] descriptors ... in the descriptor sets shall be examined" :

      1. "from zero" ...

      2. "through nfds-1."

      (B) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 163 states that :

      1. ... since "descriptors start at 0" ...

      2. "the ['nfds'] argument" specifies :

        (a) "the number of descriptors," ...

        (b) "not the largest value."

    2. "The select() function shall ... examine the file descriptor sets whose addresses are passed in the 'readfds' ('p_sock_desc_rd'), 'writefds' ('p_sock_desc_wr'), and 'errorfds' ('p_sock_desc_err') parameters to see whether some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively."

      (A)

      1. (a) "If the 'readfds' argument ('p_sock_desc_rd') is not a null pointer, it points to an object of type 'fd_set' ('NET_SOCK_DESC') that on input specifies the file descriptors to be checked for being ready to read, and on output indicates which file descriptors are ready to read."

        (b) "A descriptor shall be considered ready for reading when a call to an input function ... would not block, whether or not the function would transfer data successfully. (The function might return data, an end-of-file indication, or an error other than one indicating that it is blocked, and in each of these cases the descriptor shall be considered ready for reading.)" :

        1. "If the socket is currently listening, then it shall be marked as readable if an incoming connection request has been received, and a call to the accept() function shall complete without blocking."

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Pages 164-165 states that "a socket is ready for reading if any of the following ... conditions is true" :

        1. "A read operation on the socket will not block and will return a value greater than 0 (i.e., the data that is ready to be read)."

        2. "The read half of the connection is closed (i.e., a TCP connection that has received a FIN). A read operation ... will not block and will return 0 (i.e., EOF)."

        3. "The socket is a listening socket and the number of completed connections is nonzero. An accept() on the listening socket will ... not block."

        4. "A socket error is pending. A read operation on the socket will not block and will return an error (-1) with 'errno' set to the specific error condition."

          (A) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states "that when an error occurs on a socket, it is [also] marked as both readable and writeable by select()".

      2. (a) "If the 'writefds' argument ('p_sock_desc_wr') is not a null pointer, it points to an object of type 'fd_set' ('NET_SOCK_DESC') that on input specifies the file descriptors to be checked for being ready to write, and on output indicates which file descriptors are ready to write."

        (b) "A descriptor shall be considered ready for writing when a call to an output function ... would not block, whether or not the function would transfer data successfully" :

        1. "If a non-blocking call to the connect() function has been made for a socket, and the connection attempt has either succeeded or failed leaving a pending error, the socket shall be marked as writable."

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states that "a socket is ready for writing if any of the following ... conditions is true" :

        1. "A write operation will not block and will return a positive value (e.g., the number of bytes accepted by the transport layer)."

        2. "The write half of the connection is closed."

        3. "A socket using a non-blocking connect() has completed the connection, or the connect() has failed."

        4. "A socket error is pending. A write operation on the socket will not block and will return an error (-1) with 'errno' set to the specific error condition."

          (A) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states "that when an error occurs on a socket, it is [also] marked as both readable and writeable by select()".

      3. (a) "If the 'errorfds' argument ('p_sock_desc_err') is not a null pointer, it points to an object of type 'fd_set' ('NET_SOCK_DESC') that on input specifies the file descriptors to be checked for error conditions pending, and on output indicates which file descriptors have error conditions pending."

        (b) "A file descriptor ... shall be considered to have an exceptional condition pending ... as noted below" :

        1. (A) "A socket ... receive operation ... [that] would return out-of-band data without blocking."

          (B) "A socket ... [with] out-of-band data ... present in the receive queue."

        2. "If a socket has a pending error."

        3. "Other circumstances under which a socket may be considered to have an exceptional condition pending are protocol-specific and implementation-defined."

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states that "a socket has an exception condition pending if ... any of the following ... conditions is true" :

        1. (A) "Out-of-band data for the socket" is currently available; ...

          (B) "Or the socket is still at the out-of-band mark."

        (d) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states "that when an error occurs on a socket, it is [also] marked as both readable and writeable by select()".

      (B)

      1. (a) "Upon successful completion, ... select() ... shall" :

        1. "modify the objects pointed to by the 'readfds' ('p_sock_desc_rd'), 'writefds' ('p_sock_desc_wr'), and 'errorfds' ('p_sock_desc_err') arguments to indicate which file descriptors are ready for reading, ready for writing, or have an error condition pending, respectively," ...

        2. "and shall return the total number of ready descriptors in all the output sets."

        (b)

        1. "For each file descriptor less than nfds ('sock_nbr_max'), the corresponding bit shall be set on successful completion" :

          (A) "if it was set on input" ...

          (B) "and the associated condition is true for that file descriptor."

        2. Conversely, "for each file descriptor ... the corresponding bit shall be ... [clear] ... on ... completion" :

          (A) If it was clear on input. ...

          (B) If the associated condition is NOT true for that file descriptor.

          (C) Or it was set on input, but any timeout occurs (see Note #3c2B).

      2. select() can NOT absolutely guarantee that descriptors returned as ready will still be ready during subsequent operations since any higher priority tasks or processes may asynchronously consume the descriptors' operations and/or resources. This can occur since select() functionality and subsequent operations are NOT atomic operations protected by network, file system, or operating system mechanisms.

      3. (A) "The 'timeout' parameter ('p_timeout') controls how long ... select() ... shall take before timing out."

        1. (a) "If the 'timeout' parameter ('p_timeout') is not a null pointer, it specifies a maximum interval to wait for the selection to complete."

          1. "If none of the selected descriptors are ready for the requested operation, ... select() ... shall block until at least one of the requested operations becomes ready ... or ... until the timeout occurs."

          2. "If the specified time interval expires without any requested operation becoming ready, the function shall return."

          3. "To effect a poll, the 'timeout' parameter ('p_timeout') should not be a null pointer, and should point to a zero-valued timespec structure ('NET_SOCK_TIMEOUT')."

          (b)

          1. (A) "If the 'readfds' ('p_sock_desc_rd'), 'writefds' ('p_sock_desc_wr'), and 'errorfds' ('p_sock_desc_err') arguments are" ...

            1. "all null pointers" ...

            2. [or all null-valued (i.e., no file descriptors set)]...

            (B) "and the 'timeout' argument ('p_timeout') is not a null pointer," ...

          2. ... then "select() ... shall block for the time specified".

        2. "If the 'timeout' parameter ('p_timeout') is a null pointer, then the call to ... select() shall block indefinitely until at least one descriptor meets the specified criteria."

          (a)

          1. Although IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that select() may "block indefinitely until ... one of the requested operations becomes ready ... or until interrupted by a signal", it does NOT explicitly specify how to handle the case where the descriptor arguments and the timeout parameter argument are all NULL pointers.

          2. However, since inter-process signals are NOT currently supported, it does NOT seem reasonable to block a task or process indefinitely (i.e., forever) if the descriptor arguments and the timeout parameter argument are all NULL pointers. Instead, an 'invalid timeout interval' error should be returned.

        (B)

        1. "For the select() function, the timeout period is given ... in an argument ('p_timeout') of type struct 'timeval' ('NET_SOCK_TIMEOUT')" ... :

          (a) "in seconds" ...

          (b) "and microseconds."

        2. (a)

          1. "Implementations may place limitations on the maximum timeout interval supported" :

            (A) "All implementations shall support a maximum timeout interval of at least 31 days."

            1. However, since maximum timeout interval values are dependent on the specific OS implementation; a maximum timeout interval can NOT be guaranteed.

            (B) "If the 'timeout' argument ('p_timeout') specifies a timeout interval greater than the implementation-defined maximum value, the maximum value shall be used as the actual timeout value."

          2. "Implementations may also place limitations on the granularity of timeout intervals" :

            (A) "If the requested 'timeout' interval requires a finer granularity than the implementation supports, the actual timeout interval shall be rounded up to the next supported value."

          (b) Operating systems may have different minimum/maximum ranges and resolutions for timeouts while pending or waiting on an operating system resource to become available (see Note #3b3A1a) versus time delays for suspending a task or process that is NOT pending or waiting for an operating system resource (see Note #3b3A1b).

          (c)

          1. (A) IEEE Std 1003.1, 2004 Edition, Section 'select() : RETURN VALUE' states that :

            1. "Upon successful completion, ... select() ... shall return the total number of bits set in the bit masks."

            2. (a) "Otherwise, -1 shall be returned," ...

              (b) "and 'errno' shall be set to indicate the error." 'errno' NOT currently supported (see 'net_bsd.h Note #1b').

            (B) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 161 states that BSD select() function "returns ... 0 on timeout".

          2. IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that :

            (A) "On failure, the objects pointed to by the 'readfds' ('p_sock_desc_rd'), 'writefds' ('p_sock_desc_wr'), and 'errorfds' ('p_sock_desc_err') arguments shall not be modified."

            1. Since 'p_sock_desc_rd', 'p_sock_desc_wr', and 'p_sock_desc_err' arguments are both input and output arguments; their input values, prior to use, MUST be copied to return their initial input values PRIOR to all other validation or function handling in case of any error(s).

            (B) "If the 'timeout' interval expires without the specified condition being true for any of the specified file descriptors, the objects pointed to by the 'readfds' ('p_sock_desc_rd'), 'writefds' ('p_sock_desc_wr'), and 'errorfds' ('p_sock_desc_err') arguments shall have all bits set to 0."

          (d) IEEE Std 1003.1, 2004 Edition, Section 'select() : ERRORS' states that "under the following conditions, ... select() shall fail and set 'errno' to" :

          1. "[EBADF] - One or more of the file descriptor sets specified a file descriptor that is not a valid open file descriptor."

          2. "[EINVAL]" -

            (A) "The 'nfds' argument ('sock_nbr_max') is" :

            1. "less than 0 or" ...

            2. "greater than FD_SETSIZE."

            (B) "An invalid timeout interval was specified."

          3. A socket events table lists requested socket or connection ID numbers/handle identifiers and their respective socket event operations.

            (a) Socket event tables are terminated with NULL table entry values.

            (b)

            1. NET_SOCK_CFG_SEL_NBR_EVENTS_MAX configures socket event tables' maximum number of socket events/operations.

            2. This value is used to declare the size of the socket events tables. Note that one additional table entry is added for a terminating NULL table entry at a maximum table index 'NET_SOCK_CFG_SEL_NBR_EVENTS_MAX'.

          4. Since datagram-type sockets typically never wait on transmit operations, no socket event should wait on datagram-type socket transmit operations or transmit errors.

NetSock_SelAbort()#

Description#

Aborts (unblocks) all tasks that are pending on a particular socket using the select.

Files#

net_sock.h/net_sock.c

Prototype#

void  NetSock_SelAbort (NET_SOCK_ID   sock_id,
                        RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to abort the select.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetSock_TxData()#

Description#

Transmits data through a socket.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_TxData (NET_SOCK_ID          sock_id,
                                   void                *p_data,
                                   CPU_INT16U           data_len,
                                   NET_SOCK_API_FLAGS   flags,
                                   RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to transmit data.

p_data

Pointer to application data to transmit.

data_len

Length of application data to transmit (in octets).

flags

Flags to select transmit options; bit-field flags logically OR'd :

  • NET_SOCK_FLAG_NONE No socket flags selected.

  • NET_SOCK_FLAG_TX_NO_BLOCK Transmit socket data without blocking.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_RETRY_MAX

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • FAULT

  • RTOS_ERR_NET_ADDR_UNRESOLVED

Returned Value#

  • Number of positive data octets transmitted, if NO error(s).

  • NET_SOCK_BSD_RTN_CODE_CONN_CLOSED, if socket connection closed.

  • NET_SOCK_BSD_ERR_TX, otherwise.

Notes / Warnings#

  1. (a)

    1. (A) Datagram-type sockets transmit and receive all data atomically -- i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram. Thus each call to transmit data MUST be transmitted in a single, complete datagram.

      (B) Since IP transmit fragmentation is NOT currently supported (see 'net_ip.h Note #1d'), if the socket's type is datagram and the requested transmit data length is greater than the socket/transport layer MTU, then NO data is transmitted and RTOS_ERR_WOULD_OVF error is returned.

    2. (A)

      1. Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      2. Thus if the socket's type is stream and the socket's transmit data queue(s) are NOT large enough for the transmitted data, the transmit data queue(s) are maximally filled with transmit data and the remaining data octets are discarded but may be re-transmitted by later application-socket transmits.

      3. Therefore, NO stream-type socket transmit data length should be "too long to pass through the underlying protocol" and cause the socket transmit to "fail ... [with] no data ... transmitted" (see Note #3a1B1).

      (B) Thus it is typical -- but NOT absolutely required -- that a single application task ONLY transmit or request to transmit data to a stream-type socket.

    (b) 'data_len' of 0 octets NOT allowed.

  2. Only some socket transmit flag options are implemented. If other flag options are requested, NetSock_TxData() handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

  3. Although NO socket send() specification states to return '0' when the socket's connection is closed, it seems reasonable to return '0' since it is possible for the socket connection to be close()'d or shutdown() by the remote host.

NetSock_TxDataTo()#

Description#

Transmit data through a network socket. This must be used with the Datagram type socket to specify the remote destination address, since no connection has been established for Datagram socket type.

Files#

net_sock.h/net_sock.c

Prototype#

NET_SOCK_RTN_CODE  NetSock_TxDataTo (NET_SOCK_ID          sock_id,
                                     void                *p_data,
                                     CPU_INT16U           data_len,
                                     NET_SOCK_API_FLAGS   flags,
                                     NET_SOCK_ADDR       *p_addr_remote,
                                     NET_SOCK_ADDR_LEN    addr_len,
                                     RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to transmit data.

p_data

Pointer to application data to transmit.

data_len

Length of application data to transmit (in octets).

flags

Flags to select transmit options; bit-field flags logically OR'd :

  • NET_SOCK_FLAG_NONE No socket flags selected.

  • NET_SOCK_FLAG_TX_NO_BLOCK Transmit socket data without blocking.

p_addr_remote

Pointer to destination address buffer.

addr_len

Length of destination address buffer (in octets).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_RETRY_MAX

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_NET_ADDR_UNRESOLVED

Returned Value#

  • Number of positive data octets transmitted, if NO error(s).

  • NET_SOCK_BSD_RTN_CODE_CONN_CLOSED, if socket connection closed.

  • NET_SOCK_BSD_ERR_TX, otherwise.

Notes / Warnings#

  1. (a)

    1. (A) Datagram-type sockets transmit and receive all data atomically -- i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram. Thus each call to transmit data MUST be transmitted in a single, complete datagram.

      (B) Since IP transmit fragmentation is NOT currently supported, if the socket's type is datagram and the requested transmit data length is greater than the socket/transport layer MTU, then NO data is transmitted and RTOS_ERR_WOULD_OVF error is returned.

    2. (A)

      1. Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      2. Thus if the socket's type is stream and the socket's transmit data queue(s) are NOT large enough for the transmitted data, the transmit data queue(s) are maximally filled with transmit data and the remaining data octets are discarded but may be re-transmitted by later application-socket transmits.

      3. Therefore, NO stream-type socket transmit data length should be "too long to pass through the underlying protocol" and cause the socket transmit to "fail ... [with] no data ... transmitted".

      (B) Thus it is typical -- but NOT absolutely required -- that a single application task ONLY transmit or request to transmit data to a stream-type socket.

    (b) 'data_len' of 0 octets NOT allowed.

  2. Only some socket transmit flag options are implemented. If other flag options are requested, NetSock_TxData() handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

  3. Although NO socket send() specification states to return '0' when the socket's connection is closed, it seems reasonable to return '0' since it is possible for the socket connection to be close()'d or shutdown() by the remote host.

BSD Sockets Functions API#

Function Name

Description

accept()

Wait for new socket connections on a listening server socket.

bind()

Assign network addresses to sockets.

close()

Terminate communication and free a socket.

connect()

Connect a local socket to a remote socket address.

FD_CLR()

Remove a socket file descriptor ID as a member of a file descriptor set.

FD_ISSET()

Check if a socket file descriptor ID is a member of a file descriptor set.

FD_SET()

Add a socket file descriptor ID as a member of a file descriptor set.

FD_ZERO()

Initialize/zero-clear a file descriptor set.

getsockopt()

Get a specific option value on a specific TCP socket.

htonl()

Convert 32-bit integer values from CPU host-order to network-order.

htons()

Convert 16-bit integer values from CPU host-order to network-order.

inet_addr()

Convert a string of an IPv4 address in dotted-decimal notation to an IPv4 address in host-order.

inet_aton()

Convert an IPv4 address in ASCII dotted-decimal notation to a network protocol IPv4 address in network-order.

inet_ntoa()

Convert an IPv4 address in host-order into an IPv4 dotted-decimal notation ASCII strin

inet_ntop()

Converts an IPv4 or IPv6 Internet network address into a string in Internet standard format.

inet_pton()

Converts an IPv4 or IPv6 Internet network address in its standard text presentation form into its numeric binary form.

getaddrinfo()

Converts human-readable text strings representing hostnames or IP addresses into a dynamically allocated linked list of struct addrinfo structures.

freeaddrinfo()

Frees addrinfo structures information that getaddrinfo() has allocated.

listen()

Set a socket to accept incoming connections.

ntohl()

Convert 32-bit integer values from network-order to CPU host-order.

ntohs()

Convert 16-bit integer values from network-order to CPU host-order.

recv() / recvfrom()

Copy up to a specified number of bytes received from a remote socket into an application memory buffer.

select()

Check if any sockets are ready for available read or write operations or error conditions.

send() / sentto()

Copy bytes from an application memory buffer into a socket to send to a remote socket.

setsockopt()

Set a specific option on a specific TCP socket.

socket()

Create a datagram (i.e., UDP) or stream (i.e., TCP) type socket.

accept() (TCP only)#

Description#

Gets a new accepted socket from a socket set to listen for connection requests.

Files#

net_bsd.h/net_bsd.c

Prototype#

#ifdef  NET_SOCK_TYPE_STREAM_MODULE_EN

int  accept (        int         sock_id,
             struct  sockaddr   *p_addr_remote,
                     socklen_t  *p_addr_len)

Arguments#

sock_id

Socket descriptor/handle identifier of listen socket.

p_addr_remote

Pointer to an address buffer that will receive the socket address structure of the accepted socket's remote address, if NO error(s).

p_addr_len

Pointer to a variable to pass the size of the address buffer pointed to by 'p_addr_remote' and returns the actual size of socket address structure with the accepted socket's remote address, if NO error(s). Return 0, otherwise.

Returned Value#

  • Socket descriptor/handle identifier of new accepted socket, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

  1. Socket address structure 'sa_family' member returned in host-order and SHOULD NOT be converted to network-order.

  2. Socket address structure addresses returned in network-order and SHOULD be converted from network-order to host-order.

bind()#

Description#

Binds a socket to a local address.

Files#

net_bsd.h/net_bsd.c

Prototype#

int  bind (        int         sock_id,
           struct  sockaddr   *p_addr_local,
                   socklen_t   addr_len)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to bind to a local address.

p_addr_local

Pointer to socket address structure.

addr_len

Length of socket address structure (in octets).

Returned Value#

  • 0, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

  1. Socket address structure 'sa_family' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

  2. Socket address structure addresses MUST be configured/converted from host-order to network-order.

close()#

Description#

Closes a socket.

Files#

net_bsd.h/net_bsd.c

Prototype#

int  close (int  sock_id)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to close.

Returned Value#

  • 0, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

Once an application closes its socket, NO further operations on the socket are allowed and the application MUST NOT continue to access the socket.

connect()#

Description#

Connects a socket to a remote server.

Files#

net_bsd.h/net_bsd.c

Prototype#

int  connect (        int         sock_id,
              struct  sockaddr   *p_addr_remote,
                      socklen_t   addr_len)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to connect.

p_addr_remote

Pointer to socket address structure (see Note #1).

addr_len

Length of socket address structure (in octets).

Returned Value#

  • 0, if NO error(s). -1, otherwise.

Notes / Warnings#

  1. Socket address structure 'sa_family' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

  2. Socket address structure addresses MUST be configured/converted from host-order to network-order.

FD_CLR()#

Remove a socket file descriptor ID as a member of a file descriptor set. See function NET_SOCK_DESC_CLR() for more information.

Files#

net_bsd.h

Prototype#

 FD_CLR(fd, fdsetp);

Required Configuration#

None.

FD_ISSET()#

Check if a socket file descriptor ID is a member of a file descriptor set. See function NET_SOCK_DESC_IS_SET() for more information.

Files#

net_bsd.h

Prototype#

          FD_ISSET(fd, fdsetp);

Required Configuration#

None.

FD_SET()#

Add a socket file descriptor ID as a member of a file descriptor set. See function NET_SOCK_DESC_SET() for more information.

Files#

net_bsd.h

Prototype#

          FD_SET(fd, fdsetp);

Required Configuration#

None.

FD_ZERO()#

Initialize/zero-clear a file descriptor set. See function NET_SOCK_DESC_INIT() for more information.

Files#

net_bsd.h

Prototype#

          FD_ZERO(fdsetp);

Required Configuration#

None.

getsockopt()#

Description#

Gets the socket option.

Files#

net_bsd.h/net_bsd.c

Prototype#

int  getsockopt (int         sock_id,
                 int         protocol,
                 int         opt_name,
                 void       *p_opt_val,
                 socklen_t  *p_opt_len)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to get the option.

protocol

Protocol level at which the option resides.

opt_name

Name of the single socket option to get.

p_opt_val

Pointer to the socket option value to get.

opt_len

Option length.

Returned Value#

  • 0, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

None.

htonl()#

Convert 32-bit integer values from CPU host-order to network-order. See function NET_UTIL_HOST_TO_NET_32 for more information.

Files#

net_bsd.h

Prototype#

          htonl(val);

Required Configuration#

None.

htons()#

Convert 16-bit integer values from CPU host-order to network-order. See function NET_UTIL_HOST_TO_NET_16 for more information.

Files#

net_bsd.h

Prototype#

          htons(val);

inet_addr() (IPv4 only)#

Description#

Converts an IPv4 address in ASCII dotted-decimal notation to a network protocol IPv4 address in network-order.

Files#

net_bsd.h/net_bsd.c

Prototype#

in_addr_t  inet_addr (char  *p_addr)

Arguments#

p_addr

Pointer to an ASCII string that contains a dotted-decimal IPv4 address (see Note #2).

Returned Value#

  • Network-order IPv4 address represented by ASCII string, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

  1. RFC #1983 states that "dotted decimal notation ... refers [to] IP addresses of the form A.B.C.D; where each letter represents, in decimal, one byte of a four byte IP address." In other words, the dotted-decimal notation separates four decimal octet values by the dot (or period) character ('.'). Each decimal value represents one octet of the IP address starting with the most significant octet in network-order.

    IP Address Examples : 192.168.1.64 = 0xC0A80140

  2. The dotted-decimal ASCII string MUST :

    (a) Include ONLY decimal values and the dot (or period) character ('.'). ALL other characters are trapped as invalid, including any leading or trailing characters.

    (b) Include UP TO four decimal values separated by UP TO three dot characters and MUST be terminated with the NULL character.

    (c) Ensure that each decimal value does NOT exceed the maximum octet value (i.e., 255).

    (d) Ensure that each decimal value does NOT include leading zeros.

inet_aton() (IPv4 only)#

Description#

Converts an IPv4 address in ASCII dotted-decimal notation to a network protocol IPv4 address in network-order.

Files#

net_bsd.h/net_bsd.c

Prototype#

#ifdef  NET_IPv4_MODULE_EN

int  inet_aton(       char     *p_addr_in,
               struct in_addr  *p_addr)

Arguments#

p_addr_in

Pointer to an ASCII string that contains a dotted-decimal IPv4 address.

p_addr

Pointer to an IPv4 address.

Returned Value#

  • 1 if the supplied address is valid.

  • 0, otherwise.

Notes / Warnings#

  1. RFC #1983 states that "dotted decimal notation ... refers [to] IP addresses of the form A.B.C.D; where each letter represents, in decimal, one byte of a four byte IP address."

  2. IEEE Std 1003.1, 2004 Edition - inet_addr, inet_ntoa - IPv4 address manipulation:

    (a) Values specified using IPv4 dotted decimal notation take one of the following forms:

    1. a.b.c.d - With a four-part address, each part shall be interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address.

    2. a.b.c - With a three-part address, the last part shall be interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as "128.net.host".

    3. a.b - With a two-part address, the last part shall be interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as "net.host".

    4. a - With a one-part address, the value shall be stored directly in the network address without any byte rearrangement.

  3. The dotted-decimal ASCII string MUST :

    (a) Include ONLY decimal values and the dot (or period) character ('.'). ALL other characters trapped are invalid, including any leading or trailing characters.

    (b) Include UP TO four decimal values separated by UP TO three dot characters and MUST be terminated with the NULL character.

    (c) Ensure that each decimal value does NOT exceed the maximum value for its form:

    1. a.b.c.d - 255.255.255.255

    2. a.b.c - 255.255.65535

    3. a.b - 255.16777215

    4. a - 4294967295

    (d) Ensure that each decimal value does NOT include leading zeros.

inet_ntoa() (IPv4 only)#

Description#

Converts a network protocol IPv4 address into a dotted-decimal notation ASCII string.

Files#

net_bsd.h/net_bsd.c

Prototype#

#ifdef  NET_IPv4_MODULE_EN

char  *inet_ntoa (struct  in_addr  addr)

Arguments#

addr

IPv4 address.

Returned Value#

Pointer to ASCII string of converted IPv4 address, if NO error(s). Pointer to NULL, otherwise.

Notes / Warnings#

  1. RFC #1983 states that "dotted decimal notation ... refers [to] IP addresses of the form A.B.C.D; where each letter represents, in decimal, one byte of a four byte IP address."

    In other words, the dotted-decimal notation separates four decimal octet values by the dot (or period) character ('.'). Each decimal value represents one octet of the IP address starting with the most significant octet in network-order.

    IP Address Examples : 192.168.1.64 = 0xC0A80140

  2. IEEE Std 1003.1, 2004 Edition, Section 'inet_ntoa() : DESCRIPTION' states that "inet_ntoa() ... need not be reentrant ... [and] is not required to be thread-safe."

    Since the character string is returned in a single, global character string array, this conversion function is NOT re-entrant.

inet_ntop()#

Description#

Converts an IPv4 or IPv6 Internet network address into a string in Internet standard format.

Files#

net_bsd.h/net_bsd.c

Prototype#

const char *inet_ntop (      int        af,
                       const void      *src,
                             char      *dst,
                             socklen_t  size)

Arguments#

af

Address family:

  • AF_INET IPv4 Address Family

  • AF_INET6 IPv6 Address Family

src

A pointer to the IP address in network byte to convert to a string.

dst

A pointer to a buffer in which to store the NULL-terminated string representation of the IP address.

size

Length, in characters, of the buffer pointed to by dst.

Returned Value#

  • Pointer to a buffer containing the string representation of IP address in the standard format, If no error occurs.

  • DEF_NULL, otherwise.

Notes / Warnings#

None.

inet_pton()#

Description#

Converts an IPv4 or IPv6 Internet network address in its standard text presentation form into its numeric binary form.

Files#

net_bsd.h/net_bsd.c

Prototype#

int inet_pton (      int   af,
               const char *src,
                     void *dst);

Arguments#

af

Address family:

  • AF_INET IPv4 Address Family

  • AF_INET6 IPv6 Address Family

src

A pointer to the IP address in network byte to convert to a string.

dst

A pointer to a buffer in which to store the NULL-terminated string representation of the IP address.

Returned Value#

  • 1, if no error.

  • 0, if src does not contain a character string representing a valid network address in the specified address family.

  • -1, if af does not contain a valid address family.

Notes / Warnings#

None.

getaddrinfo()#

Description#

Converts human-readable text strings representing hostnames or IP addresses into a dynamically allocated linked list of struct addrinfo structures.

Files#

net_bsd.h/net_bsd.c

Prototype#

int getaddrinfo (const        char      *p_node_name,
                 const        char      *p_service_name,
                 const struct addrinfo  *p_hints,
                       struct addrinfo **pp_res)

Arguments#

p_node_name

A pointer to a string that contains a host (node) name or a numeric host address string. For the Internet protocol, the numeric host address string is a dotted-decimal IPv4 address or an IPv6 hex address.

p_service_name

A pointer to a string that contains either a service name or port number represented as a string.

p_hints

A pointer to an addrinfo structure that provides hints about the type of socket the caller supports.

pp_res

A pointer to a linked list of one or more addrinfo structures that contains response information about the host.

Returned Value#

  • 0, if no error,

Most nonzero error codes returned map to the set of errors outlined by Internet Engineering Task Force (IETF) recommendations:

  • EAI_ADDRFAMILY

  • EAI_AGAIN

  • EAI_BADFLAGS

  • EAI_FAIL

  • EAI_FAMILY

  • EAI_MEMORY

  • EAI_NONAME

  • EAI_OVERFLOW

  • EAI_SERVICE

  • EAI_SOCKTYPE

  • EAI_SYSTEM

Notes / Warnings#

None.

freeaddrinfo()#

Description#

Frees addrinfo structures information that getaddrinfo() has allocated.

Files#

net_bsd.h/net_bsd.c

Prototype#

void freeaddrinfo(struct addrinfo *res)

Arguments#

res

A pointer to the addrinfo structure or linked list of addrinfo structures to be freed.

Returned Value#

None.

Notes / Warnings#

None.

listen() (TCP only)#

Description#

Sets a socket to listen for connection requests.

Files#

net_bsd.h/net_bsd.c

Prototype#

#ifdef  NET_SOCK_TYPE_STREAM_MODULE_EN

int  listen (int  sock_id,
             int  sock_q_size)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to listen.

sock_q_size

Number of connection requests to queue on listen socket.

Returned Value#

  • 0, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

None.

ntohl()#

Convert 32-bit integer values from network-order to CPU host-order. See function NET_UTIL_NET_TO_HOST_32 for more information.

Files#

net_bsd.h

Prototype#

  ntohl(val);

Required Configuration#

None.

ntohs()#

Convert 16-bit integer values from network-order to CPU host-order. See function NET_UTIL_NET_TO_HOST_16 for more information.

Files#

net_bsd.h

Prototype#

    ntohs(val);

Required Configuration#

None.

recv()#

Description#

Receives data from a socket.

Files#

net_bsd.h/net_bsd.c

Prototype#

ssize_t  recv (int      sock_id,
               void    *p_data_buf,
              _size_t   data_buf_len,
               int      flags)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to receive data.

p_data_buf

Pointer to an application data buffer that will receive the socket's received data.

data_buf_len

Size of the application data buffer (in octets).

flags

Flags to select receive options; bit-field flags logically OR'd :

  • 0 No socket flags selected.

  • MSG_PEEK Receive socket data without consuming the socket data.

  • MSG_DONTWAIT Receive socket data without blocking.

Returned Value#

  • Number of positive data octets received, if NO error(s). - 0, if socket connection closed.

  • -1, otherwise.

Notes / Warnings#

  1. (a)

    1. Datagram-type sockets transmit and receive all data atomically -- i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram.

    2. Thus if the socket's type is datagram and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data but the remaining data octets are discarded and RTOS_ERR_WOULD_OVF error is returned.

    (b)

    1. (A) Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      (B) Thus if the socket's type is stream and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data and the remaining data octets remain queued for later application-socket receives.

    2. It is typical, but NOT absolutely required, that a single application task ONLY receive or request to receive data from a stream-type socket.

  2. Only some socket receive flag options are implemented. If other flag options are requested, socket receive handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

  3. IEEE Std 1003.1, 2004 Edition, Section 'recv() : RETURN VALUE' states that :

    (a) "Upon successful completion, recv() shall return the length of the message in bytes."

    (b) "If no messages are available to be received and the peer has performed an orderly shutdown, recv() shall return 0."

    (c)

    1. "Otherwise, -1 shall be returned"

    2. "and 'errno' set to indicate the error." 'errno' is NOT currently supported.

recvfrom()#

Description#

Receives data from a socket.

Files#

net_bsd.h/net_bsd.c

Prototype#

ssize_t  recvfrom (        int         sock_id,
                           void       *p_data_buf,
                          _size_t      data_buf_len,
                           int         flags,
                   struct  sockaddr   *p_addr_remote,
                           socklen_t  *p_addr_len)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to receive data.

p_data_buf

Pointer to an application data buffer that will receive the socket's received data.

data_buf_len

Size of the application data buffer (in octets).

flags

Flags to select receive options; bit-field flags logically OR'd :

  • 0 No socket flags selected.

  • MSG_PEEK Receive socket data without consuming the socket data.

  • MSG_DONTWAIT Receive socket data without blocking.

p_addr_remote

Pointer to an address buffer that will receive the socket address structure with the received data's remote address, if NO error(s).

p_addr_len

Pointer to a variable to pass the size of the address buffer pointed to by 'p_addr_remote' and returns the actual size of socket address structure with the received data's remote address, if NO error(s). Return 0, otherwise.

Returned Value#

  • Number of positive data octets received, if NO error(s).

  • 0, if socket connection closed.

  • -1, otherwise.

Notes / Warnings#

  1. (a)

    1. Datagram-type sockets transmit and receive all data atomically (i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram).

    2. If the socket's type is datagram and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data but the remaining data octets are discarded and NET_SOCK_ERR_INVALID_DATA_SIZE error is returned.

    (b)

    1. (A) Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      (B) Thus if the socket's type is stream and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data and the remaining data octets remain queued for later application-socket receives.

    2. It is typical, but NOT absolutely required, that a single application task ONLY receive or request to receive data from a stream-type socket.

  2. Only some socket receive flag options are implemented. If other flag options are requested, socket receive handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

  3. (a) Socket address structure 'sa_family' member returned in host-order and SHOULD NOT be converted to network-order.

    (b) Socket address structure addresses returned in network-order and SHOULD be converted from network-order to host-order.

  4. IEEE Std 1003.1, 2004 Edition, Section 'recvfrom() : RETURN VALUE' states that :

    (a) "Upon successful completion, recvfrom() shall return the length of the message in bytes."

    (b) "If no messages are available to be received and the peer has performed an orderly shutdown, recvfrom() shall return 0."

    (c)

    1. "Otherwise, [-1 shall be returned]"

    2. "and 'errno' set to indicate the error." 'errno' is NOT currently supported.

select()#

Description#

Checks multiple file descriptors for available resources and/or operations.

Files#

net_bsd.h/net_bsd.c

Prototype#

#if    (NET_SOCK_CFG_SEL_EN == DEF_ENABLED)

int  select (        int       desc_nbr_max,
             struct  fd_set   *p_desc_rd,
             struct  fd_set   *p_desc_wr,
             struct  fd_set   *p_desc_err,
             struct  timeval  *p_timeout)

Arguments#

desc_nbr_max

Maximum number of file descriptors in the file descriptor sets.

p_desc_rd

Pointer to a set of file descriptors to :

  1. Check for available read operation(s).

  2. (a) Return the actual file descriptors ready for available read operation(s), if NO error(s).

    (b) Return the initial, non-modified set of file descriptors, on any error(s).

    (c) Return a null-valued (i.e., zero-cleared) descriptor set, if any timeout expires.

p_desc_wr

Pointer to a set of file descriptors to :

  1. Check for available write operation(s).

  2. (a) Return the actual file descriptors ready for available write operation(s), if NO error(s).

    (b) Return the initial, non-modified set of file descriptors, on any error(s).

    (c) Return a null-valued (i.e., zero-cleared) descriptor set, if any timeout expires.

p_desc_err

Pointer to a set of file descriptors to :

  1. Check for any error(s) and/or exception(s).

  2. (a) Return the actual file descriptors flagged with any error(s) and/or exception(s), if NO non-descriptor-related error(s);

    (b) Return the initial, non-modified set of file descriptors, on any error(s);

    (c) Return a null-valued (i.e., zero-cleared) descriptor set, if any timeout expires.

p_timeout

Pointer to a timeout.

Returned Value#

  • Number of file descriptors with available resources and/or operations, if any.

  • 0, on timeout.

  • -1, otherwise.

Notes / Warnings#

  1. (a) IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that :

    1. (A) "select() ... shall support" the following file descriptor types :

      1. "regular files"

      2. "terminal and pseudo-terminal devices"

      3. "STREAMS-based files"

      4. "FIFOs"

      5. "pipes"

      6. "sockets"

      (B) "The behavior of ... select() on ... other types of ... file descriptors ... is unspecified."

    2. Network Socket Layer supports BSD 4.x select() functionality with the following restrictions/constraints :

      (A) ONLY supports the following file descriptor types :

      1. Sockets

    (b) IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that :

    1. (A) "The 'nfds' argument ('desc_nbr_max') specifies the range of descriptors to be tested. The first 'nfds' descriptors shall be checked in each set; the descriptors from zero through nfds-1 in the descriptor sets shall be examined."

      (B) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 163 states that "the ['nfds'] argument" specifies :

      1. "the number of descriptors" ...

      2. "not the largest value"

    2. "The select() function shall ... examine the file descriptor sets whose addresses are passed in the 'readfds' ('p_desc_rd'), 'writefds' ('p_desc_wr'), and 'errorfds' ('p_desc_err') parameters to see whether some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively."

      (A)

      1. (a) "If the 'readfds' argument ('p_desc_rd') is not a null pointer, it points to an object of type 'fd_set' that on input specifies the file descriptors to be checked for being ready to read, and on output indicates which file descriptors are ready to read."

        (b) "A descriptor shall be considered ready for reading when a call to an input function ... would not block, whether or not the function would transfer data successfully. (The function might return data, an end-of-file indication, or an error other than one indicating that it is blocked, and in each of these cases the descriptor shall be considered ready for reading.)" :

        1. "If the socket is currently listening, then it shall be marked as readable if an incoming connection request has been received, and a call to the accept() function shall complete without blocking."

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Pages 164-165 states that "a socket is ready for reading if any of the following ... conditions is true" :

        1. "A read operation on the socket will not block and will return a value greater than 0 (i.e., the data that is ready to be read)."

        2. "The read half of the connection is closed (i.e., a TCP connection that has received a FIN). A read operation ... will not block and will return 0 (i.e., EOF)."

        3. "The socket is a listening socket and the number of completed connections is nonzero. An accept() on the listening socket will ... not block."

        4. "A socket error is pending. A read operation on the socket will not block and will return an error (-1) with 'errno' set to the specific error condition."

      2. (a) "If the 'writefds' argument ('p_desc_wr') is not a null pointer, it points to an object of type 'fd_set' that on input specifies the file descriptors to be checked for being ready to write, and on output indicates which file descriptors are ready to write."

        (b) "A descriptor shall be considered ready for writing when a call to an output function ... would not block, whether or not the function would transfer data successfully" :

        1. "If a non-blocking call to the connect() function has been made for a socket, and the connection attempt has either succeeded or failed leaving a pending error, the socket shall be marked as writable."

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states that "a socket is ready for writing if any of the following ... conditions is true" :

        1. "A write operation will not block and will return a positive value (e.g., the number of bytes accepted by the transport layer)."

        2. "The write half of the connection is closed."

        3. "A socket using a non-blocking connect() has completed the connection, or the connect() has failed."

        4. "A socket error is pending. A write operation on the socket will not block and will return an error (-1) with 'errno' set to the specific error condition."

      3. (a) "If the 'errorfds' argument ('p_desc_err') is not a null pointer, it points to an object of type 'fd_set' that on input specifies the file descriptors to be checked for error conditions pending, and on output indicates which file descriptors have error conditions pending."

        (b) "A file descriptor ... shall be considered to have an exceptional condition pending ... as noted below" :

        1. "If a socket has a pending error."

        2. "Other circumstances under which a socket may be considered to have an exceptional condition pending are protocol-specific and implementation-defined."

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 165 states "that when an error occurs on a socket, it is [also] marked as both readable and writeable by select()".

      (B)

      1. (a) "Upon successful completion, ... select() ... shall" :

        1. "modify the objects pointed to by the 'readfds' ('p_desc_rd'), 'writefds' ('p_desc_wr'), and 'errorfds' ('p_desc_err') arguments to indicate which file descriptors are ready for reading, ready for writing, or have an error condition pending, respectively," ...

        2. "and shall return the total number of ready descriptors in all the output sets."

        (b)

        1. "For each file descriptor less than nfds ('desc_nbr_max'), the corresponding bit shall be set on successful completion" :

          (A) "if it was set on input" ...

          (B) "and the associated condition is true for that file descriptor."

      2. select() can NOT absolutely guarantee that descriptors returned as ready will still be ready during subsequent operations since any higher priority tasks or processes may asynchronously consume the descriptors' operations and/or resources. This can occur since select() functionality and subsequent operations are NOT atomic operations protected by network, file system, or operating system mechanisms.

        However, as long as no higher priority tasks or processes access any of the same descriptors, then a single task or process can assume that all descriptors returned as ready by select() will still be ready during subsequent operations.

      3. (A) "The 'timeout' parameter ('p_timeout') controls how long ... select() ... shall take before timing out."

        1. (a) "If the 'timeout' parameter ('p_timeout') is not a null pointer, it specifies a maximum interval to wait for the selection to complete."

          1. "If none of the selected descriptors are ready for the requested operation, ... select() ... shall block until at least one of the requested operations becomes ready ... or ... until the timeout occurs."

          2. "If the specified time interval expires without any requested operation becoming ready, the function shall return."

          3. "To effect a poll, the 'timeout' parameter ('p_timeout') should not be a null pointer, and should point to a zero-valued timespec structure ('timeval')."

          (b)

          1. (A) "If the 'readfds' ('p_desc_rd'), 'writefds' ('p_desc_wr'), and 'errorfds' ('p_desc_err') arguments are"

            1. "all null pointers"

            2. [or all null-valued (i.e., no file descriptors set)]

            (B) "and the 'timeout' argument ('p_timeout') is not a null pointer,"

          2. ... then "select() ... shall block for the time specified".

        2. "If the 'timeout' parameter ('p_timeout') is a null pointer, then the call to ... select() shall block indefinitely until at least one descriptor meets the specified criteria."

        (B)

        1. "For the select() function, the timeout period is given ... in an argument ('p_timeout') of type struct 'timeval'" ... :

          (a) "in seconds"

          (b) "and microseconds"

        2. (a)

          1. "Implementations may place limitations on the maximum timeout interval supported" :

            (A) "All implementations shall support a maximum timeout interval of at least 31 days."

            1. However, since maximum timeout interval values are dependent on the specific OS implementation; a maximum timeout interval CANNOT be guaranteed.

            (B) "If the 'timeout' argument ('p_timeout') specifies a timeout interval greater than the implementation-defined maximum value, the maximum value shall be used as the actual timeout value."

          2. "Implementations may also place limitations on the granularity of timeout intervals" :

            (A) "If the requested 'timeout' interval requires a finer granularity than the implementation supports, the actual timeout interval shall be rounded up to the next supported value."

    (c)

    1. (A) IEEE Std 1003.1, 2004 Edition, Section 'select() : RETURN VALUE' states that :

      1. "Upon successful completion, ... select() ... shall return the total number of bits set in the bit masks."

      2. (a) "Otherwise, -1 shall be returned," ...

        (b) "and 'errno' shall be set to indicate the error." 'errno' NOT currently supported (see 'net_bsd.c Note #1b').

        (c) Stevens/Fenner/Rudoff, UNIX Network Programming, Volume 1, 3rd Edition, 6th Printing, Section 6.3, Page 161 states that BSD select() function "returns ... 0 on timeout".

      3. IEEE Std 1003.1, 2004 Edition, Section 'select() : DESCRIPTION' states that :

        (A) "On failure, the objects pointed to by the 'readfds' ('p_desc_rd'), 'writefds' ('p_desc_wr'), and 'errorfds' ('p_desc_err') arguments shall not be modified."

        (B) "If the 'timeout' interval expires without the specified condition being true for any of the specified file descriptors, the objects pointed to by the 'readfds' ('p_desc_rd'), 'writefds' ('p_desc_wr'), and 'errorfds' ('p_desc_err') arguments shall have all bits set to 0."

    (d) IEEE Std 1003.1, 2004 Edition, Section 'select() : ERRORS' states that "under the following conditions, ... select() shall fail and set 'errno' to" :

    1. "[EBADF] - One or more of the file descriptor sets specified a file descriptor that is not a valid open file descriptor."

    2. "[EINVAL]" -

      (A) "The 'nfds' argument ('desc_nbr_max') is" :

      1. "less than 0 or" ...

      2. "greater than FD_SETSIZE."

      (B) "An invalid timeout interval was specified."

      'errno' is NOT currently supported.

send()#

Description#

Sends data through a socket.

Files#

net_bsd.h/net_bsd.c

Prototype#

ssize_t  send (int      sock_id,
               void    *p_data,
              _size_t   data_len,
               int      flags)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to send data.

p_data

Pointer to application data to send.

data_len

Length of application data to send (in octets).

flags

Flags to select send options; bit-field flags logically OR'd :

  • 0 No socket flags selected.

  • MSG_DONTWAIT Send socket data without blocking.

Returned Value#

  • Number of positive data octets sent, if NO error(s).

  • 0, if socket connection closed.

  • -1, otherwise.

Notes / Warnings#

  1. (a)

    1. (A) Datagram-type sockets send and receive all data atomically -- i.e., every single, complete datagram sent MUST be received as a single, complete datagram. Thus each call to send data MUST be transmitted in a single, complete datagram.

      (B)

      1. IEEE Std 1003.1, 2004 Edition, Section 'send() : DESCRIPTION' states that "if the message is too long to pass through the underlying protocol, send() shall fail and no data shall be transmitted".

      2. Since IP transmit fragmentation is NOT currently supported (see 'net_ip.h Note #1d'), if the socket's type is datagram and the requested send data length is greater than the socket/transport layer MTU, then NO data is sent and NET_SOCK_ERR_INVALID_DATA_SIZE error is returned.

    2. (A)

      1. Stream-type sockets send and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      2. Thus if the socket's type is stream and the socket's send data queue(s) are NOT large enough for the send data, the send data queue(s) are maximally filled with send data and the remaining data octets are discarded, but may be re-sent by later application-socket sends.

      3. Therefore, NO stream-type socket send data length should be "too long to pass through the underlying protocol" and cause the socket send to "fail ... [with] no data ... transmitted".

      (B) Thus it is typical -- but NOT absolutely required -- that a single application task ONLY send or request to send data to a stream-type socket.

    (b) 'data_len' of 0 octets NOT allowed.

  2. Only some socket send flag options are implemented. If other flag options are requested, socket send handler function(s) abort and return appropriate error codes so that requested flag options are NOT silently ignored.

  3. (a) IEEE Std 1003.1, 2004 Edition, Section 'send() : RETURN VALUE' states that :

    1. "Upon successful completion, send() shall return the number of bytes sent."

      (A) Section 'send() : DESCRIPTION' elaborates that "successful completion of a call to sendto() does not guarantee delivery of the message".

      (B)

      1. Thus applications SHOULD verify the actual returned number of data octets transmitted and/or prepared for transmission.

      2. In addition, applications MAY desire verification of receipt and/or acknowledgement of transmitted data to the remote host, either inherently by the transport layer or explicitly by the application.

    2. (A) "Otherwise, -1 shall be returned."

      1. Section 'send() : DESCRIPTION' elaborates that "a return value of -1 indicates only locally-detected errors".

      (B) "and 'errno' set to indicate the error." 'errno' is NOT currently supported.

    (b) Although NO socket send() specification states to return '0' when the socket's connection is closed, it seems reasonable to return '0' since it is possible for the socket connection to be close()'d or shutdown() by the remote host.

sendto()#

Description#

Sends data through a socket.

Files#

net_bsd.h/net_bsd.c

Prototype#

ssize_t  sendto (        int         sock_id,
                         void       *p_data,
                        _size_t      data_len,
                         int         flags,
                 struct  sockaddr   *p_addr_remote,
                         socklen_t   addr_len)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to send data.

p_data

Pointer to application data to send.

data_len

Length of application data to send (in octets).

flags

Flags to select send options; bit-field flags logically OR'd :

  • 0 No socket flags selected.

  • MSG_DONTWAIT Send socket data without blocking.

p_addr_remote

Pointer to destination address buffer; required for datagram sockets, optional for stream sockets.

addr_len

Length of destination address buffer (in octets).

Returned Value#

  • Number of positive data octets sent, if NO error(s).

  • 0, if socket connection closed.

  • -1, otherwise.

Notes / Warnings#

  1. (a)

    1. (A) Datagram-type sockets send and receive all data atomically (i.e., every single, complete datagram sent MUST be received as a single, complete datagram). Each call to send data MUST be transmitted in a single, complete datagram.

      (B) Since IP transmit fragmentation is NOT currently supported, if the socket's type is datagram and the requested send data length is greater than the socket/transport layer MTU, then NO data is sent and RTOS_ERR_WOULD_OVF error is returned.

    2. (A)

      1. Stream-type sockets send and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet(s); rather, it is contiguous and sequenced from one packet to the next.

      2. Thus if the socket's type is stream and the socket's send data queue(s) are NOT large enough for the send data, the send data queue(s) are maximally filled with send data and the remaining data octets are discarded but may be re-sent by later application-socket sends.

      3. Therefore, NO stream-type socket send data length should be "too long to pass through the underlying protocol" and cause the socket send to "fail ... [with] no data ... transmitted".

      (B) It is typical, but NOT absolutely required, that a single application task ONLY send or request to send data to a stream-type socket.

    (b) 'data_len' of 0 octets NOT allowed.

  2. Only some socket send flag options are implemented. If other flag options are requested, the socket send handler function(s) abort, then return appropriate error codes so that the requested flag options are NOT silently ignored.

  3. (a) Socket address structure 'sa_family' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

    (b) Socket address structure addresses MUST be configured/converted from host-order to network-order.

  4. (a) IEEE Std 1003.1, 2004 Edition, Section 'sendto() : RETURN VALUE' states that :

    1. "Upon successful completion, sendto() shall return the number of bytes sent."

      (A) Section 'sendto() : DESCRIPTION' elaborates that "successful completion of a call to sendto() does not guarantee delivery of the message."

      (B)

      1. Thus applications SHOULD verify the actual returned number of data octets transmitted and/or prepared for transmission.

      2. In addition, applications MAY desire verification of receipt and/or acknowledgement of transmitted data to the remote host, either inherently by the transport layer or explicitly by the application.

    2. (A) "Otherwise, -1 shall be returned" ...

      1. Section 'sendto() : DESCRIPTION' elaborates that "a return value of -1 indicates only locally-detected errors".

      (B) "and 'errno' set to indicate the error." 'errno' is NOT currently supported.

    (b) Although NO socket send() specification states to return '0' when the socket's connection is closed, it seems reasonable to return '0' since it is possible for the socket connection to be close()'d or shutdown() by the remote host.

setsockopt()#

Description#

Sets the socket option.

Files#

net_bsd.h/net_bsd.c

Prototype#

int  setsockopt (int         sock_id,
                 int         protocol,
                 int         opt_name,
                 void       *p_opt_val,
                 socklen_t   opt_len)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to set the option.

protocol

Protocol level at which the option resides.

opt_name

Name of the single socket option to set.

p_opt_val

Pointer to the socket option value to set.

opt_len

Option length.

Returned Value#

  • 0, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

None.

socket()#

Description#

Creates a socket.

Files#

net_bsd.h/net_bsd.c

Prototype#

int  socket (int  protocol_family,
             int  sock_type,
             int  protocol)

Arguments#

protocol_family

Socket protocol family :

  • PF_INET Internet Protocol version 4 (IPv4).

  • PF_INET6 Internet Protocol version 6 (IPv6).

sock_type

Socket type :

  • SOCK_DGRAM Datagram-type socket.

  • SOCK_STREAM Stream -type socket.

protocol

Socket protocol :

  • 0 Default protocol for socket type.

  • IPPROTO_UDP User Datagram Protocol (UDP).

  • IPPROTO_TCP Transmission Control Protocol (TCP).

Returned Value#

  • Socket descriptor/handle identifier, if NO error(s).

  • -1, otherwise.

Notes / Warnings#

None.

Network Application Interface API#

Function Name

Description

NetApp_ClientDatagramOpen()

Open a UDP datagram using IPv4 or IPv6 address.

NetApp_ClientDatagramOpenByHostname()

Open a UDP datagram to a server using the server's hostname (select remote address using DNS)

NetApp_ClientStreamOpen()

Open and connect a TCP Stream to a server

NetApp_ClientStreamOpenByHostname()

Open and connect a TCP Stream to a server using the server's hostname (select remote address using DNS)

NetApp_SockOpen()

Open an application socket.

NetApp_SockClose()

Close an application socket.

NetApp_SockBind()

Bind an application socket to a local address.

NetApp_SockConn()

Connect an application socket to a remote address.

NetApp_SockListen()

Set an application socket to listen for connection requests.

NetApp_SockAccept()

Return a new application socket accepted from a listen application socket.

NetApp_SockRx()

Receive application data via socket.

NetApp_SockTx()

Transmit application data via socket.

NetApp_SetSockAddr()

Setup a socket address from an IPv4 or an IPv6 address.

NetApp_TimeDly_ms()

Delay for specified time, in milliseconds.

NetApp_ClientDatagramOpen()#

Description#

  1. Connects a client to a server using an IP address (IPv4 or IPv6) with a datagram socket by following these steps :

    (a) Open a datagram socket.

    (b) Set connection timeout.

Files#

net_app.h/net_app.c

Prototype#

NET_SOCK_ID  NetApp_ClientDatagramOpen (CPU_INT08U          *p_addr,
                                        NET_IP_ADDR_FAMILY   addr_family,
                                        NET_PORT_NBR         remote_port_nbr,
                                        NET_SOCK_ADDR       *p_sock_addr,
                                        RTOS_ERR            *p_err)

Arguments#

p_addr

Pointer to IP address.

addr_family

IP family of the address.

remote_port_nbr

Port of the remote host.

p_sock_addr

Pointer to a variable that receives the socket address of the remote host.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

Returned Value#

  • Socket ID, if no error(s).

  • NET_SOCK_ID_NONE, otherwise.

Notes / Warnings#

None.

NetApp_ClientDatagramOpenByHostname()#

Description#

  1. Opens a datagram type (UDP) socket to the server using its host name. (select IP address automatically, see Note #2):

    (a) Get the IP address of the remote host from a string that contains either the IP address or the host name that will be resolved using DNS (see Note #2). (b) Open a datagram socket.

Files#

net_app.h/net_app.c

Prototype#

NET_IP_ADDR_FAMILY  NetApp_ClientDatagramOpenByHostname (NET_SOCK_ID         *p_sock_id,
                                                         CPU_CHAR            *p_remote_host_name,
                                                         NET_PORT_NBR         remote_port_nbr,
                                                         NET_IP_ADDR_FAMILY   ip_family,
                                                         NET_SOCK_ADDR       *p_sock_addr,
                                                         CPU_BOOLEAN         *p_is_hostname,
                                                         RTOS_ERR            *p_err)

Arguments#

p_sock_id

Pointer to a variable that receives the socket ID opened from this function.

p_remote_host_name

Pointer to a string that contains the remote host name to resolve.

remote_port_nbr

Port of the remote host.

ip_family

Select IP family of addresses returned by DNS resolution :

  • NET_IP_ADDR_FAMILY_IPv4

  • NET_IP_ADDR_FAMILY_IPv6

p_sock_addr

Pointer to a variable that receives the socket address of the remote host.

p_is_hostname

Pointer to variable that receives the boolean to indicate if the string passed in p_remote_host_name was a hostname or a IP address.

  • DEF_YES, hostname was received.

  • DEF_NO, otherwise.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NET_ADDR_UNRESOLVED

  • RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

  • NET_IP_ADDR_FAMILY_IPv4, if the opening was successful using an IPv4 address.

  • NET_IP_ADDR_FAMILY_IPv6, if the opening was successful using an IPv6 address.

  • NET_IP_ADDR_FAMILY_UNKNOWN, otherwise.

Notes / Warnings#

  1. When a host name is passed into the remote host name parameter, this function tries to resolve the address of the remote host using DNS.

    (a) The DNS must be present and enabled in the project for the resolve to be possible.

    (b) The ip_family argument let the application choose the IP family of the addresses returned by the DNS resolution.

    (c) This function always blocks and the fail timeout depends on the DNS resolution timeout, the number of remote addresses found, and the connection timeout parameter.

NetApp_ClientStreamOpen()#

Description#

  1. Connects a client to a server using an IP address (IPv4 or IPv6) with a stream socket by following these steps :

    (a) Open a stream socket.

    (b) Set Security parameter (TLS/SSL), if required.

    (c) Set connection timeout.

    (d) Connect to the remote host.

Files#

net_app.h/net_app.c

Prototype#

NET_SOCK_ID  NetApp_ClientStreamOpen (CPU_INT08U               *p_addr,
                                      NET_IP_ADDR_FAMILY        addr_family,
                                      NET_PORT_NBR              remote_port_nbr,
                                      NET_SOCK_ADDR            *p_sock_addr,
                                      NET_APP_SOCK_SECURE_CFG  *p_secure_cfg,
                                      CPU_INT32U                req_timeout_ms,
                                      RTOS_ERR                 *p_err)

Arguments#

p_addr

Pointer to IP address.

addr_family

IP family of the address.

remote_port_nbr

Port of the remote host.

p_sock_addr

Pointer to a variable that receives the socket address of the remote host.

p_secure_cfg

Pointer to the secure configuration (TLS/SSL), if needed.

req_timeout_ms

Connection timeout in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • Socket ID, if no error(s).

  • NET_SOCK_ID_NONE, otherwise.

Notes / Warnings#

This function is in blocking mode, which means that at the end of the function, the socket will have succeeded or failed to connect to the remote host.

NetApp_ClientStreamOpenByHostname()#

Description#

  1. Connects a client to a server using its host name with a stream (TCP) socket (select IP address automatically, see Note #2) by following these steps :

    (a) Get the IP address of the remote host from a string that contains either the IP address or the host name that will be resolved using DNS (see Note #2).

    (b) Open a stream socket.

    (c) Connect a stream socket.

Files#

net_app.h/net_app.c

Prototype#

NET_IP_ADDR_FAMILY  NetApp_ClientStreamOpenByHostname (NET_SOCK_ID              *p_sock_id,
                                                       CPU_CHAR                 *p_remote_host_name,
                                                       NET_PORT_NBR              remote_port_nbr,
                                                       NET_SOCK_ADDR            *p_sock_addr,
                                                       NET_APP_SOCK_SECURE_CFG  *p_secure_cfg,
                                                       CPU_INT32U                req_timeout_ms,
                                                       RTOS_ERR                 *p_err)

Arguments#

p_sock_id

Pointer to a variable that receives the socket ID opened from this function.

p_remote_host_name

Pointer to a string that contains the remote host name to resolve.

remote_port_nbr

Port of the remote host.

p_sock_addr

Pointer to a variable that receives the socket address of the remote host.

p_secure_cfg

Pointer to the secure configuration (TLS/SSL), if needed.

req_timeout_ms

Connection timeout in ms.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_ADDR_UNRESOLVED

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • NET_IP_ADDR_FAMILY_IPv4, if connected successfully using an IPv4 address.

  • NET_IP_ADDR_FAMILY_IPv6, if connected successfully using an IPv6 address.

  • NET_IP_ADDR_FAMILY_UNKNOWN, otherwise.

Notes / Warnings#

  1. When a host name is passed to the remote host name parameter, this function tries to resolve the address of the remote host using DNS.

    (a) The DNS must be present and enabled in the project for the resolve to be possible.

    (b) If an IPv6 and an IPv4 address are found for the remote host. This function will first try to connect to the remote host using the IPv6 address. If the connection fails using IPv6, a connection retry will occur using the IPv4 address.

    (c) This function always blocks and the fail timeout depends on the DNS resolution timeout, the number of remote addresses found, and the connection timeout parameter.

  2. This function is in blocking mode, which means that at the end of the function, the socket will have succeeded or failed to connect to the remote host.

NetApp_SetSockAddr()#

Description#

Sets up a socket address from an IPv4 or an IPv6 address.

Files#

net_app.h/net_app.c

Prototype#

void  NetApp_SetSockAddr (NET_SOCK_ADDR        *p_sock_addr,
                          NET_SOCK_ADDR_FAMILY  addr_family,
                          NET_PORT_NBR          port_nbr,
                          CPU_INT08U           *p_addr,
                          NET_IP_ADDR_LEN       addr_len,
                          RTOS_ERR             *p_err)

Arguments#

p_sock_addr

Pointer to the socket address that will be configure by this function.

addr_family

IP address family to configure, possible values:

  • NET_SOCK_ADDR_FAMILY_IP_V4

  • NET_SOCK_ADDR_FAMILY_IP_V6

port_nbr

Port number.

p_addr

Pointer to IP address to use.

addr_len

Length of the IP address to use.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

NetApp_SockAccept()#

Description#

  1. Returns a new application socket accepted from a listen application socket with error handling :

    (a) Configure the accept timeout, if any

    (b) Wait for the accept socket

    (c) Restore the accept timeout, if necessary

Files#

net_app.h/net_app.c

Prototype#

NET_SOCK_ID  NetApp_SockAccept (NET_SOCK_ID         sock_id,
                                NET_SOCK_ADDR      *p_addr_remote,
                                NET_SOCK_ADDR_LEN  *p_addr_len,
                                CPU_INT16U          retry_max,
                                CPU_INT32U          timeout_ms,
                                CPU_INT32U          time_dly_ms,
                                RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of listen socket.

p_addr_remote

Pointer to an address buffer that receives the socket address structure.

p_addr_len

Pointer to a variable to pass the size of the socket address structure and that will receive the size of the accepted connection’s socket address structure, if no errors. Otherwise, a 0 size will be returned.

retry_max

Maximum number of consecutive socket accept retries.

timeout_ms

Socket accept timeout value per attempt/retry.

time_dly_ms

Transitory socket accept delay value (in milliseconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function::

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Socket descriptor/handle identifier of new accepted socket, if NO error(s).

  • NET_SOCK_BSD_ERR_ACCEPT, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'rtos_cfg.h').

  2. Socket accept operation valid for stream-type sockets only.

  3. (a) Socket address structure 'AddrFamily' member returned in host-order and SHOULD NOT be converted to network-order.

    (b) Socket address structure addresses returned in network-order and SHOULD be converted from network-order to host-order.

  4. If a non-zero number of retries is requested and the global socket blocking ('NET_SOCK_CFG_BLOCK_SEL') is configured for non-blocking operation ('NET_SOCK_BLOCK_SEL_NO_BLOCK'), then one or more of the following SHOULD also be requested. Otherwise, all retries will likely fail immediately since no time will elapse to wait for and allow socket operation(s) to successfully complete :

    (a) One or more of the following SHOULD also be requested. Otherwise, all retries will likely fail immediately since no time will have elapsed to allow socket operation(s) to successfully complete :

    1. A non-zero timeout

    2. A non-zero time delay(s).

NetApp_SockBind()#

Description#

Binds an application socket to a local address with error handling.

Files#

net_app.h/net_app.c

Prototype#

CPU_BOOLEAN  NetApp_SockBind (NET_SOCK_ID         sock_id,
                              NET_SOCK_ADDR      *p_addr_local,
                              NET_SOCK_ADDR_LEN   addr_len,
                              CPU_INT16U          retry_max,
                              CPU_INT32U          time_dly_ms,
                              RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of the application to which to bind the socket.

p_addr_local

Pointer to socket address structure.

addr_len

Length of socket address structure (in octets).

retry_max

Maximum number of consecutive socket bind retries).

time_dly_ms

Transitory socket bind delay value, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • DEF_OK, application socket is successfully bound to a local address.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments are validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'rtos_cfg.h').

  2. (a) Socket address structure 'AddrFamily' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

    (b) Socket address structure addresses MUST be configured/converted from host-order to network-order.

  3. If a non-zero number of retries is requested, a non-zero time delay SHOULD also be requested. Otherwise, all retries will most likely fail immediately since no time will have elapsed to allow socket operation(s) to successfully complete.

NetApp_SockClose()#

Description#

  1. Closes an application socket, with error handling :

    (a) Configure close timeout, if any

    (b) Close application socket

Files#

net_app.h/net_app.c

Prototype#

CPU_BOOLEAN  NetApp_SockClose (NET_SOCK_ID   sock_id,
                               CPU_INT32U    timeout_ms,
                               RTOS_ERR     *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of application socket to close.

timeout_ms

Socket close timeout value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_RETRY_MAX

  • RTOS_ERR_NET_SOCK_CLOSED

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

Returned Value#

  • DEF_OK, application socket successfully closed.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments are validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'net_cfg.h').

  2. (a) Once an application closes its socket, NO further operations on the socket are allowed and the application MUST NOT continue to access the socket.

    (b) NO error is returned for any internal error while closing the socket.

NetApp_SockConn()#

Description#

  1. Connects an application socket to a remote address with error handling :

    (a) Configure connect timeout, if any

    (b) Connect application socket to remote address

    (c) Restore connect timeout, if necessary

Files#

net_app.h/net_app.c

Prototype#

CPU_BOOLEAN  NetApp_SockConn (NET_SOCK_ID         sock_id,
                              NET_SOCK_ADDR      *p_addr_remote,
                              NET_SOCK_ADDR_LEN   addr_len,
                              CPU_INT16U          retry_max,
                              CPU_INT32U          timeout_ms,
                              CPU_INT32U          time_dly_ms,
                              RTOS_ERR           *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of application socket to which to connect.

p_addr_remote

Pointer to socket address structure.

addr_len

Length of socket address structure (in octets).

retry_max

Maximum number of consecutive socket connect retries.

timeout_ms

Socket connect timeout value per attempt/retry.

time_dly_ms

Transitory socket connect delay value (in milliseconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • DEF_OK, application socket has successfully connected to a remote address.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments are validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'rtos_cfg.h').

  2. (a) Socket address structure 'AddrFamily' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

    (b) Socket address structure addresses MUST be configured/converted from host-order to network-order.

  3. (a)

    1. If a non-zero number of retries is requested AND ...

    2. global socket blocking ('NET_SOCK_CFG_BLOCK_SEL') is configured ... for non-blocking operation ('NET_SOCK_BLOCK_SEL_NO_BLOCK'); ...

    (b) ... one or more of the following SHOULD also be requested. Otherwise, all retries will most likely fail immediately since no time will have elapsed to allow socket operation(s) to successfully complete :

    1. A non-zero timeout

    2. A non-zero time delay

NetApp_SockListen()#

Description#

Sets an application socket to listen for connection requests with error handling.

Files#

net_app.h/net_app.c

Prototype#

CPU_BOOLEAN  NetApp_SockListen (NET_SOCK_ID       sock_id,
                                NET_SOCK_Q_SIZE   sock_q_size,
                                RTOS_ERR         *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to listen.

sock_q_size

Maximum number of connection requests to accept and queue on listen socket.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • DEF_OK, application socket is successfully set to listen.

  • DEF_FAIL, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments are validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'net_cfg.h').

  2. Socket listen operation is only valid for stream-type sockets.

NetApp_SockOpen()#

Description#

Opens an application socket, with error handling.

Files#

net_app.h/net_app.c

Prototype#

NET_SOCK_ID  NetApp_SockOpen (NET_SOCK_PROTOCOL_FAMILY   protocol_family,
                              NET_SOCK_TYPE              sock_type,
                              NET_SOCK_PROTOCOL          protocol,
                              CPU_INT16U                 retry_max,
                              CPU_INT32U                 time_dly_ms,
                              RTOS_ERR                  *p_err)

Arguments#

protocol_family

Socket protocol family :

  • NET_SOCK_PROTOCOL_FAMILY_IP_V4

  • NET_SOCK_PROTOCOL_FAMILY_IP_V6

sock_type

Socket type :

  • NET_SOCK_TYPE_DATAGRAM

  • NET_SOCK_TYPE_STREAM

protocol

Socket protocol :

  • NET_SOCK_PROTOCOL_TCP

  • NET_SOCK_PROTOCOL_UDP

retry_max

Maximum number of consecutive socket open retries.

time_dly_ms

Transitory socket open delay value (in milliseconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_POOL_EMPTY

Returned Value#

  • Socket descriptor/handle identifier, if NO error(s).

  • NET_SOCK_BSD_ERR_OPEN, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'rtos_cfg.h').

  2. If a non-zero number of retries is requested, a non-zero time delay SHOULD also be requested. Otherwise, all retries will most likely fail immediately since no time will have elapsed to allow socket operation(s) to successfully complete.

NetApp_SockRx()#

Description#

  1. Receive application data via socket, with error handling :

    (a) Validate receive arguments

    (b) Configure receive timeout, if any

    (c) Receive application data via socket

    (d) Restore receive timeout, if necessary

Files#

net_app.h/net_app.c

Prototype#

CPU_INT16U  NetApp_SockRx (NET_SOCK_ID          sock_id,
                           void                *p_data_buf,
                           CPU_INT16U           data_buf_len,
                           CPU_INT16U           data_rx_th,
                           NET_SOCK_API_FLAGS   flags,
                           NET_SOCK_ADDR       *p_addr_remote,
                           NET_SOCK_ADDR_LEN   *p_addr_len,
                           CPU_INT16U           retry_max,
                           CPU_INT32U           timeout_ms,
                           CPU_INT32U           time_dly_ms,
                           RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to receive application data.

p_data_buf

Pointer to an application data buffer that will receive application data.

data_buf_len

Size of the application data buffer (in octets).

data_rx_th

Application data receive threshold :

  • 0, NO minimum receive threshold; i.e., receive ANY amount of data. Recommended for datagram sockets.

  • Minimum amount of application data to receive (in octets) within maximum number of retries, otherwise.

flags

Flags to select receive options; bit-field flags logically OR'd :

  • NET_SOCK_FLAG_NONE

  • NET_SOCK_FLAG_RX_DATA_PEEK

  • NET_SOCK_FLAG_RX_NO_BLOCK

p_addr_remote

Pointer to an address buffer that receives the socket address structure.

p_addr_len

Pointer to a variable to pass the size of the socket address structure and that will receive the size of the accepted connection’s socket address structure, if no errors. Otherwise, a 0 size will be returned.

retry_max

Maximum number of consecutive socket receive retries.

timeout_ms

Socket receive timeout value per attempt/retry.

time_dly_ms

Transitory socket receive delay value, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_NET_CONN_CLOSE_RX

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of positive data octets received, if NO error(s).

  • 0, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments are validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'rtos_cfg.h').

  2. (a) Socket address structure 'AddrFamily' member returned in host-order and SHOULD NOT be converted to network-order.

    (b) Socket address structure addresses returned in network-order and SHOULD be converted from network-order to host-order.

  3. (a)

    1. (A) Datagram-type sockets transmit and receive all data atomically -- i.e., every single, complete datagram transmitted MUST be received as a single, complete datagram.

      (B) IEEE Std 1003.1, 2004 Edition, Section 'recvfrom() : DESCRIPTION' summarizes that "for message-based sockets, such as ... SOCK_DGRAM ... the entire message shall be read in a single operation. If a message is too long to fit in the supplied buffer, and MSG_PEEK is not set in the flags argument, the excess bytes shall be discarded."

    2. If the socket's type is datagram and the receive data buffer size is NOT large enough for the received data, the receive data buffer is maximally filled with receive data but the remaining data octets are discarded and RTOS_ERR_WOULD_OVF error is returned.

    (b)

    1. (A) Stream-type sockets transmit and receive all data octets in one or more non-distinct packets. In other words, the application data is NOT bounded by any specific packet

      (s); rather, it is contiguous and sequenced from one packet to the next.

      (B) IEEE Std 1003.1, 2004 Edition, Section 'recv() : DESCRIPTION' summarizes that "for stream-based sockets, such as SOCK_STREAM, message boundaries shall be ignored. In this case, data shall be returned to the user as soon as it becomes available, and no data shall be discarded."

    2. If the socket's type is stream and the receive data buffer size is NOT large enough for the received data, the receive data buffer is filled with received data and the remaining data octets remain queued for subsequent application reception.

  4. (a)

    1. If a non-zero number of retries is requested and one of the following conditions:

    2. (A) global socket blocking ('NET_SOCK_CFG_BLOCK_SEL') is configured for non-blocking operation ('NET_SOCK_BLOCK_SEL_NO_BLOCK'), OR

      (B) socket 'flags' argument set to 'NET_SOCK_FLAG_RX_BLOCK'.

    (b) One or more of the following SHOULD also be requested. Otherwise, all retries will most likely fail immediately since no time will have elapsed to allow the socket operation(s) to successfully complete :

    1. A non-zero timeout

    2. A non-zero time delay(s).

NetApp_SockTx()#

Description#

  1. Transmits application data via socket with error handling :

    (a) Configure transmit timeout, if any

    (b) Transmit application data via socket

    (c) Restore transmit timeout, if necessary

Files#

net_app.h/net_app.c

Prototype#

CPU_INT16U  NetApp_SockTx (NET_SOCK_ID          sock_id,
                           void                *p_data,
                           CPU_INT16U           data_len,
                           NET_SOCK_API_FLAGS   flags,
                           NET_SOCK_ADDR       *p_addr_remote,
                           NET_SOCK_ADDR_LEN    addr_len,
                           CPU_INT16U           retry_max,
                           CPU_INT32U           timeout_ms,
                           CPU_INT32U           time_dly_ms,
                           RTOS_ERR            *p_err)

Arguments#

sock_id

Socket descriptor/handle identifier of socket to transmit application data.

p_data

Pointer to application data to transmit.

data_len

Length of application data to transmit (in octets).

flags

Flags to select transmit options; bit-field flags logically OR'd :

  • NET_SOCK_FLAG_NONE

  • NET_SOCK_FLAG_TX_NO_BLOCK

p_addr_remote

Pointer to destination address buffer.

addr_len

Length of destination address buffer (in octets).

retry_max

Maximum number of consecutive socket transmit retries.

timeout_ms

Socket transmit timeout value per attempt/retry.

time_dly_ms

Transitory socket transmit delay value (in milliseconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_RETRY_MAX

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

  • Number of positive data octets transmitted, if NO error(s).

  • 0, otherwise.

Notes / Warnings#

  1. Socket arguments and/or operations are validated in network socket handler functions. Some arguments are validated only if the validation code is enabled (i.e., RTOS_ARG_CHK_EXT_EN is DEF_ENABLED in 'rtos_cfg.h').

  2. (a) Socket address structure 'AddrFamily' member MUST be configured in host-order and MUST NOT be converted to/from network-order.

    (b) Socket address structure addresses MUST be configured/converted from host-order to network-order.

  3. If a non-zero number of retries is requested and the global socket blocking ('NET_SOCK_CFG_BLOCK_SEL') is configured for non-blocking operation ('NET_SOCK_BLOCK_SEL_NO_BLOCK'), then one or more of the following SHOULD also be requested. Otherwise, all retries will most likely fail immediately since no time will elapse to wait for & allow socket operation(s) to successfully complete :

    (a) A non-zero timeout

    (b) A non-zero time delay

  4. Datagram sockets NOT currently blocked during transmit and therefore require NO transmit timeout.

NetApp_TimeDly_ms()#

Description#

Delays for a specified time (in milliseconds).

Files#

net_app.h/net_app.c

Prototype#

void  NetApp_TimeDly_ms (CPU_INT32U   time_dly_ms,
                         RTOS_ERR    *p_err)

Arguments#

time_dly_ms

Time delay value (in milliseconds