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