\section{IPv6 functions}

% Short description/overview of module functions

\subsection{pico$\_$ipv6$\_$to$\_$string}

\subsubsection*{Description}
Convert the internet host address IP to a string in IPv6 colon:hex notation.
The result is stored in the char array that ipbuf points to.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_to_string(char *ipbuf, const uint8_t ip[PICO_SIZE_IP6]);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{ipbuf} - Char array to store the result in.
\item \texttt{ip} - Internet host address in unsigned byte array notation of lenght 16.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns 0 if the conversion was successful.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_to_string(buf, ip);
\end{verbatim}

\subsection{pico$\_$string$\_$to$\_$ipv6}

\subsubsection*{Description}
Convert the IPv6 colon:hex notation into binary form. The result is stored in the
\texttt{int} that IP points to. 
The address supplied in \texttt{ipstr} can have one of the default forms for IPv6 address
description, including at most one abbreviation skipping zeroed fields using "::"

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_string_to_ipv6(const char *ipstr, uint8_t *ip); 
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{ipstr} - Pointer to the IP string.
\item \texttt{ip} - Int pointer to store the result in.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns 0 if the conversion was successful.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_string_to_ipv6("fe80::1", *ip);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$unicast}

\subsubsection*{Description}
Check if the provided address is unicast or multicast.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_unicast(struct pico_ip6 *a);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}

\subsubsection*{Return value}
Returns 1 if unicast, 0 if multicast.

%\subsubsection*{Errors}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_unicast(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$multicast}
\subsubsection*{Description}
Check if the provided address is a valid Internet multicast address, i.e. it belongs to the range ff00::/8.
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_multicast(struct pico_ip6 *a);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}
\subsubsection*{Return value}
Returns 1 if a multicast Internet address has been provided.
%\subsubsection*{Errors}
\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_multicast(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$global}

\subsubsection*{Description}
Check if the provided address is a valid Internet global address, i.e. it belongs to the range 2000::/3.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_global(struct pico_ip6 *a);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}

\subsubsection*{Return value}
Returns 1 if a global Internet address has been provided.

%\subsubsection*{Errors}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_global(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$uniquelocal}

\subsubsection*{Description}
Check if the provided address is a valid Internet uniquelocal address, i.e. it belongs to the range fc00::/7.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_uniquelocal(struct pico_ip6 *a);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}

\subsubsection*{Return value}
Returns 1 if a uniquelocal Internet address has been provided.

%\subsubsection*{Errors}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_uniquelocal(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$sitelocal}
\subsubsection*{Description}
Check if the provided address is a valid Internet sitelocal address, i.e. it belongs to the range fec0::/10.
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_sitelocal(struct pico_ip6 *a);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}
\subsubsection*{Return value}
Returns 1 if a sitelocal Internet address has been provided.
%\subsubsection*{Errors}
\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_sitelocal(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$linklocal}
\subsubsection*{Description}
Check if the provided address is a valid Internet linklocal address, i.e. it belongs to the range fe80::/10.
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_linklocal(struct pico_ip6 *a);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}
\subsubsection*{Return value}
Returns 1 if a linklocal Internet address has been provided.
%\subsubsection*{Errors}
\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_linklocal(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$localhost}
\subsubsection*{Description}
Check if the provided address is a valid Internet localhost address, i.e. it is "::1".
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_localhost(struct pico_ip6 *a);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}
\subsubsection*{Return value}
Returns 1 if a localhost Internet address has been provided.
%\subsubsection*{Errors}
\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_localhost(address);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$is$\_$undefined}
\subsubsection*{Description}
Check if the provided address is a valid Internet undefined address, i.e. it is "::0".
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_is_undefined(struct pico_ip6 *a);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Internet host address.
\end{itemize}
\subsubsection*{Return value}
Returns 1 if the Internet address provided describes ANY host.
%\subsubsection*{Errors}
\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_is_undefined(address);
\end{verbatim}


\subsection{pico$\_$ipv6$\_$source$\_$find}

\subsubsection*{Description}
Find the source IP for the link associated to the specified destination.
This 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.

\subsubsection*{Function prototype}
\begin{verbatim}
struct pico_ip6 *pico_ipv6_source_find(struct pico_ip6 *dst);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip6}.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns the source IP as \texttt{struct pico$\_$ip6}.
If the source can not be found, \texttt{NULL} is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
src = pico_ipv6_source_find(dst);
\end{verbatim}




\subsection{pico$\_$ipv6$\_$link$\_$add }

\subsubsection*{Description}
Add 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.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_link_add(struct pico_device *dev, struct pico_ip6 address,
struct pico_ip6 netmask);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{dev} - Local device.
\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip6}.
\item \texttt{netmask} - Netmask of the address.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns 0.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space
\item \texttt{PICO$\_$ERR$\_$ENETUNREACH} - network unreachable
\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_link_add(dev, address, netmask);
\end{verbatim}



\subsection{pico$\_$ipv6$\_$link$\_$del}

