SOS: Scalable Object Store  4.0.0
 All Classes Functions Variables Typedefs Enumerations Enumerator Groups Pages
SOS Keys

Macros

#define SOS_STACK_KEY_SIZE   256
 Define a SOS stack key. More...
 
#define SOS_KEY(_name_)
 
#define SOS_KEY_SZ(_name_, _sz_)
 

Functions

sos_key_t sos_key_new (size_t sz)
 Create a memory key. More...
 
void sos_key_put (sos_key_t key)
 
size_t sos_key_set (sos_key_t key, void *value, size_t sz)
 Set the value of a key. More...
 
char * sos_key_to_str (sos_key_t key, const char *fmt, const char *sep, size_t el_sz)
 Return the value of a key as a character string. More...
 
int sos_key_join (sos_key_t key, sos_attr_t join_attr,...)
 
int sos_key_split (sos_key_t key, sos_attr_t join_attr,...)
 
size_t sos_key_size (sos_key_t key)
 Return the maximum size of this key's value. More...
 
size_t sos_key_len (sos_key_t key)
 Return the length of the key's value. More...
 
unsigned char * sos_key_value (sos_key_t key)
 Return the value of a key. More...
 
void * sos_value_as_key (sos_value_t value)
 
int sos_attr_key_from_str (sos_attr_t attr, sos_key_t key, const char *str)
 Set the value of a key from a string. More...
 
const char * sos_attr_key_to_str (sos_attr_t attr, sos_key_t key)
 Return a string representation of the key value. More...
 
sos_key_t sos_attr_key_new (sos_attr_t attr, size_t size)
 Create a key based on the specified attribute or size. More...
 
int sos_attr_key_cmp (sos_attr_t attr, sos_key_t a, sos_key_t b)
 Compare two keys using the attribute index's compare function. More...
 
size_t sos_attr_key_size (sos_attr_t attr)
 Return the size of the attribute index's key. More...
 

Detailed Description

Macro Definition Documentation

#define SOS_KEY (   _name_)
Value:
struct sos_key_value_s ## _name_ { \
uint16_t len; \
unsigned char value[SOS_STACK_KEY_SIZE];\
} _name_ ## _ ## data; \
ODS_OBJ(_name_ ## _ ## key_s, &_name_ ## _ ## data, SOS_STACK_KEY_SIZE); \
sos_key_t _name_ = &_name_ ## _ ## key_s;
#define SOS_STACK_KEY_SIZE
Define a SOS stack key.
Definition: sos.h:591
#define SOS_KEY_SZ (   _name_,
  _sz_ 
)
Value:
struct sos_key_value_s ## _name_ { \
uint16_t len; \
unsigned char value[_sz_];\
} _name_ ## _ ## data; \
ODS_OBJ(_name_ ## _ ## key_s, &_name_ ## _ ## data, _sz_); \
sos_key_t _name_ = &_name_ ## _ ## key_s;
#define SOS_STACK_KEY_SIZE   256

Define a SOS stack key.

A key that is up to 256 bytes in length that is allocated on the current stack frame. If your application uses keys that are greater than this length, use the sos_key_new() function or redefine the SOS_STACK_KEY_SIZE macro and recompile your application.

Do not use the sos_obj_put() function to release keys of this type, they will be automatically destroyed when the containing function returns.

Parameters
<em>name</em>The variable name to use to refer to the key.

Function Documentation

int sos_attr_key_cmp ( sos_attr_t  attr,
sos_key_t  a,
sos_key_t  b 
)

Compare two keys using the attribute index's compare function.

Parameters
attrThe attribute handle
aThe first key
bThe second key
Returns
<0 a < b
0 a == b
>0 a > b
int sos_attr_key_from_str ( sos_attr_t  attr,
sos_key_t  key,
const char *  str 
)

Set the value of a key from a string.

Parameters
attrThe attribute handle
keyThe key
strPointer to a string
Return values
0if successful
-1if there was an error converting the string to a value
sos_key_t sos_attr_key_new ( sos_attr_t  attr,
size_t  size 
)

Create a key based on the specified attribute or size.

Create a new SOS key based on the specified attribute. If the size is specified, the attribute parameter is ignored and the key is based on the specified size.

Parameters
attrThe attribute handle
sizeThe desired key size
Return values
Apointer to the new key or NULL if there is an error
size_t sos_attr_key_size ( sos_attr_t  attr)

Return the size of the attribute index's key.

Returns the native size of the attribute index's key values. If the key value is variable size, this function returns -1. See the sos_key_len() and sos_key_size() functions for the current size of the key's value and the size of the key's buffer respectively.

Returns
The native size of the attribute index's keys in bytes
const char * sos_attr_key_to_str ( sos_attr_t  attr,
sos_key_t  key 
)

Return a string representation of the key value.

Parameters
attrThe attribute handle
keyThe key
Returns
A const char * representation of the key value.
size_t sos_key_len ( sos_key_t  key)

Return the length of the key's value.

Returns the current size of the key's value.

Parameters
keyThe key
Returns
The size of the key in bytes
sos_key_t sos_key_new ( size_t  sz)

Create a memory key.

A key is just a an object with a set of convenience routines to help with getting and setting it's value based on the key type used on an index.

A memory key is used to look up objects in the ODS. The storage for these keys comes from memory. See the sos_key_new() function for keys that are stored in the Container.

If the size of the key is known to be less than 254 bytes, the SOS_KEY() macro is useful for defining a SOS key that is allocated on the stack and is automatically destroyed when the containing function returns.

Parameters
szThe maximum size in bytes of the key value
Return values
!0ods_key_t pointer to the key
0Insufficient resources
size_t sos_key_set ( sos_key_t  key,
void *  value,
size_t  sz 
)

Set the value of a key.

Sets the value of the key to 'value'. The value parameter is of type void* to make it convenient to use values of arbitrary types. The minimum of 'sz' and the maximum key length is copied. The number of bytes copied into the key is returned.

Parameters
keyThe key
valueThe value to set the key to
szThe size of value in bytes
Returns
The number of bytes copied
size_t sos_key_size ( sos_key_t  key)

Return the maximum size of this key's value.

Returns
The size in bytes of this key's value buffer.
char * sos_key_to_str ( sos_key_t  key,
const char *  fmt,
const char *  sep,
size_t  el_sz 
)

Return the value of a key as a character string.

Format a key based on the provided fmt string. See the man page for the printf() function for the format of this string. The el_sz parameter indicates the size of each component of the key. The sep parameter is placed between each component in the formatted output.

For example, to format the key as hex bytes:

char *hex_str = sos_key_to_str(key, "%02X", ":", 1);
printf("%s\n", hex_str);

The returned string should be freed with the free() function when bo long needed.

Parameters
keyThe key handle
Return values
Thestring
unsigned char * sos_key_value ( sos_key_t  key)

Return the value of a key.

Parameters
keyThe key
Returns
Pointer to the value of the key