diff options
Diffstat (limited to 'doc/gnunet-c-tutorial.tex')
-rw-r--r-- | doc/gnunet-c-tutorial.tex | 123 |
1 files changed, 122 insertions, 1 deletions
diff --git a/doc/gnunet-c-tutorial.tex b/doc/gnunet-c-tutorial.tex index 7c0680d73..ccd2afb8f 100644 --- a/doc/gnunet-c-tutorial.tex +++ b/doc/gnunet-c-tutorial.tex | |||
@@ -978,7 +978,6 @@ in the {\tt gnunet\_server\_lib.h} header. | |||
978 | \exercise{Change the service respond to the request from your | 978 | \exercise{Change the service respond to the request from your |
979 | client. Make sure you handle malformed messages in both directions.} | 979 | client. Make sure you handle malformed messages in both directions.} |
980 | 980 | ||
981 | |||
982 | \section{Interacting directly with other Peers using the CORE Service} | 981 | \section{Interacting directly with other Peers using the CORE Service} |
983 | 982 | ||
984 | One of the most important services in GNUnet is the \texttt{CORE} service | 983 | One of the most important services in GNUnet is the \texttt{CORE} service |
@@ -1113,6 +1112,128 @@ disconnects (void *cls, | |||
1113 | 1112 | ||
1114 | \exercise{Fix your service to handle peer disconnects.} | 1113 | \exercise{Fix your service to handle peer disconnects.} |
1115 | 1114 | ||
1115 | \section{Storing peer-specific data using the PEERSTORE service} | ||
1116 | |||
1117 | GNUnet's PEERSTORE service offers persistent peer-specific arbitrary data storage. | ||
1118 | Other GNUnet services can use the PEERSTORE API to store, retrieve and monitor data records. | ||
1119 | Each data record stored with PEERSTORE contains the following fields: | ||
1120 | |||
1121 | \begin{itemize} | ||
1122 | \itemsep0em | ||
1123 | \item subsystem: Name of the subsystem responsible for the record. | ||
1124 | \item peerid: Identity of the peer this record is related to. | ||
1125 | \item key: a key string identifying the record. | ||
1126 | \item value: binary record value. | ||
1127 | \item expiry: record expiry date. | ||
1128 | \end{itemize} | ||
1129 | |||
1130 | The first step is to start a connection to the PEERSTORE service: | ||
1131 | \begin{lstlisting} | ||
1132 | #include "gnunet_peerstore_service.h" | ||
1133 | |||
1134 | peerstore_handle = GNUNET_PEERSTORE_connect (cfg); | ||
1135 | \end{lstlisting} | ||
1136 | The service handle \lstinline|peerstore_handle| will be needed for all subsequent | ||
1137 | PEERSTORE operations. | ||
1138 | |||
1139 | \subsection{Storing records} | ||
1140 | |||
1141 | To store a new record, use the following function: | ||
1142 | \begin{lstlisting} | ||
1143 | struct GNUNET_PEERSTORE_StoreContext * | ||
1144 | GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, | ||
1145 | const char *sub_system, | ||
1146 | const struct GNUNET_PeerIdentity *peer, | ||
1147 | const char *key, | ||
1148 | const void *value, | ||
1149 | size_t size, | ||
1150 | struct GNUNET_TIME_Absolute expiry, | ||
1151 | enum GNUNET_PEERSTORE_StoreOption options, | ||
1152 | GNUNET_PEERSTORE_Continuation cont, | ||
1153 | void *cont_cls); | ||
1154 | \end{lstlisting} | ||
1155 | |||
1156 | The \lstinline|options| parameter can either be \lstinline|GNUNET_PEERSTORE_STOREOPTION_MULTIPLE| | ||
1157 | which means that multiple values can be stored under the same key combination (subsystem, peerid, key), | ||
1158 | or \lstinline|GNUNET_PEERSTORE_STOREOPTION_REPLACE| which means that PEERSTORE will replace any | ||
1159 | existing values under the given key combination (subsystem, peerid, key) with the new given value. | ||
1160 | |||
1161 | The continuation function \lstinline|cont| will be called after the store request is successfully | ||
1162 | sent to the PEERSTORE service. This does not guarantee that the record is successfully stored, only | ||
1163 | that it was received by the service. | ||
1164 | |||
1165 | The \lstinline|GNUNET_PEERSTORE_store| function returns a handle to the store operation. This handle | ||
1166 | can be used to cancel the store operation only before the continuation function is called: | ||
1167 | \begin{lstlisting} | ||
1168 | void | ||
1169 | GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); | ||
1170 | \end{lstlisting} | ||
1171 | |||
1172 | \subsection{Retrieving records} | ||
1173 | |||
1174 | To retrieve stored records, use the following function: | ||
1175 | \begin{lstlisting} | ||
1176 | struct GNUNET_PEERSTORE_IterateContext * | ||
1177 | GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h, | ||
1178 | const char *sub_system, | ||
1179 | const struct GNUNET_PeerIdentity *peer, | ||
1180 | const char *key, | ||
1181 | struct GNUNET_TIME_Relative timeout, | ||
1182 | GNUNET_PEERSTORE_Processor callback, | ||
1183 | void *callback_cls); | ||
1184 | \end{lstlisting} | ||
1185 | The values of \lstinline|peer| and \lstinline|key| can be \lstinline|NULL|. This allows the | ||
1186 | iteration over values stored under any of the following key combinations: | ||
1187 | \begin{itemize} | ||
1188 | \itemsep0em | ||
1189 | \item (subsystem) | ||
1190 | \item (subsystem, peerid) | ||
1191 | \item (subsystem, key) | ||
1192 | \item (subsystem, peerid, key) | ||
1193 | \end{itemize} | ||
1194 | |||
1195 | The \lstinline|callback| function will be called once with each retrieved record and once | ||
1196 | more with a \lstinline|NULL| record to signify end of list. | ||
1197 | |||
1198 | The \lstinline|GNUNET_PEERSTORE_iterate| function returns a handle to the iterate operation. This | ||
1199 | handle can be used to cancel the iterate operation only before the callback function is called with | ||
1200 | a \lstinline|NULL| record. | ||
1201 | |||
1202 | \subsection{Monitoring records} | ||
1203 | |||
1204 | PEERSTORE offers the functionality of monitoring for new records stored under a specific key | ||
1205 | combination (subsystem, peerid, key). To start the monitoring, use the following function: | ||
1206 | \begin{lstlisting} | ||
1207 | struct GNUNET_PEERSTORE_WatchContext * | ||
1208 | GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h, | ||
1209 | const char *sub_system, | ||
1210 | const struct GNUNET_PeerIdentity *peer, | ||
1211 | const char *key, | ||
1212 | GNUNET_PEERSTORE_Processor callback, | ||
1213 | void *callback_cls); | ||
1214 | \end{lstlisting} | ||
1215 | |||
1216 | Whenever a new record is stored under the given key combination, the \lstinline|callback| function | ||
1217 | will be called with this new record. This will continue until the connection to the PEERSTORE service | ||
1218 | is broken or the watch operation is cancelled: | ||
1219 | \begin{lstlisting} | ||
1220 | void | ||
1221 | GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc); | ||
1222 | \end{lstlisting} | ||
1223 | |||
1224 | \subsection{Disconnecting from PEERSTORE} | ||
1225 | |||
1226 | When the connection to the PEERSTORE service is no longer needed, disconnect using the following | ||
1227 | function: | ||
1228 | \begin{lstlisting} | ||
1229 | void | ||
1230 | GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first); | ||
1231 | \end{lstlisting} | ||
1232 | |||
1233 | If the \lstinline|sync_first| flag is set to \lstinline|GNUNET_YES|, the API will delay the | ||
1234 | disconnection until all store requests are received by the PEERSTORE service. Otherwise, | ||
1235 | it will disconnect immediately. | ||
1236 | |||
1116 | \section{Using the DHT} | 1237 | \section{Using the DHT} |
1117 | The DHT allows to store data so other peers in the P2P network can | 1238 | The DHT allows to store data so other peers in the P2P network can |
1118 | access it and retrieve data stored by any peers in the network. | 1239 | access it and retrieve data stored by any peers in the network. |