chap_api_ipv4.tex

\section{IPv4 functions}

% Short description/overview of module functions

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

\subsubsection*{Description}
Convert the internet host address IP to a string in IPv4 dotted-decimal notation.
The 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).

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_to_string(char *ipbuf, const uint32_t ip);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{ipbuf} - Char array to store the result in.
\item \texttt{ip} - Internet host address in integer notation.
\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_ipv4_to_string(buf, ip);
\end{verbatim}



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

\subsubsection*{Description}
Convert the IPv4 dotted-decimal notation into binary form. The result is stored in the
\texttt{int} that IP points to. Little endian or big endian is not taken into account.
The address supplied in \texttt{ipstr} can have one of the following
forms: a.b.c.d, a.b.c or a.b.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_string_to_ipv4(const char *ipstr, uint32_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_ipv4(buf, *ip);
\end{verbatim}


\subsection{pico$\_$ipv4$\_$valid$\_$netmask}

\subsubsection*{Description}
Check if the provided mask if valid.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_valid_netmask(uint32_t mask);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{mask} - The netmask in integer notation.
\end{itemize}

\subsubsection*{Return value}
On success, this call returns the netmask in CIDR notation is returned if the netmask is valid.
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_ipv4_valid_netmask(netmask);
\end{verbatim}


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

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

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_is_unicast(uint32_t address);
\end{verbatim}

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

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

%\subsubsection*{Errors}

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



\subsection{pico$\_$ipv4$\_$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_ip4 *pico_ipv4_source_find(struct pico_ip4 *dst);
\end{verbatim}

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

\subsubsection*{Return value}
On success, this call returns the source IP as \texttt{struct pico$\_$ip4}.
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_ipv4_source_find(dst);
\end{verbatim}




\subsection{pico$\_$ipv4$\_$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_ipv4_link_add(struct pico_device *dev, struct pico_ip4 address,
struct pico_ip4 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$\_$ip4}.
\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_ipv4_link_add(dev, address, netmask);
\end{verbatim}



\subsection{pico$\_$ipv4$\_$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_ipv4_link_del(struct pico_device *dev, struct pico_ip4 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$\_$ip4}.
\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$\_$ENXIO} - no such device or address
\end{itemize}

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



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

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

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

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the internet host address as \texttt{struct pico$\_$ip4}.
\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_ipv4_link_find(address);
\end{verbatim}



\subsection{pico$\_$ipv4$\_$nat$\_$enable}

\subsubsection*{Description}
This function enables NAT functionality on the passed IPv4 link.
Forwarded packets from an internal network will have the public IP address from the passed link
and a translated port number for transmission on the external network.
Usual operation requires at least one additional link for the internal network,
which is used as a gateway for the internal hosts.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_nat_enable(struct pico_ipv4_link *link)
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{link} - Pointer to a link \texttt{pico$\_$ipv4$\_$link}.
\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_ipv4_nat_enable(&external_link);
\end{verbatim}



\subsection{pico$\_$ipv4$\_$nat$\_$disable}

\subsubsection*{Description}
Disables the NAT functionality.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_nat_disable(void);
\end{verbatim}

%\subsubsection*{Parameters}

\subsubsection*{Return value}
Always returns 0.

%\subsubsection*{Errors}
%\subsubsection*{Example}


\subsection{pico$\_$ipv4$\_$port$\_$forward}

\subsubsection*{Description}
This function adds or deletes a rule in the IP forwarding table. Internally in the stack,
a one-direction NAT entry will be made.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_port_forward(struct pico_ip4 pub_addr, uint16_t pub_port,
struct pico_ip4 priv_addr, uint16_t priv_port, uint8_t proto,
uint8_t flag)
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{pub$\_$addr} - Public IP address, must be identical to the address of the external link.
\item \texttt{pub$\_$port} - Public port to be translated.
\item \texttt{priv$\_$addr} - Private IP address of the host on the internal network.
\item \texttt{priv$\_$port} - Private port of the host on the internal network.
\item \texttt{proto} - Protocol identifier, see supported list below.
\item \texttt{flag} - Option for function call: create \texttt{PICO$\_$IPV4$\_$FORWARD$\_$ADD} (= 1) \\
or delete \texttt{PICO$\_$IPV4$\_$FORWARD$\_$DEL} (= 0).
\end{itemize}

\subsubsection*{Protocol list}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$PROTO$\_$ICMP4}
\item \texttt{PICO$\_$PROTO$\_$TCP}
\item \texttt{PICO$\_$PROTO$\_$UDP}
\end{itemize}

\subsubsection*{Return value}
On success, this call 0 after a successful entry of the forward rule.
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$\_$EAGAIN} - not successful, try again
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
ret = pico_ipv4_port_forward(ext_link_addr, ext_port, host_addr,
host_port, PICO_PROTO_UDP, 1);
\end{verbatim}



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

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

If both \texttt{address} and \texttt{netmask} are zeroed, the call assumes the meaning of adding a default gateway.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_ipv4_route_add(struct pico_ip4 address, struct pico_ip4 netmask,
struct pico_ip4 gateway, int metric, struct pico_ipv4_link *link);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the destination internet host address as \texttt{struct pico$\_$ip4}.
\item \texttt{netmask} - Netmask of the address.
\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 not 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_ipv4_route_add(dst, netmask, gateway, metric, link);
\end{verbatim}



\subsection{pico$\_$ipv4$\_$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_ipv4_route_del(struct pico_ip4 address, struct pico_ip4 netmask, int metric);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{address} - Pointer to the destination internet host address as struct \texttt{pico$\_$ip4}.
\item \texttt{netmask} - Netmask of the address.
\item \texttt{metric} - Metric of the route.
\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_ipv4_route_del(dst, netmask, metric);
\end{verbatim}



\subsection{pico$\_$ipv4$\_$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_ip4 pico_ipv4_route_get_gateway(struct pico_ip4 *addr)
\end{verbatim}

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

\subsubsection*{Return value}
On success the gateway address is returned -- or \texttt{0.0.0.0} if no gateway is needed (and \texttt{pico$\_$err} is unchanged).
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_ip4 pico_ipv4_route_get_gateway(&dest_addr)
\end{verbatim}


\subsection{pico$\_$icmp4$\_$ping}

\subsubsection*{Description}
This function sends out a number of ping echo requests and checks if the replies are received correctly.
The information from the replies is passed to the callback function after a successful reception.
If a timeout expires before a reply is received, the callback is called with the error condition.

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_icmp4_ping(char *dst, int count, int interval, int timeout, int size,
void (*cb)(struct pico_icmp4_stats *));
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{dst} - Pointer to the destination internet host address as text string
\item \texttt{count} - Number of pings going to be send
\item \texttt{interval} - Time between two transmissions (in ms)
\item \texttt{timeout} - Timeout period untill reply received (in ms)
\item \texttt{size} - Size of data buffer in bytes
\item \texttt{cb} - Callback for ICMP ping
\end{itemize}

\subsubsection*{Data structure \texttt{struct pico$\_$icmp4$\_$stats}}
\begin{verbatim}
struct pico_icmp4_stats
{
  struct pico_ip4 dst;
  unsigned long size;
  unsigned long seq;
  unsigned long time;
  unsigned long ttl;
  int err;
};
\end{verbatim}
With \textbf{err} values:
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$PING$\_$ERR$\_$REPLIED} (value 0)
\item \texttt{PICO$\_$PING$\_$ERR$\_$TIMEOUT} (value 1)
\item \texttt{PICO$\_$PING$\_$ERR$\_$UNREACH} (value 2)
\item \texttt{PICO$\_$PING$\_$ERR$\_$PENDING} (value 0xFFFF)
\end{itemize}

\subsubsection*{Return value}
On success, this call returns a positive number, which is the ID of the ping operation just started.
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
\end{itemize}

\subsubsection*{Example}
\begin{verbatim}
id = pico_icmp4_ping(dst_addr, 30, 10, 100, 1000, callback);
\end{verbatim}


\subsection{pico$\_$icmp4$\_$ping$\_$abort}

\subsubsection*{Description}
This function aborts an ongoing ping operation that has previously started using pico$\_$icmp4$\_$ping().

\subsubsection*{Function prototype}
\begin{verbatim}
int pico_icmp4_ping_abort(int id);
\end{verbatim}

\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
    \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.
\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_icmp4_ping_abort(id);
\end{verbatim}