namecache.rst (3609B)
1 2 .. index:: 3 single: GNS; name cache 4 double: subsystem; NAMECACHE 5 6 .. _GNS-Namecache-Dev: 7 8 NAMECACHE 9 ========= 10 11 The NAMECACHE API consists of five simple functions. First, there is 12 ``GNUNET_NAMECACHE_connect`` to connect to the NAMECACHE service. This 13 returns the handle required for all other operations on the NAMECACHE. 14 Using ``GNUNET_NAMECACHE_block_cache`` clients can insert a block into 15 the cache. ``GNUNET_NAMECACHE_lookup_block`` can be used to lookup 16 blocks that were stored in the NAMECACHE. Both operations can be 17 canceled using ``GNUNET_NAMECACHE_cancel``. Note that canceling a 18 ``GNUNET_NAMECACHE_block_cache`` operation can result in the block being 19 stored in the NAMECACHE --- or not. Cancellation primarily ensures that 20 the continuation function with the result of the operation will no 21 longer be invoked. Finally, ``GNUNET_NAMECACHE_disconnect`` closes the 22 connection to the NAMECACHE. 23 24 The maximum size of a block that can be stored in the NAMECACHE is 25 ``GNUNET_NAMECACHE_MAX_VALUE_SIZE``, which is defined to be 63 kB. 26 27 .. _The-NAMECACHE-Client_002dService-Protocol: 28 29 The NAMECACHE Client-Service Protocol 30 ------------------------------------- 31 32 All messages in the NAMECACHE IPC protocol start with the 33 ``struct GNUNET_NAMECACHE_Header`` which adds a request ID (32-bit 34 integer) to the standard message header. The request ID is used to match 35 requests with the respective responses from the NAMECACHE, as they are 36 allowed to happen out-of-order. 37 38 .. _Lookup: 39 40 Lookup 41 ^^^^^^ 42 43 The ``struct LookupBlockMessage`` is used to lookup a block stored in 44 the cache. It contains the query hash. The NAMECACHE always responds 45 with a ``struct LookupBlockResponseMessage``. If the NAMECACHE has no 46 response, it sets the expiration time in the response to zero. 47 Otherwise, the response is expected to contain the expiration time, the 48 ECDSA signature, the derived key and the (variable-size) encrypted data 49 of the block. 50 51 .. _Store: 52 53 Store 54 ^^^^^ 55 56 The ``struct BlockCacheMessage`` is used to cache a block in the 57 NAMECACHE. It has the same structure as the 58 ``struct LookupBlockResponseMessage``. The service responds with a 59 ``struct BlockCacheResponseMessage`` which contains the result of the 60 operation (success or failure). In the future, we might want to make it 61 possible to provide an error message as well. 62 63 .. _The-NAMECACHE-Plugin-API: 64 65 The NAMECACHE Plugin API 66 ------------------------ 67 68 The NAMECACHE plugin API consists of two functions, ``cache_block`` to 69 store a block in the database, and ``lookup_block`` to lookup a block in 70 the database. 71 72 .. _Lookup2: 73 74 Lookup2 75 ^^^^^^^ 76 77 The ``lookup_block`` function is expected to return at most one block to 78 the iterator, and return ``GNUNET_NO`` if there were no non-expired 79 results. If there are multiple non-expired results in the cache, the 80 lookup is supposed to return the result with the largest expiration 81 time. 82 83 .. _Store2: 84 85 Store2 86 ^^^^^^ 87 88 The ``cache_block`` function is expected to try to store the block in 89 the database, and return ``GNUNET_SYSERR`` if this was not possible for 90 any reason. Furthermore, ``cache_block`` is expected to implicitly 91 perform cache maintenance and purge blocks from the cache that have 92 expired. Note that ``cache_block`` might encounter the case where the 93 database already has another block stored under the same key. In this 94 case, the plugin must ensure that the block with the larger expiration 95 time is preserved. Obviously, this can done either by simply adding new 96 blocks and selecting for the most recent expiration time during lookup, 97 or by checking which block is more recent during the store operation. 98