1. WIZnet socket APIs

WIZnet socket APIs are based on Berkeley socket APIs, thus it has much similar name and interface. But there is a little bit of difference. More...

Functions
int8_t	socket (uint8_t sn, uint8_t protocol, uint16_t port, uint8_t flag)
	Open a socket. More...
int8_t	close (uint8_t sn)
	Close a SOCKET. More...
int8_t	listen (uint8_t sn)
	Listen to a connection request from a TCP CLIENT. More...
int8_t	connect (uint8_t sn, uint8_t *addr, uint16_t port, uint8_t addrlen)
	Try to connect to a TCP SERVER. More...
int8_t	disconnect (uint8_t sn)
	Try to disconnect to the connected peer. More...
datasize_t	send (uint8_t sn, uint8_t *buf, datasize_t len)
	Send data to the connected peer. More...
datasize_t	recv (uint8_t sn, uint8_t *buf, datasize_t len)
	Receive data from the connected peer. More...
datasize_t	sendto (uint8_t sn, uint8_t *buf, datasize_t len, uint8_t *addr, uint16_t port, uint8_t addrlen)
	Send datagram to the peer specifed by destination IP address and port number passed as parameter. More...
datasize_t	recvfrom (uint8_t sn, uint8_t *buf, datasize_t len, uint8_t *addr, uint16_t *port, uint8_t *addrlen)
	Receive datagram from a peer. More...
int8_t	ctlsocket (uint8_t sn, ctlsock_type cstype, void *arg)
	Control SOCKETn. More...
int8_t	setsockopt (uint8_t sn, sockopt_type sotype, void *arg)
	Set SOCKETn options. More...
int8_t	getsockopt (uint8_t sn, sockopt_type sotype, void *arg)
	get SOCKETn options More...
int16_t	peeksockmsg (uint8_t sn, uint8_t *submsg, uint16_t subsize)
	Peeks a sub-message in SOCKETn RX buffer. More...

Detailed Description

WIZnet socket APIs are based on Berkeley socket APIs, thus it has much similar name and interface. But there is a little bit of difference.

Comparison between WIZnet and Berkeley SOCKET APIs

API	WIZnet	Berkeley
socket()	O	O
bind()	X	O
listen()	O	O
connect()	O	O
accept()	X	O
recv()	O	O
send()	O	O
recvfrom()	O	O
sendto()	O	O
closesocket()	O close() & disconnect()	O

There are bind() and accept() functions in Berkeley SOCKET API but, not in WIZnet SOCKET API.
Because socket() of WIZnet is not only creating a SOCKET but also binding a local port number,
and listen() of WIZnet is not only listening to connection request from client but also accepting the connection request.
When you program "TCP SERVER" with Berkeley SOCKET API, you can use only one listen port.
When the listen SOCKET accepts a connection request from a client, it keeps listening.
After accepting the connection request, a new SOCKET is created and the new SOCKET is used in communication with the client.
Following figure shows network flow diagram by Berkeley SOCKET API.

<Berkeley SOCKET API>

But, When you program "TCP SERVER" with WIZnet SOCKET API, you can use as many as 8 listen SOCKET with same port number.
Because there's no accept() in WIZnet SOCKET APIs, when the listen SOCKET accepts a connection request from a client,
it is changed in order to communicate with the client.
And the changed SOCKET is not listening any more and is dedicated for communicating with the client.
If there're many listen SOCKET with same listen port number and a client requests a connection,
the SOCKET which has the smallest SOCKET number accepts the request and is changed as communication SOCKET.
Following figure shows network flow diagram by WIZnet SOCKET API.

<WIZnet SOCKET API>

Function Documentation

socket()

int8_t socket	(	uint8_t	sn,
		uint8_t	protocol,
		uint16_t	port,
		uint8_t	flag
	)

Open a socket.