\subsubsection*{Description}
Remove the link associated to the local device that was previously configured, corresponding to the IP address 'address'.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_link_del(struct pico_device *dev, struct pico_ip6 address); 
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{dev} - Local device.
\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip6}.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns 0.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_link_del(dev, address);
\end{verbatim}



\subsection{pico$\_$ipv6$\_$link$\_$find}

\subsubsection*{Description}
Find the local device associated to the local IP address 'address'.

\subsubsection*{Function prototype}
\begin{verbatim}
struct pico_device *pico_ipv6_link_find(struct pico_ip6 *address);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip6}.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns the local device.
On error, \texttt{NULL} is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\item \texttt{PICO$\_$ERR$\_$ENXIO} - no such device or address
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
dev = pico_ipv6_link_find(address);
\end{verbatim}




\subsection{pico$\_$ipv6$\_$route$\_$add}

\subsubsection*{Description}
Add a new route to the destination IP address from the local device link, f.e. eth0.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_route_add(struct pico_ip6 address, struct pico_ip6 netmask,
struct pico_ip6 gateway, int metric, struct pico_ipv6_link *link);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip6}.
\item \texttt{netmask} - Netmask of the address. If zeroed, the call assumes the meaning of adding a default gateway.
\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.
\item \texttt{metric} - Metric for this route.
\item \texttt{link} - Local device interface. If a valid gateway is specified, this parameter is not mandatory, otherwise \texttt{NULL} can be used.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns 0. On error, -1 is returned and \texttt{pico$\_$err} is set appropriately. 
%if the route already exists or no memory could be allocated. 

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\item \texttt{PICO$\_$ERR$\_$ENOMEM} - not enough space
\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable
\item \texttt{PICO$\_$ERR$\_$ENETUNREACH} - network unreachable
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_route_add(dst, netmask, gateway, metric, link);
\end{verbatim}



\subsection{pico$\_$ipv6$\_$route$\_$del}

\subsubsection*{Description}
Remove the route to the destination IP address from the local device link, f.e. etho0.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv6_route_del(struct pico_ip6 address, struct pico_ip6 netmask,
struct pico_ip6 gateway, int metric, struct pico_ipv6_link *link); 
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip6}.
\item \texttt{netmask} - Netmask of the address.
\item \texttt{gateway} - Gateway of the address network.
\item \texttt{metric} - Metric of the route.
\item \texttt{link} - Local device interface.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns 0 if the route is found.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv6_route_del(dst, netmask, gateway, metric, link);
\end{verbatim}



\subsection{pico$\_$ipv6$\_$route$\_$get$\_$gateway}

\subsubsection*{Description}
This function gets the gateway address for the given destination IP address, if set.

\subsubsection*{Function prototype}
\begin{verbatim}
struct pico_ip6 pico_ipv6_route_get_gateway(struct pico_ip6 *addr)
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip6}.
\end{itemize}

\subsubsection*{Return value}
On success the gateway address is returned.
On error a \texttt{null} address is returned (\texttt{0.0.0.0}) and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Errors}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$ERR$\_$EINVAL} - invalid argument
\item \texttt{PICO$\_$ERR$\_$EHOSTUNREACH} - host is unreachable
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
gateway_addr = pico_ip6 pico_ipv6_route_get_gateway(&dest_addr)
\end{verbatim}

\subsection{pico$\_$ipv6$\_$dev$\_$routing$\_$enable}

\subsubsection*{Description}
Enable IPv6 Routing messages through the specified interface. On a picoTCP IPv6 machine, 
when routing is enabled, all possible routes to other links are advertised to the target interfaces.
This allows the hosts connected to the target interface to use the picoTCP IPv6 machine as a router
towards public IPv6 addresses configured on other interfaces, or reachable through known gateways.

\subsubsection*{Function prototype}
\begin{verbatim}
struct pico_ip6 pico_ipv6_dev_routing_enable(struct pico_device *dev)
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{dev} - Pointer to the target device struct \texttt{pico$\_$device}.
\end{itemize}

\subsubsection*{Return value}
On success, zero is returned.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Example}
\begin{verbatim}
retval = pico_ipv6_dev_routing_enable(eth1);
\end{verbatim}

\subsection{pico$\_$ipv6$\_$dev$\_$routing$\_$disable}

\subsubsection*{Description}
Enable IPv6 Routing messages through the specified interface. On a picoTCP IPv6 machine, 
when routing is enabled, all possible routes to other links are advertised to the target interface.
This function will stop advertising reachable routes to public IPv6 addresses configured on other 
interfaces, or reachable through known gateways.

\subsubsection*{Function prototype}
\begin{verbatim}
struct pico_ip6 pico_ipv6_dev_routing_disable(struct pico_device *dev)
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{dev} - Pointer to the target device struct \texttt{pico$\_$device}.
\end{itemize}

\subsubsection*{Return value}
On success, zero is returned.
On error, -1 is returned and \texttt{pico$\_$err} is set appropriately.

\subsubsection*{Example}
\begin{verbatim}
retval = pico_ipv6_dev_routing_disable(eth1);
\end{verbatim}