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