1\section{IPv6 functions} 2 3% Short description/overview of module functions 4 5\subsection{pico$\_$ipv6$\_$to$\_$string} 6 7\subsubsection*{Description} 8Convert the internet host address IP to a string in IPv6 colon:hex notation. 9The result is stored in the char array that ipbuf points to. 10 11\subsubsection*{Function prototype} 12\begin{verbatim} 13int pico_ipv6_to_string(char *ipbuf, const uint8_t ip[PICO_SIZE_IP6]); 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 unsigned byte array notation of lenght 16. 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_ipv6_to_string(buf, ip); 34\end{verbatim} 35 36\subsection{pico$\_$string$\_$to$\_$ipv6} 37 38\subsubsection*{Description} 39Convert the IPv6 colon:hex notation into binary form. The result is stored in the 40\texttt{int} that IP points to. 41The address supplied in \texttt{ipstr} can have one of the default forms for IPv6 address 42description, including at most one abbreviation skipping zeroed fields using "::" 43 44\subsubsection*{Function prototype} 45\begin{verbatim} 46int pico_string_to_ipv6(const char *ipstr, uint8_t *ip); 47\end{verbatim} 48 49\subsubsection*{Parameters} 50\begin{itemize}[noitemsep] 51\item \texttt{ipstr} - Pointer to the IP string. 52\item \texttt{ip} - Int pointer to store the result in. 53\end{itemize} 54 55\subsubsection*{Return value} 56On success, this call returns 0 if the conversion was successful. 57On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 58 59\subsubsection*{Errors} 60\begin{itemize}[noitemsep] 61\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 62\end{itemize} 63 64\subsubsection*{Example} 65\begin{verbatim} 66ret = pico_string_to_ipv6("fe80::1", *ip); 67\end{verbatim} 68 69\subsection{pico$\_$ipv6$\_$is$\_$unicast} 70 71\subsubsection*{Description} 72Check if the provided address is unicast or multicast. 73 74\subsubsection*{Function prototype} 75\begin{verbatim} 76int pico_ipv6_is_unicast(struct pico_ip6 *a); 77\end{verbatim} 78 79\subsubsection*{Parameters} 80\begin{itemize}[noitemsep] 81\item \texttt{address} - Internet host address. 82\end{itemize} 83 84\subsubsection*{Return value} 85Returns 1 if unicast, 0 if multicast. 86 87%\subsubsection*{Errors} 88 89\subsubsection*{Example} 90\begin{verbatim} 91ret = pico_ipv6_is_unicast(address); 92\end{verbatim} 93 94\subsection{pico$\_$ipv6$\_$is$\_$multicast} 95\subsubsection*{Description} 96Check if the provided address is a valid Internet multicast address, i.e. it belongs to the range ff00::/8. 97\subsubsection*{Function prototype} 98\begin{verbatim} 99int pico_ipv6_is_multicast(struct pico_ip6 *a); 100\end{verbatim} 101\subsubsection*{Parameters} 102\begin{itemize}[noitemsep] 103\item \texttt{address} - Internet host address. 104\end{itemize} 105\subsubsection*{Return value} 106Returns 1 if a multicast Internet address has been provided. 107%\subsubsection*{Errors} 108\subsubsection*{Example} 109\begin{verbatim} 110ret = pico_ipv6_is_multicast(address); 111\end{verbatim} 112 113\subsection{pico$\_$ipv6$\_$is$\_$global} 114 115\subsubsection*{Description} 116Check if the provided address is a valid Internet global address, i.e. it belongs to the range 2000::/3. 117 118\subsubsection*{Function prototype} 119\begin{verbatim} 120int pico_ipv6_is_global(struct pico_ip6 *a); 121\end{verbatim} 122 123\subsubsection*{Parameters} 124\begin{itemize}[noitemsep] 125\item \texttt{address} - Internet host address. 126\end{itemize} 127 128\subsubsection*{Return value} 129Returns 1 if a global Internet address has been provided. 130 131%\subsubsection*{Errors} 132 133\subsubsection*{Example} 134\begin{verbatim} 135ret = pico_ipv6_is_global(address); 136\end{verbatim} 137 138\subsection{pico$\_$ipv6$\_$is$\_$uniquelocal} 139 140\subsubsection*{Description} 141Check if the provided address is a valid Internet uniquelocal address, i.e. it belongs to the range fc00::/7. 142 143\subsubsection*{Function prototype} 144\begin{verbatim} 145int pico_ipv6_is_uniquelocal(struct pico_ip6 *a); 146\end{verbatim} 147 148\subsubsection*{Parameters} 149\begin{itemize}[noitemsep] 150\item \texttt{address} - Internet host address. 151\end{itemize} 152 153\subsubsection*{Return value} 154Returns 1 if a uniquelocal Internet address has been provided. 155 156%\subsubsection*{Errors} 157 158\subsubsection*{Example} 159\begin{verbatim} 160ret = pico_ipv6_is_uniquelocal(address); 161\end{verbatim} 162 163\subsection{pico$\_$ipv6$\_$is$\_$sitelocal} 164\subsubsection*{Description} 165Check if the provided address is a valid Internet sitelocal address, i.e. it belongs to the range fec0::/10. 166\subsubsection*{Function prototype} 167\begin{verbatim} 168int pico_ipv6_is_sitelocal(struct pico_ip6 *a); 169\end{verbatim} 170\subsubsection*{Parameters} 171\begin{itemize}[noitemsep] 172\item \texttt{address} - Internet host address. 173\end{itemize} 174\subsubsection*{Return value} 175Returns 1 if a sitelocal Internet address has been provided. 176%\subsubsection*{Errors} 177\subsubsection*{Example} 178\begin{verbatim} 179ret = pico_ipv6_is_sitelocal(address); 180\end{verbatim} 181 182\subsection{pico$\_$ipv6$\_$is$\_$linklocal} 183\subsubsection*{Description} 184Check if the provided address is a valid Internet linklocal address, i.e. it belongs to the range fe80::/10. 185\subsubsection*{Function prototype} 186\begin{verbatim} 187int pico_ipv6_is_linklocal(struct pico_ip6 *a); 188\end{verbatim} 189\subsubsection*{Parameters} 190\begin{itemize}[noitemsep] 191\item \texttt{address} - Internet host address. 192\end{itemize} 193\subsubsection*{Return value} 194Returns 1 if a linklocal Internet address has been provided. 195%\subsubsection*{Errors} 196\subsubsection*{Example} 197\begin{verbatim} 198ret = pico_ipv6_is_linklocal(address); 199\end{verbatim} 200 201\subsection{pico$\_$ipv6$\_$is$\_$localhost} 202\subsubsection*{Description} 203Check if the provided address is a valid Internet localhost address, i.e. it is "::1". 204\subsubsection*{Function prototype} 205\begin{verbatim} 206int pico_ipv6_is_localhost(struct pico_ip6 *a); 207\end{verbatim} 208\subsubsection*{Parameters} 209\begin{itemize}[noitemsep] 210\item \texttt{address} - Internet host address. 211\end{itemize} 212\subsubsection*{Return value} 213Returns 1 if a localhost Internet address has been provided. 214%\subsubsection*{Errors} 215\subsubsection*{Example} 216\begin{verbatim} 217ret = pico_ipv6_is_localhost(address); 218\end{verbatim} 219 220\subsection{pico$\_$ipv6$\_$is$\_$undefined} 221\subsubsection*{Description} 222Check if the provided address is a valid Internet undefined address, i.e. it is "::0". 223\subsubsection*{Function prototype} 224\begin{verbatim} 225int pico_ipv6_is_undefined(struct pico_ip6 *a); 226\end{verbatim} 227\subsubsection*{Parameters} 228\begin{itemize}[noitemsep] 229\item \texttt{address} - Internet host address. 230\end{itemize} 231\subsubsection*{Return value} 232Returns 1 if the Internet address provided describes ANY host. 233%\subsubsection*{Errors} 234\subsubsection*{Example} 235\begin{verbatim} 236ret = pico_ipv6_is_undefined(address); 237\end{verbatim} 238 239 240\subsection{pico$\_$ipv6$\_$source$\_$find} 241 242\subsubsection*{Description} 243Find the source IP for the link associated to the specified destination. 244This 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. 245 246\subsubsection*{Function prototype} 247\begin{verbatim} 248struct pico_ip6 *pico_ipv6_source_find(struct pico_ip6 *dst); 249\end{verbatim} 250 251\subsubsection*{Parameters} 252\begin{itemize}[noitemsep] 253\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip6}. 254\end{itemize} 255 256\subsubsection*{Return value} 257On success, this call returns the source IP as \texttt{struct pico$\_$ip6}. 258If the source can not be found, \texttt{NULL} is returned and \texttt{pico$\_$err} is set appropriately. 259 260\subsubsection*{Errors} 261\begin{itemize}[noitemsep] 262\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 263\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 264\end{itemize} 265 266\subsubsection*{Example} 267\begin{verbatim} 268src = pico_ipv6_source_find(dst); 269\end{verbatim} 270 271 272 273 274\subsection{pico$\_$ipv6$\_$link$\_$add } 275 276\subsubsection*{Description} 277Add 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. 278 279\subsubsection*{Function prototype} 280\begin{verbatim} 281int pico_ipv6_link_add(struct pico_device *dev, struct pico_ip6 address, 282struct pico_ip6 netmask); 283\end{verbatim} 284 285\subsubsection*{Parameters} 286\begin{itemize}[noitemsep] 287\item \texttt{dev} - Local device. 288\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip6}. 289\item \texttt{netmask} - Netmask of the address. 290\end{itemize} 291 292\subsubsection*{Return value} 293On success, this call returns 0. 294On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 295 296\subsubsection*{Errors} 297\begin{itemize}[noitemsep] 298\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 299\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space 300\item \texttt{PICO$\_$ERR$\_$ENETUNREACH} - network unreachable 301\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 302\end{itemize} 303 304\subsubsection*{Example} 305\begin{verbatim} 306ret = pico_ipv6_link_add(dev, address, netmask); 307\end{verbatim} 308 309 310 311\subsection{pico$\_$ipv6$\_$link$\_$del} 312 313\subsubsection*{Description} 314Remove the link associated to the local device that was previously configured, corresponding to the IP address 'address'. 315 316\subsubsection*{Function prototype} 317\begin{verbatim} 318int pico_ipv6_link_del(struct pico_device *dev, struct pico_ip6 address); 319\end{verbatim} 320 321\subsubsection*{Parameters} 322\begin{itemize}[noitemsep] 323\item \texttt{dev} - Local device. 324\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip6}. 325\end{itemize} 326 327\subsubsection*{Return value} 328On success, this call returns 0. 329On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 330 331\subsubsection*{Errors} 332\begin{itemize}[noitemsep] 333\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 334\end{itemize} 335 336\subsubsection*{Example} 337\begin{verbatim} 338ret = pico_ipv6_link_del(dev, address); 339\end{verbatim} 340 341 342 343\subsection{pico$\_$ipv6$\_$link$\_$find} 344 345\subsubsection*{Description} 346Find the local device associated to the local IP address 'address'. 347 348\subsubsection*{Function prototype} 349\begin{verbatim} 350struct pico_device *pico_ipv6_link_find(struct pico_ip6 *address); 351\end{verbatim} 352 353\subsubsection*{Parameters} 354\begin{itemize}[noitemsep] 355\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip6}. 356\end{itemize} 357 358\subsubsection*{Return value} 359On success, this call returns the local device. 360On error, \texttt{NULL} is returned and \texttt{pico$\_$err} is set appropriately. 361 362\subsubsection*{Errors} 363\begin{itemize}[noitemsep] 364\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 365\item \texttt{PICO$\_$ERR$\_$ENXIO} - no such device or address 366\end{itemize} 367 368\subsubsection*{Example} 369\begin{verbatim} 370dev = pico_ipv6_link_find(address); 371\end{verbatim} 372 373 374 375 376\subsection{pico$\_$ipv6$\_$route$\_$add} 377 378\subsubsection*{Description} 379Add a new route to the destination IP address from the local device link, f.e. eth0. 380 381\subsubsection*{Function prototype} 382\begin{verbatim} 383int pico_ipv6_route_add(struct pico_ip6 address, struct pico_ip6 netmask, 384struct pico_ip6 gateway, int metric, struct pico_ipv6_link *link); 385\end{verbatim} 386 387\subsubsection*{Parameters} 388\begin{itemize}[noitemsep] 389\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip6}. 390\item \texttt{netmask} - Netmask of the address. If zeroed, the call assumes the meaning of adding a default gateway. 391\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. 392\item \texttt{metric} - Metric for this route. 393\item \texttt{link} - Local device interface. If a valid gateway is specified, this parameter is not mandatory, otherwise \texttt{NULL} can be used. 394\end{itemize} 395 396\subsubsection*{Return value} 397On success, this call returns 0. On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 398%if the route already exists or no memory could be allocated. 399 400\subsubsection*{Errors} 401\begin{itemize}[noitemsep] 402\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 403\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space 404\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 405\item \texttt{PICO$\_$ERR$\_$ENETUNREACH} - network unreachable 406\end{itemize} 407 408\subsubsection*{Example} 409\begin{verbatim} 410ret = pico_ipv6_route_add(dst, netmask, gateway, metric, link); 411\end{verbatim} 412 413 414 415\subsection{pico$\_$ipv6$\_$route$\_$del} 416 417\subsubsection*{Description} 418Remove the route to the destination IP address from the local device link, f.e. etho0. 419 420\subsubsection*{Function prototype} 421\begin{verbatim} 422int pico_ipv6_route_del(struct pico_ip6 address, struct pico_ip6 netmask, 423struct pico_ip6 gateway, int metric, struct pico_ipv6_link *link); 424\end{verbatim} 425 426\subsubsection*{Parameters} 427\begin{itemize}[noitemsep] 428\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip6}. 429\item \texttt{netmask} - Netmask of the address. 430\item \texttt{gateway} - Gateway of the address network. 431\item \texttt{metric} - Metric of the route. 432\item \texttt{link} - Local device interface. 433\end{itemize} 434 435\subsubsection*{Return value} 436On success, this call returns 0 if the route is found. 437On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 438 439\subsubsection*{Errors} 440\begin{itemize}[noitemsep] 441\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 442\end{itemize} 443 444\subsubsection*{Example} 445\begin{verbatim} 446ret = pico_ipv6_route_del(dst, netmask, gateway, metric, link); 447\end{verbatim} 448 449 450 451\subsection{pico$\_$ipv6$\_$route$\_$get$\_$gateway} 452 453\subsubsection*{Description} 454This function gets the gateway address for the given destination IP address, if set. 455 456\subsubsection*{Function prototype} 457\begin{verbatim} 458struct pico_ip6 pico_ipv6_route_get_gateway(struct pico_ip6 *addr) 459\end{verbatim} 460 461\subsubsection*{Parameters} 462\begin{itemize}[noitemsep] 463\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip6}. 464\end{itemize} 465 466\subsubsection*{Return value} 467On success the gateway address is returned. 468On error a \texttt{null} address is returned (\texttt{0.0.0.0}) and \texttt{pico$\_$err} is set appropriately. 469 470\subsubsection*{Errors} 471\begin{itemize}[noitemsep] 472\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument 473\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable 474\end{itemize} 475 476\subsubsection*{Example} 477\begin{verbatim} 478gateway_addr = pico_ip6 pico_ipv6_route_get_gateway(&dest_addr) 479\end{verbatim} 480 481\subsection{pico$\_$ipv6$\_$dev$\_$routing$\_$enable} 482 483\subsubsection*{Description} 484Enable IPv6 Routing messages through the specified interface. On a picoTCP IPv6 machine, 485when routing is enabled, all possible routes to other links are advertised to the target interfaces. 486This allows the hosts connected to the target interface to use the picoTCP IPv6 machine as a router 487towards public IPv6 addresses configured on other interfaces, or reachable through known gateways. 488 489\subsubsection*{Function prototype} 490\begin{verbatim} 491struct pico_ip6 pico_ipv6_dev_routing_enable(struct pico_device *dev) 492\end{verbatim} 493 494\subsubsection*{Parameters} 495\begin{itemize}[noitemsep] 496\item \texttt{dev} - Pointer to the target device struct \texttt{pico$\_$device}. 497\end{itemize} 498 499\subsubsection*{Return value} 500On success, zero is returned. 501On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 502 503\subsubsection*{Example} 504\begin{verbatim} 505retval = pico_ipv6_dev_routing_enable(eth1); 506\end{verbatim} 507 508\subsection{pico$\_$ipv6$\_$dev$\_$routing$\_$disable} 509 510\subsubsection*{Description} 511Enable IPv6 Routing messages through the specified interface. On a picoTCP IPv6 machine, 512when routing is enabled, all possible routes to other links are advertised to the target interface. 513This function will stop advertising reachable routes to public IPv6 addresses configured on other 514interfaces, or reachable through known gateways. 515 516\subsubsection*{Function prototype} 517\begin{verbatim} 518struct pico_ip6 pico_ipv6_dev_routing_disable(struct pico_device *dev) 519\end{verbatim} 520 521\subsubsection*{Parameters} 522\begin{itemize}[noitemsep] 523\item \texttt{dev} - Pointer to the target device struct \texttt{pico$\_$device}. 524\end{itemize} 525 526\subsubsection*{Return value} 527On success, zero is returned. 528On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 529 530\subsubsection*{Example} 531\begin{verbatim} 532retval = pico_ipv6_dev_routing_disable(eth1); 533\end{verbatim} 534