Initializes the SOCKET have the sn number open it.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.
protocol	Protocol type to operate such as TCP, UDP IPRAW, and MACRAW. TCP : Sn_MR_TCP(= Sn_MR_TCP4), Sn_MR_TCP6, and Sn_MR_TCPD UDP : Sn_MR_UDP(= Sn_MR_UDP4), Sn_MR_UDP6, and Sn_MR_UDPD IPRAW : Sn_MR_IPRAW(= Sn_MR_IPRAW4) and Sn_MR_IPRAW6 MACRAW : Sn_MR_MACRAW
port	Source port number to be binded.
flag	SOCKET flags are as following. It is used together with OR operation. SF_MULTI_ENABLE SF_ETHER_OWN SF_BROAD_BLOCK SF_TCP_FPSH SF_TCP_NODELAY SF_IGMP_VER2 SF_SOLICIT_BLOCK SF_ETHER_MULTI4B SF_UNI_BLOCK SF_ETHER_MULIT6B SF_DHA_MANUAL SF_FORCE_ARP SF_IO_NONBLOCK

Returns

Success : The SOCKET number sn passed as parameter
Fail :
SOCKERR_SOCKNUM - Invalid SOCKETn, sn
SOCKERR_SOCKMODE - Invalid SOCKETn mode
SOCKERR_SOCKFLAG - Invaild SOCKETn flag.

See also

_Sn_MR_, _Sn_MR2_

Definition at line 101 of file socket.c.

References CHECK_IPZERO, CHECK_SOCKNUM, close(), getLLAR, getSIPR, setSn_MR, setSn_MR2, SF_DHA_MANUAL, SF_FORCE_ARP, SF_MULTI_ENABLE, SF_UNI_BLOCK, Sn_MR_IPRAW4, Sn_MR_IPRAW6, Sn_MR_MACRAW, Sn_MR_TCP4, Sn_MR_TCP6, Sn_MR_TCPD, Sn_MR_UDP, Sn_MR_UDP6, Sn_MR_UDPD, SOCKERR_SOCKFLAG, and SOCKERR_SOCKMODE.

Referenced by DHCP_run(), DHCP_run2(), DHCPv4_run(), loopback_tcpc(), loopback_tcps(), and loopback_udps().

close()

int8_t close

(

uint8_t

sn

)

Close a SOCKET.

It closes the SOCKET with 'sn' passed as parameter.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.

Returns

Success : SOCK_OK
Fail : SOCKERR_SOCKNUM - Invalid SOCKET number

Definition at line 186 of file socket.c.

References CHECK_SOCKNUM, getSn_CR, setSn_CR, setSn_IRCLR, and Sn_CR_CLOSE.

Referenced by DHCP_stop(), DHCPv4_stop(), listen(), loopback_tcpc(), loopback_tcps(), recv(), send(), and socket().

listen()

int8_t listen

(

uint8_t

sn

)

Listen to a connection request from a TCP CLIENT.

It is listening to a connection request from a client. If connection request is accepted successfully, the connection is established.
SOCKET sn is used as passive(TCP SERVER) mode.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.

Returns

Success : SOCK_OK
Fail :
SOCKERR_SOCKINIT - Socket is not initialized
SOCKERR_SOCKCLOSED - Socket closed unexpectedly.

Definition at line 204 of file socket.c.

References CHECK_SOCKINIT, CHECK_SOCKNUM, close(), getSn_CR, getSn_SR, setSn_CR, Sn_CR_LISTEN, SOCK_LISTEN, SOCK_OK, and SOCKERR_SOCKCLOSED.

Referenced by loopback_tcps().

connect()

int8_t connect	(	uint8_t	sn,
		uint8_t *	addr,
		uint16_t	port,
		uint8_t	addrlen
	)

Try to connect to a TCP SERVER.

It sends a connection-reqeust message to the server with destination IP address and port number passed as parameter.
SOCKET sn is used as active(TCP CLIENT) mode.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.
addr	Pointer variable of destination IPv6 or IPv4 address.
port	Destination port number.
addrlen	the length of addr. If addr is IPv6 address it should be 16,else if addr is IPv4 address it should be 4. Otherwize, return SOCKERR_IPINVALID.

Returns

Success : SOCK_OK
Fail :
SOCKERR_SOCKNUM - Invalid socket number
SOCKERR_SOCKMODE - Invalid socket mode
SOCKERR_SOCKINIT - Socket is not initialized
SOCKERR_IPINVALID - Wrong server IP address
SOCKERR_PORTZERO - Server port zero
SOCKERR_TIMEOUT - Timeout occurred during request connection
SOCK_BUSY - In non-block io mode, it returns immediately

