kv_create_key_from_uri()

#include <kvstore.h>

kv_error_t 
kv_create_key_from_uri(kv_store_t *store,
                       kv_key_t **key,
                       const char *uri) 

Creates a key in the key/value store based on a URI. To release the resources used by this structure, use kv_release_key().

This function differs from kv_create_key_from_uri_copy() in that it does not copy the contents of the URI string passed to the function. Therefore, the URI strings should not be released or modified until the kv_key_t structure created by this function is released.

The key path string format used here is designed to work with URIs and URLs. It is intended to be used as a general purpose string identifier. The key path components are separated by slash (/) delimiters. A special slash-hyphen-slash delimiter (/-/) is used to separate the major and minor paths. Characters that are not allowed in a URI path are encoded using URI syntax (%XX where XX are hexadecimal digits). The string always begins with a leading slash to prevent it from begin treated as a URI relative path. Some examples are below.

• /SingleComponentMajorPath

• /MajorPathPart1/MajorPathPart2/-/MinorPathPart1/MinorPathPart2

• /HasEncodedSlash:%2F,Zero:%00,AndSpace:%20

Example 1 demonstrates the simplest possible path. Note that a leading slash is always necessary.

Example 2 demonstrates the use of the /-/ separator between the major and minor paths. If a key happens to have a path component that is nothing but a hyphen, to distinguish it from that delimiter it is encoded as %2D. For example: /major/%2d/path/-/minor/%2d/path.

Example 3 demonstrates encoding of characters that are not allowed in a path component. For URI compatibility, characters that are encoded are the ASCII space and other Unicode separators, the ASCII and Unicode control characters, and the following 15 ASCII characters: (" # % / < > ? [ \ ] ^ ` { | }). The hyphen (-) is also encoded when it is the only character in the path component, as described above.

Note that although any Unicode character may be used in a key path component, in practice it may be problematic to include control characters because web user agents, proxies, and so forth, may not be tolerant of all characters. Although it will be encoded, embedding a slash in a path component may also be problematic. It is the responsibility of the application to use characters that are compatible with other software that processes the URI.

Parameters

• store

  The store parameter is the handle to the store in which the key is used. The store handle is obtained using kv_open_store().

• key

  The key parameter references memory into which a pointer to the allocated key is copied.

• uri

  The uri parameter is the full key path, both major and minor components, described as a string. See the description at the beginning of this page for how that string should be formatted.

  Note that the string used here is not copied. You must not release or modify this memory until the structure in which it is used is released.

See Also

• Key/Value Pair Management Functions