ADR Object Name Operations

libadr supports ADR object names by providing a adr_name_t type and a suite of routines for creating and inspecting them. Consumers needing to operate on object names should include the rad/adr_name.h header file:

#include <rad/adr_name.h>

This file contains definitions for all the ADR-name related functionality provided by libadr.

adr_name_t Type

The adr_name_t type represents an object name. The internal structure of an adr_name_t is private. All operations on a adr_name_t are performed using accessor functions provided by libadr. Like adr_data_t values, adr_name_t values are immutable and reference counted. The following functions are provided for handling adr_name_t reference counts:

adr_name_t *adr_name_hold(adr_data_t *name);
void adr_name_rele(adr_name_t *name);

The reference count on the adr_name_t name is incremented with adr_name_hold. For convenience, adr_name_hold returns name. Symmetrically, the reference count on the adr_name_t name is decremented with adr_name_rele. When then last reference on an adr_name_t is released, the name is freed; after calling adr_name_rele the caller must not access name in any way. Neither adr_name_hold nor adr_name_rele can fail.

Creating adr_name_t Type

ADR names are composed of a domain and a set of key/value pairs. Two functions are provided that take exactly those arguments and return an adr_name_t:

adr_name_t *adr_name_create(const char *domain, int count,
     const char * const *keys, const char * const *values);
 
adr_name_t *adr_name_vcreate(const char *domain, int count, ...);

Both forms take a domain argument, which should be a reverse-dotted domain name, and the number of key/value pairs as count. The two differ in how the key/value values are communicated. In the first form, adr_name_create, two char * arrays are provided, one for keys and the other for values, as shown in the following example.

Example 4-3 adr_name_create

const char *keys[] = { "key1", "key2" };
const char *values[] = { "value1", "value2" };
name = adr_name_create("com.example", 2, keys, values);

In the second form, adr_name_vcreate, keys and values are provided as alternating varargs. The previous example written using adr_name_vcreate would look like the following example.

Example 4-4 adr_name_vcreate

name = adr_name_vcreate("com.example", 2, "key1", "value1", "key2", "value2");

If either routine fails to create the adr_name_t, it will return NULL. All data provided to adr_name_create is copied and can subsequently be modified or freed without affecting existing adr_name_t types.

Sometimes, it is convenient to start with an existing ADR name and append additional key/value pairs to form the desired name. For this situation, libadr provides “compose” analogues to the previously described creation routines:

adr_name_t *adr_name_compose(const adr_name_t *name, int count,
     const char * const *keys, const char * const *values);
 
adr_name_t *adr_name_vcompose(const adr_name_t *name, int count, ...);
 

These two functions behave the same as their corresponding adr_create_* routine except that they take an adr_name_t instead of a domain. The resulting adr_name_t has the domain from name, and merges the key/value pairs found on name with those provided as arguments. The key/value arguments to the compose operations must not specify keys already present on name.

The adr_name_t name passed to the compose operations is not referenced by their return values. In many cases, it will be used as an argument to these functions again and again. Unlike adr_data_t allocation routines, adr_name_compose and adr_name_vcompose do not consume the caller's reference to the provided name.

Inspecting adr_name_t Type

adr_name_t types are immutable, so all operations on them are read-only. The two most common operations one needs to perform on an adr_name_t are obtaining the name's domain and obtaining the value associated with a particular key.

const char *adr_name_domain(const adr_name_t *name);
const char *adr_name_key(const adr_name_t *name, const char *key);

adr_name_domain returns name's reverse-dotted domain as a string. The string returned is part of name and therefore must not be modified or freed, and must not be accessed after the caller's reference on name has been released. Likewise, adr_name_key returns the value associated with key. The string returned by adr_name_key is subject to the same restrictions as the return value of adr_name_domain.

The two functions for comparing adr_name_t types are:

int adr_name_cmp(const adr_name_t *name1, const adr_name_t *name2);
 
boolean_t adr_name_match(const adr_name_t *name, const adr_name_t *pattern);
 

adr_name_cmp compares two adr_name_t types, returning 0 if the name1 and name2 are equal (that is, if the two names have the same names and the same keys, and each key has the same value on both names). It returns an integer less than 0 if name1 is less than name2, or and integer greater than 0 if name1 is greater than name2.

adr_name_match is a pattern-matching operation. The adr_name_t pattern is treated as a collection of attributes against which name is compared. adr_name_match returns B_TRUE if and only if the domains of name and pattern are equal, and every key present in pattern is present in name and has the same value. While normally an adr_name_t must have a domain and at least one key/value pair, pattern is permitted to have no key/value pairs and an empty domain. An empty pattern domain is considered a wildcard that matches any name domain.

String Representation

It is sometimes necessary to represent, either in human-readable output or in persistent storage, an ADR object name as a string. libadr provides routines for converting to and from a canonical string form.

adr_name_t *adr_name_fromstr(const char *str);
 
char *adr_name_tostr(const adr_name_t *name);

adr_name_fromstr takes a string and returns the corresponding adr_name_t. It behaves like an allocation routine, as described in Creating adr_name_t Type. If the string isn't a valid name, adr_name_fromstr returns NULL.

adr_name_tostr takes an adr_name_t and formats it in string form. The return value is allocated using malloc and should be freed when the caller is done with it. adr_name_tostr will return NULL if it is unable to allocate memory for its return value.