-
Notifications
You must be signed in to change notification settings - Fork 17
/
chap_api_dns_c.tex
115 lines (87 loc) · 3.8 KB
/
chap_api_dns_c.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
\section{DNS client}
% Short description/overview of module functions
\subsection{pico$\_$dns$\_$client$\_$nameserver}
\subsubsection*{Description}
Function to add or remove nameservers.
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_dns_client_nameserver(struct pico_ip4 *ns, uint8_t flag);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{ns} - Pointer to the address of the name server.
\item \texttt{flag} - Flag to indicate addition or removal (see further).
\end{itemize}
\subsubsection*{Flags}
\begin{itemize}[noitemsep]
\item \texttt{PICO$\_$DNS$\_$NS$\_$ADD} - to add a nameserver
\item \texttt{PICO$\_$DNS$\_$NS$\_$DEL} - to remove a nameserver
\end{itemize}
\subsubsection*{Return value}
On success, this call returns 0 if the nameserver operation has succeeded.
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} - resource temporarily unavailable
\end{itemize}
\subsubsection*{Example}
\begin{verbatim}
ret = pico_dns_client_nameserver(&addr_ns, PICO_DNS_NS_ADD);
ret = pico_dns_client_nameserver(&addr_ns, PICO_DNS_NS_DEL);
\end{verbatim}
\subsection{pico$\_$dns$\_$client$\_$getaddr}
\subsubsection*{Description}
Function to translate an url text string to an internet host address IP.
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_dns_client_getaddr(const char *url, void (*callback)(char *ip, void *arg),
void *arg);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{url} - Pointer to text string containing url text string (e.g. www.google.com).
\item \texttt{callback} - Callback function, returning the internet host address IP and the provided argument. The returned string has to be freed by the user.
\item \texttt{arg} - Pointer to an identifier for the request. The pointer is returned in the callback.
\end{itemize}
\subsubsection*{Return value}
On success, this call returns 0 if the request is sent.
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} - resource temporarily unavailable
\end{itemize}
\subsubsection*{Example}
\begin{verbatim}
int ret = pico_dns_client_getaddr("www.google.com", cb_getaddr, &identifier);
\end{verbatim}
\subsection{pico$\_$dns$\_$client$\_$getname}
\subsubsection*{Description}
Function to translate an internet host address IP to an url text string.
\subsubsection*{Function prototype}
\begin{verbatim}
int pico_dns_client_getname(const char *ip, void (*callback)(char *url, void *arg),
void *arg);
\end{verbatim}
\subsubsection*{Parameters}
\begin{itemize}[noitemsep]
\item \texttt{ip} - Pointer to text string containing an internet host address IP (e.g. 8.8.4.4)
\item \texttt{callback} - Callback function, receiving the url text string. Note: the returned string has to be freed by the user.
\item \texttt{arg} - Pointer to an identifier for the request. The pointer is returned in the callback.
\end{itemize}
\subsubsection*{Return value}
On success, this call returns 0 if the request is sent.
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} - resource temporarily unavailable
\end{itemize}
\subsubsection*{Example}
\begin{verbatim}
int ret = pico_dns_client_getname("8.8.4.4", cb_getname, &identifier);
\end{verbatim}