Note

It is valid only in TCP client mode.
In block io mode, it does not return until connection is completed.
In Non-block io mode(SF_IO_NONBLOCK), it returns SOCK_BUSY immediately.

Definition at line 219 of file socket.c.

References CHECK_IPZERO, CHECK_SOCKINIT, CHECK_SOCKNUM, CHECK_TCPMODE, getSn_CR, getSn_MR, setSn_CR, setSn_DIP6R, setSn_DIPR, setSn_DPORTR, Sn_CR_CONNECT, Sn_CR_CONNECT6, Sn_MR_TCP6, SOCKERR_PORTZERO, and SOCKERR_SOCKMODE.

Referenced by loopback_tcpc().

disconnect()

int8_t disconnect

(

uint8_t

sn

)

Try to disconnect to the connected peer.

It sends disconnect-request message to the connected peer which is TCP SERVER or TCP CLIENT.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.

Returns

Success : SOCK_OK
Fail :
SOCKERR_SOCKNUM - Invalid SOCKET number
SOCKERR_SOCKMODE - Invalid operation in the SOCKET
SOCKERR_TIMEOUT - Timeout occurred
SOCK_BUSY - In non-block io mode, it returns immediately.

Note

It is valid only in TCP mode such as Sn_MR_TCP4, Sn_MR_TCP6, and Sn_MR_TCPD.
In block io mode, it does not return until disconnection is completed.
In Non-block io mode(SF_IO_NONBLOCK), it returns SOCK_BUSY immediately.

Definition at line 266 of file socket.c.

References CHECK_SOCKNUM, CHECK_TCPMODE, getSn_CR, getSn_SR, setSn_CR, Sn_CR_DISCON, and SOCK_CLOSED.

Referenced by loopback_tcpc(), and loopback_tcps().

send()

datasize_t send	(	uint8_t	sn,
		uint8_t *	buf,
		datasize_t	len
	)

Send data to the connected peer.

It sends data to the connected peer by using TCP mode SOCKET sn.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.
buf	Pointer of data buffer to be sent.
len	The byte length of data in buf.

Returns

Success : The real sent data size. It may be equal to len or small.
Fail :
SOCKERR_SOCKSTATUS - Invalid SOCKET status for SOCKET operation
SOCKERR_TIMEOUT - Timeout occurred
SOCKERR_SOCKMODE - Invalid operation in the SOCKET
SOCKERR_SOCKNUM - Invalid SOCKET number
SOCK_BUSY - SOCKET is busy.

Note

It is valid only in TCP mode such as Sn_MR_TCP4, Sn_MR_TCP6, and Sn_MR_TCPD.
It can send data as many as SOCKET TX buffer size if data is greater than SOCKET TX buffer size.
In block io mode, It doesn't return until data sending is completed when SOCKET transmittable buffer size is greater than data.
In non-block io mode(SF_IO_NONBLOCK), It return SOCK_BUSY immediately when SOCKET transmittable buffer size is not enough or the previous sent data is not completed.

Definition at line 289 of file socket.c.

References close(), getSn_SR, getSn_TX_FSR(), getSn_TxMAX, SOCK_CLOSE_WAIT, SOCK_CLOSED, SOCK_ESTABLISHED, and SOCKERR_SOCKSTATUS.

Referenced by loopback_tcpc(), and loopback_tcps().

recv()

datasize_t recv	(	uint8_t	sn,
		uint8_t *	buf,
		datasize_t	len
	)

Receive data from the connected peer.

It can read data received from the connected peer by using TCP mode SOCKET sn.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.
buf	Pointer buffer to read the received data.
len	The max data length of data in buf.

Returns

Success : The real received data size. It may be equal to len or small.
Fail :
SOCKERR_SOCKSTATUS - Invalid SOCKET status for SOCKET operation
SOCKERR_SOCKMODE - Invalid operation in the SOCKET
SOCKERR_SOCKNUM - Invalid SOCKET number
SOCK_BUSY - SOCKET is busy.

