1\section{IPv4 functions} 2 3% Short description/overview of module functions 4 5\subsection{pico$\_$ipv4$\_$to$\_$string} 6 7\subsubsection*{Description} 8Convert the internet host address IP to a string in IPv4 dotted-decimal notation. 9The result is stored in the char array that ipbuf points to. The given IP address argument must be in network order (i.e. 0xC0A80101 becomes 192.168.1.1). 10 11\subsubsection*{Function prototype} 12\begin{verbatim} 13int pico_ipv4_to_string(char *ipbuf, const uint32_t ip); 14\end{verbatim} 15 16\subsubsection*{Parameters} 17\begin{itemize}[noitemsep] 18\item \texttt{ipbuf} - Char array to store the result in. 19\item \texttt{ip} - Internet host address in integer notation. 20\end{itemize} 21 22\subsubsection*{Return value} 23On success, this call returns 0 if the conversion was successful. 24On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 25 26\subsubsection*{Errors} 27\begin{itemize}[noitemsep] 28\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 29\end{itemize} 30 31\subsubsection*{Example} 32\begin{verbatim} 33ret = pico_ipv4_to_string(buf, ip); 34\end{verbatim} 35 36 37 38\subsection{pico$\_$string$\_$to$\_$ipv4} 39 40\subsubsection*{Description} 41Convert the IPv4 dotted-decimal notation into binary form. The result is stored in the 42\texttt{int} that IP points to. Little endian or big endian is not taken into account. 43The address supplied in \texttt{ipstr} can have one of the following 44forms: a.b.c.d, a.b.c or a.b. 45 46\subsubsection*{Function prototype} 47\begin{verbatim} 48int pico_string_to_ipv4(const char *ipstr, uint32_t *ip); 49\end{verbatim} 50 51\subsubsection*{Parameters} 52\begin{itemize}[noitemsep] 53\item \texttt{ipstr} - Pointer to the IP string. 54\item \texttt{ip} - Int pointer to store the result in. 55\end{itemize} 56 57\subsubsection*{Return value} 58On success, this call returns 0 if the conversion was successful. 59On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 60 61\subsubsection*{Errors} 62\begin{itemize}[noitemsep] 63\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 64\end{itemize} 65 66\subsubsection*{Example} 67\begin{verbatim} 68ret = pico_string_to_ipv4(buf, *ip); 69\end{verbatim} 70 71 72\subsection{pico$\_$ipv4$\_$valid$\_$netmask} 73 74\subsubsection*{Description} 75Check if the provided mask if valid. 76 77\subsubsection*{Function prototype} 78\begin{verbatim} 79int pico_ipv4_valid_netmask(uint32_t mask); 80\end{verbatim} 81 82\subsubsection*{Parameters} 83\begin{itemize}[noitemsep] 84\item \texttt{mask} - The netmask in integer notation. 85\end{itemize} 86 87\subsubsection*{Return value} 88On success, this call returns the netmask in CIDR notation is returned if the netmask is valid. 89On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 90 91\subsubsection*{Errors} 92\begin{itemize}[noitemsep] 93\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 94\end{itemize} 95 96\subsubsection*{Example} 97\begin{verbatim} 98ret = pico_ipv4_valid_netmask(netmask); 99\end{verbatim} 100 101 102\subsection{pico$\_$ipv4$\_$is$\_$unicast} 103 104\subsubsection*{Description} 105Check if the provided address is unicast or multicast. 106 107\subsubsection*{Function prototype} 108\begin{verbatim} 109int pico_ipv4_is_unicast(uint32_t address); 110\end{verbatim} 111 112\subsubsection*{Parameters} 113\begin{itemize}[noitemsep] 114\item \texttt{address} - Internet host address in integer notation. 115\end{itemize} 116 117\subsubsection*{Return value} 118Returns 1 if unicast, 0 if multicast. 119 120%\subsubsection*{Errors} 121 122\subsubsection*{Example} 123\begin{verbatim} 124ret = pico_ipv4_is_unicast(address); 125\end{verbatim} 126 127 128 129\subsection{pico$\_$ipv4$\_$source$\_$find} 130 131\subsubsection*{Description} 132Find the source IP for the link associated to the specified destination. 133This function will use the currently configured routing table to identify the link that would be used to transmit any traffic directed to the given IP address. 134 135\subsubsection*{Function prototype} 136\begin{verbatim} 137struct pico_ip4 *pico_ipv4_source_find(struct pico_ip4 *dst); 138\end{verbatim} 139 140\subsubsection*{Parameters} 141\begin{itemize}[noitemsep] 142\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip4}. 143\end{itemize} 144 145\subsubsection*{Return value} 146On success, this call returns the source IP as \texttt{struct pico$\_$ip4}. 147If the source can not be found, \texttt{NULL} is returned and \texttt{pico$\_$err} is set appropriately. 148 149\subsubsection*{Errors} 150\begin{itemize}[noitemsep] 151\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 152\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 153\end{itemize} 154 155\subsubsection*{Example} 156\begin{verbatim} 157src = pico_ipv4_source_find(dst); 158\end{verbatim} 159 160 161 162 163\subsection{pico$\_$ipv4$\_$link$\_$add } 164 165\subsubsection*{Description} 166Add a new local device dev inteface, f.e. eth0, with IP address 'address' and netmask 'netmask'. A device may have more than one link configured, i.e. to access multiple networks on the same link. 167 168\subsubsection*{Function prototype} 169\begin{verbatim} 170int pico_ipv4_link_add(struct pico_device *dev, struct pico_ip4 address, 171struct pico_ip4 netmask); 172\end{verbatim} 173 174\subsubsection*{Parameters} 175\begin{itemize}[noitemsep] 176\item \texttt{dev} - Local device. 177\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip4}. 178\item \texttt{netmask} - Netmask of the address. 179\end{itemize} 180 181\subsubsection*{Return value} 182On success, this call returns 0. 183On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 184 185\subsubsection*{Errors} 186\begin{itemize}[noitemsep] 187\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 188\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space 189\item \texttt{PICO$\_$ERR$\_$ENETUNREACH} - network unreachable 190\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 191\end{itemize} 192 193\subsubsection*{Example} 194\begin{verbatim} 195ret = pico_ipv4_link_add(dev, address, netmask); 196\end{verbatim} 197 198 199 200\subsection{pico$\_$ipv4$\_$link$\_$del} 201 202\subsubsection*{Description} 203Remove the link associated to the local device that was previously configured, corresponding to the IP address 'address'. 204 205\subsubsection*{Function prototype} 206\begin{verbatim} 207int pico_ipv4_link_del(struct pico_device *dev, struct pico_ip4 address); 208\end{verbatim} 209 210\subsubsection*{Parameters} 211\begin{itemize}[noitemsep] 212\item \texttt{dev} - Local device. 213\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip4}. 214\end{itemize} 215 216\subsubsection*{Return value} 217On success, this call returns 0. 218On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 219 220\subsubsection*{Errors} 221\begin{itemize}[noitemsep] 222\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 223\end{itemize} 224 225\subsubsection*{Example} 226\begin{verbatim} 227ret = pico_ipv4_link_del(dev, address); 228\end{verbatim} 229 230 231 232\subsection{pico$\_$ipv4$\_$link$\_$find} 233 234\subsubsection*{Description} 235Find the local device associated to the local IP address 'address'. 236 237\subsubsection*{Function prototype} 238\begin{verbatim} 239struct pico_device *pico_ipv4_link_find(struct pico_ip4 *address); 240\end{verbatim} 241 242\subsubsection*{Parameters} 243\begin{itemize}[noitemsep] 244\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip4}. 245\end{itemize} 246 247\subsubsection*{Return value} 248On success, this call returns the local device. 249On error, \texttt{NULL} is returned and \texttt{pico$\_$err} is set appropriately. 250 251\subsubsection*{Errors} 252\begin{itemize}[noitemsep] 253\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 254\item \texttt{PICO$\_$ERR$\_$ENXIO} - no such device or address 255\end{itemize} 256 257\subsubsection*{Example} 258\begin{verbatim} 259dev = pico_ipv4_link_find(address); 260\end{verbatim} 261 262 263 264\subsection{pico$\_$ipv4$\_$nat$\_$enable} 265 266\subsubsection*{Description} 267This function enables NAT functionality on the passed IPv4 link. 268Forwarded packets from an internal network will have the public IP address from the passed link 269and a translated port number for transmission on the external network. 270Usual operation requires at least one additional link for the internal network, 271which is used as a gateway for the internal hosts. 272 273\subsubsection*{Function prototype} 274\begin{verbatim} 275int pico_ipv4_nat_enable(struct pico_ipv4_link *link) 276\end{verbatim} 277 278\subsubsection*{Parameters} 279\begin{itemize}[noitemsep] 280\item \texttt{link} - Pointer to a link \texttt{pico$\_$ipv4$\_$link}. 281\end{itemize} 282 283\subsubsection*{Return value} 284On success, this call returns 0. 285On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 286 287\subsubsection*{Errors} 288\begin{itemize}[noitemsep] 289\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 290\end{itemize} 291 292\subsubsection*{Example} 293\begin{verbatim} 294ret = pico_ipv4_nat_enable(&external_link); 295\end{verbatim} 296 297 298 299\subsection{pico$\_$ipv4$\_$nat$\_$disable} 300 301\subsubsection*{Description} 302Disables the NAT functionality. 303 304\subsubsection*{Function prototype} 305\begin{verbatim} 306int pico_ipv4_nat_disable(void); 307\end{verbatim} 308 309%\subsubsection*{Parameters} 310 311\subsubsection*{Return value} 312Always returns 0. 313 314%\subsubsection*{Errors} 315%\subsubsection*{Example} 316 317 318\subsection{pico$\_$ipv4$\_$port$\_$forward} 319 320\subsubsection*{Description} 321This function adds or deletes a rule in the IP forwarding table. Internally in the stack, 322a one-direction NAT entry will be made. 323 324\subsubsection*{Function prototype} 325\begin{verbatim} 326int pico_ipv4_port_forward(struct pico_ip4 pub_addr, uint16_t pub_port, 327struct pico_ip4 priv_addr, uint16_t priv_port, uint8_t proto, 328uint8_t persistant) 329\end{verbatim} 330 331\subsubsection*{Parameters} 332\begin{itemize}[noitemsep] 333\item \texttt{pub$\_$addr} - Public IP address, must be identical to the address of the external link. 334\item \texttt{pub$\_$port} - Public port to be translated. 335\item \texttt{priv$\_$addr} - Private IP address of the host on the internal network. 336\item \texttt{priv$\_$port} - Private port of the host on the internal network. 337\item \texttt{proto} - Protocol identifier, see supported list below. 338\item \texttt{persistant} - Option for function call: create \texttt{PICO$\_$IPV4$\_$FORWARD$\_$ADD} (= 1) \\ 339or delete \texttt{PICO$\_$IPV4$\_$FORWARD$\_$DEL} (= 0). 340\end{itemize} 341 342\subsubsection*{Protocol list} 343\begin{itemize}[noitemsep] 344\item \texttt{PICO$\_$PROTO$\_$ICMP4} 345\item \texttt{PICO$\_$PROTO$\_$TCP} 346\item \texttt{PICO$\_$PROTO$\_$UDP} 347\end{itemize} 348 349\subsubsection*{Return value} 350On success, this call 0 after a succesfull entry of the forward rule. 351On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 352 353\subsubsection*{Errors} 354\begin{itemize}[noitemsep] 355\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 356\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space 357\item \texttt{PICO$\_$ERR$\_$EAGAIN} - not succesfull, try again 358\end{itemize} 359 360\subsubsection*{Example} 361\begin{verbatim} 362ret = pico_ipv4_port_forward(ext_link_addr, ext_port, host_addr, 363host_port, PICO_PROTO_UDP, 1); 364\end{verbatim} 365 366 367 368\subsection{pico$\_$ipv4$\_$route$\_$add} 369 370\subsubsection*{Description} 371Add a new route to the destination IP address from the local device link, f.e. eth0. 372 373\subsubsection*{Function prototype} 374\begin{verbatim} 375int pico_ipv4_route_add(struct pico_ip4 address, struct pico_ip4 netmask, 376struct pico_ip4 gateway, int metric, struct pico_ipv4_link *link); 377\end{verbatim} 378 379\subsubsection*{Parameters} 380\begin{itemize}[noitemsep] 381\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip4}. 382\item \texttt{netmask} - Netmask of the address. If zeroed, the call assumes the meaning of adding a default gateway. 383\item \texttt{gateway} - Gateway of the address network. If zeroed, no gateway will be associated to this route, and the traffic towards the destination will be simply forwarded towards the given device. 384\item \texttt{metric} - Metric for this route. 385\item \texttt{link} - Local device interface. If a valid gateway is specified, this parameter is not mandatory, otherwise \texttt{NULL} can be used. 386\end{itemize} 387 388\subsubsection*{Return value} 389On success, this call returns 0. On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 390%if the route already exists or no memory could be allocated. 391 392\subsubsection*{Errors} 393\begin{itemize}[noitemsep] 394\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 395\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space 396\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 397\item \texttt{PICO$\_$ERR$\_$ENETUNREACH} - network unreachable 398\end{itemize} 399 400\subsubsection*{Example} 401\begin{verbatim} 402ret = pico_ipv4_route_add(dst, netmask, gateway, metric, link); 403\end{verbatim} 404 405 406 407\subsection{pico$\_$ipv4$\_$route$\_$del} 408 409\subsubsection*{Description} 410Remove the route to the destination IP address from the local device link, f.e. etho0. 411 412\subsubsection*{Function prototype} 413\begin{verbatim} 414int pico_ipv4_route_del(struct pico_ip4 address, struct pico_ip4 netmask, 415struct pico_ip4 gateway, int metric, struct pico_ipv4_link *link); 416\end{verbatim} 417 418\subsubsection*{Parameters} 419\begin{itemize}[noitemsep] 420\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip4}. 421\item \texttt{netmask} - Netmask of the address. 422\item \texttt{gateway} - Gateway of the address network. 423\item \texttt{metric} - Metric of the route. 424\item \texttt{link} - Local device interface. 425\end{itemize} 426 427\subsubsection*{Return value} 428On success, this call returns 0 if the route is found. 429On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 430 431\subsubsection*{Errors} 432\begin{itemize}[noitemsep] 433\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 434\end{itemize} 435 436\subsubsection*{Example} 437\begin{verbatim} 438ret = pico_ipv4_route_del(dst, netmask, gateway, metric, link); 439\end{verbatim} 440 441 442 443\subsection{pico$\_$ipv4$\_$route$\_$get$\_$gateway} 444 445\subsubsection*{Description} 446This function gets the gateway address for the given destination IP address, if set. 447 448\subsubsection*{Function prototype} 449\begin{verbatim} 450struct pico_ip4 pico_ipv4_route_get_gateway(struct pico_ip4 *addr) 451\end{verbatim} 452 453\subsubsection*{Parameters} 454\begin{itemize}[noitemsep] 455\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip4}. 456\end{itemize} 457 458\subsubsection*{Return value} 459On success the gateway address is returned. 460On error a \texttt{null} address is returned (\texttt{0.0.0.0}) and \texttt{pico$\_$err} is set appropriately. 461 462\subsubsection*{Errors} 463\begin{itemize}[noitemsep] 464\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 465\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 466\end{itemize} 467 468\subsubsection*{Example} 469\begin{verbatim} 470gateway_addr = pico_ip4 pico_ipv4_route_get_gateway(&dest_addr) 471\end{verbatim} 472 473 474\subsection{pico$\_$icmp4$\_$ping} 475 476\subsubsection*{Description} 477This function sends out a number of ping echo requests and checks if the replies are received correctly. 478The information from the replies is passed to the callback function after a succesfull reception. 479If a timeout expires before a reply is received, the callback is called with the error condition. 480 481\subsubsection*{Function prototype} 482\begin{verbatim} 483int pico_icmp4_ping(char *dst, int count, int interval, int timeout, int size, 484void (*cb)(struct pico_icmp4_stats *)); 485\end{verbatim} 486 487\subsubsection*{Parameters} 488\begin{itemize}[noitemsep] 489\item \texttt{dst} - Pointer to the destination internet host address as text string 490\item \texttt{count} - Number of pings going to be send 491\item \texttt{interval} - Time between two transmissions (in ms) 492\item \texttt{timeout} - Timeout period untill reply received (in ms) 493\item \texttt{size} - Size of data buffer in bytes 494\item \texttt{cb} - Callback for ICMP ping 495\end{itemize} 496 497\subsubsection*{Data structure \texttt{struct pico$\_$icmp4$\_$stats}} 498\begin{verbatim} 499struct pico_icmp4_stats 500{ 501 struct pico_ip4 dst; 502 unsigned long size; 503 unsigned long seq; 504 unsigned long time; 505 unsigned long ttl; 506 int err; 507}; 508\end{verbatim} 509With \textbf{err} values: 510\begin{itemize}[noitemsep] 511\item \texttt{PICO$\_$PING$\_$ERR$\_$REPLIED} (value 0) 512\item \texttt{PICO$\_$PING$\_$ERR$\_$TIMEOUT} (value 1) 513\item \texttt{PICO$\_$PING$\_$ERR$\_$UNREACH} (value 2) 514\item \texttt{PICO$\_$PING$\_$ERR$\_$PENDING} (value 0xFFFF) 515\end{itemize} 516 517\subsubsection*{Return value} 518On success, this call returns a positive number, which is the ID of the ping operation just started. 519On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 520 521\subsubsection*{Errors} 522\begin{itemize}[noitemsep] 523\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 524\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space 525\end{itemize} 526 527\subsubsection*{Example} 528\begin{verbatim} 529id = pico_icmp4_ping(dst_addr, 30, 10, 100, 1000, callback); 530\end{verbatim} 531 532 533\subsection{pico$\_$icmp4$\_$ping$\_$abort} 534 535\subsubsection*{Description} 536This function aborts an ongoing ping operation that has previously started using pico$\_$icmp4$\_$ping(). 537 538\subsubsection*{Function prototype} 539\begin{verbatim} 540int pico_icmp4_ping_abort(int id); 541\end{verbatim} 542 543\subsubsection*{Parameters} 544\begin{itemize}[noitemsep] 545 \item \texttt{id} - identification number for the ping operation. This has been returned by \texttt{pico$\_$icmp4$\_$ping()} and it is intended to distinguish the operation to be cancelled. 546\end{itemize} 547 548\subsubsection*{Return value} 549On success, this call returns 0. 550On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 551 552\subsubsection*{Errors} 553\begin{itemize}[noitemsep] 554\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 555\end{itemize} 556 557\subsubsection*{Example} 558\begin{verbatim} 559ret = pico_icmp4_ping_abort(id); 560\end{verbatim} 561 562