Allocating adr_data_t Values

The first phase in the lifecycle of an adr_data_t is allocation. For each ADR type, there is at least one allocation routine. The arguments to an allocation routine depend on the type. In the case of mandatorily immutable types, allocation implies initialization, and their allocation routines take as arguments the value the adr_data_t is to have. Structures and arrays each have a single generic allocation routine that takes an adr_type_t* specifying the type of the structure or array. An adr_data_t is assigned values using a separate set of routines.

All allocation routines return a non-NULL adr_data_t * on success, or NULL on failure.

Allocating Strings

adr_data_t *adr_data_new_string(const char *s, lifetype_t lifetime);

Allocates a new string adr_data_t, initializing it to the NULL-terminated string pointed to by s. If s is NULL, adr_data_new_string will fail.

The value of the lifetime determines how the string s is to be used.

If lifetime is LT_FREE and adr_data_new_string fails for any reason, s will automatically be freed.

adr_data_t *adr_data_new_fstring (const char *format, ...);

Allocates a new string adr_data_t, initializing it to the string generated by calling sprintf on format and any additional arguments provided.

adr_data_t *adr_data_new_nstring (const char *s, size_t count);

Allocates a new string adr_data_t, initializing it to the first count bytes of s.

Allocating boolean

adr_data_t *adr_data_new_boolean (boolean_t b);

Allocates a new boolean adr_data_t, initializing it to the boolean value specified by b.

Allocating Numeric Types

adr_data_t *adr_data_new_integer (int i);
 
adr_data_t *adr_data_new_long (long long l);
 
adr_data_t *adr_data_new_uinteger (unsigned int ui);
 
adr_data_t *adr_data_new_ulong (unsigned long long ul);
 
adr_data_t *adr_data_new_float (float f);
 
adr_data_t *adr_data_new_double (double d);

Allocates a new integer, long, uinteger, ulong, float, or double adr_data_t, respectively, initializing it to the value of the single argument provided.

Allocating Times

adr_data_t *adr_data_new_time (long long sec, int nano);
 
adr_data_t *adr_data_new_time_ts (timespec &t);
 
adr_data_t *adr_data_new_time_now (void );

Allocates a new time adr_data_t, initializing it to the argument, if any, provided.

Allocating Opaques

adr_data_t *adr_data_new_opaque (void *buffer, size_t length, adr_lifetime_t lifetime);

Allocates a new opaque adr_data_t, initializing it to the length bytes found at buffer. How adr_data_new_opaque uses buffer depends on lifetime, which takes on the same meanings as it does when used with adr_data_new_string.

Allocating Secrets

adr_data_t *data_new_secret (const char *p);

Allocates a new secret adr_data_t, initializing it to the contents of the NULL-terminated 8-bit character array pointed to by p. The secret type is used to hold sensitive data such as passwords. Client/server implementations may take additional steps to protect the content of the character array data, for example, zeroing buffers after use.

Allocating Names

adr_data_t *adr_data_new_name (adr_name_t *name);

Allocates a new name adr_data_t, initializing it to the value of name. adr_name_t types are reference counted; the reference on name held by the caller is transferred to the resulting adr_data_t by the call to adr_data_new_name. A caller that needs to continue using name should secure an additional reference to it before calling adr_data_new_name. If adr_data_new_name fails for any reason, the caller's reference to name will be released.

Allocating Enumerations

adr_data_t *adr_data_new_enum (adr_type_t *type, int value);
 
adr_data_t *adr_data_new_enum_byname (adr_type_t *type, const char * name);

The two ways to allocate an enumeration adr_data_t both require that the adr_type_t of the enumeration be specified. The first form, adr_data_new_enum, takes a scalar value as an argument and initializes the enumeration adr_data_t to the enumerated value that was assigned (implicitly or explicitly) that scalar value. The second form, adr_data_new_enum_byname, takes a pointer to a string as an argument and initializes the enumeration adr_data_t to the enumerated value that has that name. If value does not correspond to an assigned scalar value or name does not correspond to an enumerated value name, the respective allocation routine fails.

The nature of an enumeration is that all possible values are known. Enumerated types generated by radadrgen have singleton adr_data_t values that will be returned by adr_data_new_enum and adr_data_new_enum_byname. For efficiency and to reduce the error handling that needs to be performed at runtime, these values have defined symbols that may be referenced directly.

The value of type must be an enumeration data-type.

Allocating Structures

adr_data_t *adr_data_new_struct (adr_type_t *type);

Allocates an uninitialized structure adr_data_t of type type. Any post-allocation initialization that occurs must be consistent with type.

The value of type must be a structured type.

Allocating Arrays

adr_data_t *adr_data_new_array (adr_type_t *type, int size);

Allocates an empty array adr_data_t of type type. Arrays will automatically adjust their size to fit the amount of data placed in them. The size argument can be used to initialize the size of the array if it is known beforehand.

The value of type must be an array type.