Note

It is valid only in TCP SERVER or TCP CLIENT mode.
It can read data as many as SOCKET RX buffer size if data is greater than SOCKET RX buffer size.
In block io mode, it doesn't return until data reception is completed. that is, it waits until any data is received in SOCKET RX buffer.
In non-block io mode(SF_IO_NONBLOCK), it return SOCK_BUSY immediately when SOCKET RX buffer is empty.

Definition at line 338 of file socket.c.

References close(), getSn_RX_RSR(), getSn_RxMAX, getSn_SR, SOCK_CLOSE_WAIT, SOCK_CLOSED, SOCK_ESTABLISHED, and SOCKERR_SOCKSTATUS.

Referenced by loopback_tcpc(), and loopback_tcps().

sendto()

datasize_t sendto	(	uint8_t	sn,
		uint8_t *	buf,
		datasize_t	len,
		uint8_t *	addr,
		uint16_t	port,
		uint8_t	addrlen
	)

Send datagram to the peer specifed by destination IP address and port number passed as parameter.

It sends datagram data by using UDP,IPRAW, or MACRAW mode SOCKET.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.
buf	Pointer of data buffer to be sent.
len	The byte length of data in buf.
addr	Pointer variable of destination IPv6 or IPv4 address.
port	Destination port number.
addrlen	the length of addr. If addr is IPv6 address it should be 16,else if addr is IPv4 address it should be 4. Otherwize, return SOCKERR_IPINVALID.

Returns

Success : The real sent data size. It may be equal to len or small.
Fail :
SOCKERR_SOCKNUM - Invalid SOCKET number
SOCKERR_SOCKMODE - Invalid operation in the SOCKET
SOCKERR_SOCKSTATUS - Invalid SOCKET status for SOCKET operation
SOCKERR_IPINVALID - Invalid IP address
SOCKERR_PORTZERO - Destination port number is zero
SOCKERR_DATALEN - Invalid data length
SOCKERR_SOCKCLOSED - SOCKET unexpectedly closed
SOCKERR_TIMEOUT - Timeout occurred
SOCK_BUSY - SOCKET is busy.

Note

It is valid only in Sn_MR_UDP4, Sn_MR_UDP6, Sn_MR_UDPD, Sn_MR_IPRAW4, Sn_MR_IPRAW6, and Sn_MR_MACRAW.
In UDP mode, It can send data as many as SOCKET RX buffer size if data is greater than SOCKET TX buffer size.
In IPRAW and MACRAW mode, It should send data as many as MTU(maxium transmission unit) if data is greater than MTU. That is, len can't exceed to MTU. In block io mode, It doesn't return until data send is completed. In non-block io mode(SF_IO_NONBLOCK), It return SOCK_BUSY immediately when SOCKET transimttable buffer size is not enough.

Definition at line 372 of file socket.c.

References getSn_MR, getSn_SR, getSn_TX_FSR(), getSn_TxMAX, setSn_DIP6R, setSn_DIPR, setSn_DPORTR, Sn_CR_SEND, Sn_CR_SEND6, Sn_MR_IPRAW6, Sn_MR_MACRAW, Sn_MR_UDP6, SOCK_CLOSED, SOCKERR_IPINVALID, SOCKERR_PORTZERO, SOCKERR_SOCKCLOSED, and SOCKERR_SOCKMODE.

Referenced by check_DHCPv4_leasedIP(), loopback_udps(), send_DHCP_INFOREQ(), send_DHCP_REQUEST(), send_DHCP_SOLICIT(), send_DHCPv4_DECLINE(), send_DHCPv4_DISCOVER(), and send_DHCPv4_REQUEST().

recvfrom()

datasize_t recvfrom	(	uint8_t	sn,
		uint8_t *	buf,
		datasize_t	len,
		uint8_t *	addr,
		uint16_t *	port,
		uint8_t *	addrlen
	)

Receive datagram from a peer.

It can read a data received from a peer by using UDP, IPRAW, or MACRAW mode SOCKET.

Parameters

sn	SOCKET number. It should be 0 ~ _WIZCHIP_SOCK_NUM_.
buf	Pointer buffer to be saved the received data.
len	The max read data length. When the received packet size <= len, it can read data as many as the packet size. When others, it can read data as many as len and remain to the rest data of the packet.
addr	Pointer variable of destination IP address. It is valid only when recvfrom() is first called for receiving the datagram packet. You can check it valid or not through PACK_FIRST. You can get it through getsockopt(sn, SO_PACKINFO, &packinfo). In UDP4, IPRAW mode SOCKET, it should be allocated over 4bytes. In UDP6, UDPD mode SOCKET, it should be allocated over 16bytes.
port	Pointer variable of destination port number. It is valid only when recvfrom() is first called for receiving the datagram packet, same as port case.
addrlen	The byte length of destination IP address. It is valid only when recvfrom() is first called for receiving the datagram packet, same as port case. When the destination has a IPv4 address, it is set to 4. when the destination has a IPv6 address, it is set to 16.

Returns

Success : The real received data size. It may be equal to len or small.
Fail : SOCKERR_SOCKMODE - Invalid operation in the socket
SOCKERR_SOCKNUM - Invalid socket number
SOCKERR_ARG - Invalid parameter such as addr, port SOCK_BUSY - SOCKET is busy.

Note

It is valid only in Sn_MR_UDP4, Sn_MR_UDP6, Sn_MR_UDPD, Sn_MR_IPRAW4, Sn_MR_IPRAW6, and Sn_MR_MACRAW.
When SOCKET is opened with Sn_MR_MACRAW or When it reads the the remained data of the previous datagram packet, the parameters such as addr, port, addrlen is ignored.
Also, It can read data as many as the received datagram packet size if len is greater than the datagram packet size.
In block io mode, it doesn't return until data reception is completed. that is, it waits until any datagram packet is received in SOCKET RX buffer.
In non-block io mode(SF_IO_NONBLOCK), it return SOCK_BUSY immediately when SOCKET RX buffer is empty.

Definition at line 441 of file socket.c.

Referenced by loopback_udps(), parseDHCPMSG(), and parseDHCPv4MSG().

ctlsocket()

int8_t ctlsocket	(	uint8_t	sn,
		ctlsock_type	cstype,
		void *	arg
	)

Control SOCKETn.

Control IO mode, Interrupt & Mask of SOCKETn and get the SOCKETn buffer information. Refer to ctlsock_type.

Parameters

sn	socket number
cstype	type of control SOCKETn. refer to ctlsock_type.
arg	Data type and value is determined according to ctlsock_type. cstype arg type value CS_SET_IOMODE CS_GET_IOMODE uint8_t SOCK_IO_BLOCK, SOCK_IO_NONBLOCK CS_GET_MAXTXBUF CS_GET_MAXRXBUF datasize_t 0,1,2,4,8,16 KB CS_CLR_INTERRUPT CS_GET_INTERRUPT CS_SET_INTMASK CS_GET_INTMASK sockint_kind SIK_CONNECTED, etc. CS_SET_PREFER CS_GET_PREFER uint8_t SRCV6_PREFER_AUTO, SRCV6_PREFER_LLA, SRCV6_PREFER_GUA < /tr>

Returns

Success SOCK_OK
Fail :

• SOCKERR_ARG - Invalid argument
  
• SOCKERR_SOCKNUM - Invalid Socket number
  

Definition at line 528 of file socket.c.

References CHECK_SOCKNUM, CS_SET_IOMODE, and SOCK_IO_NONBLOCK.

Referenced by loopback_tcpc(), and loopback_tcps().

setsockopt()

int8_t setsockopt	(	uint8_t	sn,
		sockopt_type	sotype,
		void *	arg
	)

Set SOCKETn options.

Set SOCKETn option like as TTL, MSS, TOS, and so on. Refer to sockopt_type.

Parameters

sn	SOCKET number
sotype	SOCKET option type. refer to sockopt_type
arg	Data type and value is determined according to sotype. sotype >arg type value SO_TTL uint8_t 0 ~ 255 SO_TOS uint8_t 0 ~ 255 SO_MSS uint16_t 0 ~ 65535 SO_DESTIP wiz_IPAddress SO_DESTPORT uint16_t 1 ~ 65535 SO_KEEPALIVESEND null null SO_KEEPALIVEAUTO uint8_t 0 ~ 255

Returns

• Success : SOCK_OK
  
• Fail
  • SOCKERR_SOCKNUM - Invalid SOCKET number
    
  • SOCKERR_SOCKMODE - Invalid SOCKET mode
    
  • SOCKERR_SOCKOPT - Invalid SOCKET option or its value
    
  • SOCKERR_TIMEOUT - Timeout occurred when sending keep-alive packet

Definition at line 576 of file socket.c.

References CHECK_SOCKNUM, CHECK_TCPMODE, getSn_CR, getSn_IR, getSn_KPALVTR, setSn_CR, setSn_DIP6R, setSn_DIPR, setSn_DPORTR, setSn_IRCLR, setSn_KPALVTR, setSn_MSSR, setSn_TOSR, setSn_TTLR, Sn_CR_SEND_KEEP, Sn_IR_TIMEOUT, SO_DESTIP, SO_DESTPORT, SO_KEEPALIVEAUTO, SO_KEEPALIVESEND, SO_MSS, SO_TOS, SO_TTL, SOCK_OK, SOCKERR_ARG, SOCKERR_SOCKOPT, and SOCKERR_TIMEOUT.

getsockopt()

int8_t getsockopt	(	uint8_t	sn,
		sockopt_type	sotype,
		void *	arg
	)

get SOCKETn options

Get SOCKETn option like as FLAG, TTL, MSS, and so on. Refer to sockopt_type

Parameters

sn	SOCKET number
sotype	SOCKET option type. refer to sockopt_type
arg	Data type and value is determined according to sotype. sotype arg type value SO_FLAG uint8_t SF_ETHER_OWN, etc... SO_TOS uint8_t 0 ~ 255 SO_MSS uint16_t 0 ~ 65535 SO_DESTIP wiz_IPAddress SO_DESTPORT uint16_t 1 ~ 65535 SO_KEEPALIVEAUTO uint8_t 0 ~ 255 SO_SENDBUF datasize_t 0 ~ SO_RECVBUF datasize_t 0 ~ SO_STATUS uint8_t SOCK_ESTABLISHED, etc. SO_EXTSTATUS uint8_t TCPSOCK_MODE, TCPSOCK_OP, TCPSOCK_SIP SO_REMAINSIZE datasize_t 0~ SO_PACKINFO uint8_t PACK_FIRST, etc.

Returns

• Success : SOCK_OK
  
• Fail
  • SOCKERR_SOCKNUM - Invalid Socket number
    
  • SOCKERR_SOCKOPT - Invalid socket option or its value
    
  • SOCKERR_SOCKMODE - Invalid socket mode
    

Note

The option as PACK_REMAINED of SO_PACKINFO is valid only in NON-TCP mode.

Definition at line 620 of file socket.c.

References CHECK_SOCKNUM, getSn_MR, getSn_MR2, and SO_FLAG.

Referenced by loopback_tcpc(), loopback_tcps(), and loopback_udps().

peeksockmsg()

int16_t peeksockmsg	(	uint8_t	sn,
		uint8_t *	submsg,
		uint16_t	subsize
	)

Peeks a sub-message in SOCKETn RX buffer.

It peeks the incoming message of SOCKETn RX buffer.
It can find the specified sub-message in the incoming message and return the length of incoming message before the sub-message.
It is useful when you need to read each messages from multiple message in SOCKET RX buffer.

Parameters

sn	SOCKET number
submsg	sub-message pointer to find
subsize	the length of submsg

Returns

• Success : the length of incoming message length before the submsg
  
• Fail : -1

Note

It is just return the length of incoming message before the found sub-message. It does not receive the message.
So, after calling peeksockmsg, _Sn_RX_RD_ is not changed.

Definition at line 689 of file socket.c.

References getSn_RX_RD, getSn_RX_RSR(), WIZCHIP_OFFSET_INC, WIZCHIP_READ(), and WIZCHIP_RXBUF_BLOCK.