All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
as_key.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2014 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 #pragma once
18 
19 #include <aerospike/as_integer.h>
20 #include <aerospike/as_string.h>
21 #include <aerospike/as_bytes.h>
22 
23 #include <stdbool.h>
24 #include <stdint.h>
25 
26 /******************************************************************************
27  * MACROS
28  *****************************************************************************/
29 
30 /**
31  * The size of as_digest.value
32  *
33  * @ingroup as_key_object
34  */
35 #define AS_DIGEST_VALUE_SIZE 20
36 
37 /**
38  * The maxium size of as_namespace.
39  *
40  * @ingroup as_key_object
41  */
42 #define AS_NAMESPACE_MAX_SIZE 32
43 
44 /**
45  * The maxium size of as_set.
46  *
47  * @ingroup as_key_object
48  */
49 #define AS_SET_MAX_SIZE 64
50 
51 /******************************************************************************
52  * TYPES
53  *****************************************************************************/
54 
55 /**
56  * Namespace Name
57  *
58  * @ingroup as_key_object
59  */
61 
62 /**
63  * Set Name
64  *
65  * @ingroup as_key_object
66  */
67 typedef char as_set[AS_SET_MAX_SIZE];
68 
69 /**
70  * Digest value
71  *
72  * @ingroup as_key_object
73  */
75 
76 /**
77  * The digest is the value used to locate a record based on the
78  * set and digest of the record. The digest is calculated using RIPEMD-160.
79  * Keys for digests can be either a string or integer.
80  *
81  * @ingroup as_key_object
82  */
83 typedef struct as_digest_s {
84 
85  /**
86  * Indicates whether the digest was calculated.
87  */
88  bool init;
89 
90  /**
91  * The digest value.
92  */
94 
95 } as_digest;
96 
97 /**
98  * Key value
99  *
100  * @ingroup as_key_object
101  */
102 typedef union as_key_value_u {
103 
104  /**
105  * Integer value.
106  */
108 
109  /**
110  * String value.
111  */
113 
114  /**
115  * Raw value.
116  */
118 
119 } as_key_value;
120 
121 
122 /**
123  * A key is used for locating records in the database.
124  *
125  * ## Initialization
126  *
127  * A key can either be stack or heap allocated. Use one of the following
128  * functions to properly initialize an as_key.
129  *
130  * Each function requires a namespace, set and key value. The set can be
131  * and empty string.
132  *
133  * For stack allocated as_key, you should you the following functions to
134  * initialize the value:
135  *
136  * - as_key_init() - Initialize the key with a string value.
137  * - as_key_init_int64() - Initialize the key with an int64_t value.
138  * - as_key_init_str() - Same as as_key_init().
139  * - as_key_init_raw() - Initialize the key with byte array.
140  * - as_key_init_value() - Initialize the key with an as_key_value.
141  *
142  * ~~~~~~~~~~{.c}
143  * as_key key;
144  * as_key_init(&key, "ns", "set", "key");
145  * ~~~~~~~~~~
146  *
147  * For heap allocated as_key, you should use the following functions
148  * to allocate and initialize the value on the heap.
149  *
150  * - as_key_new() - Initialize the key with a string value.
151  * - as_key_new_int64() - Initialize the key with an int64_t value.
152  * - as_key_new_str() - Same as as_key_new().
153  * - as_key_new_raw() - Initialize the key with byte array.
154  * - as_key_new_value() - Initialize the key with an as_key_value.
155  *
156  * ~~~~~~~~~~{.c}
157  * as_key * key = as_key_new("ns", "set", "key");
158  * ~~~~~~~~~~
159  *
160  * ## Destruction
161  *
162  * When you no longer require an instance of as_key, you should release the
163  * key and associated resources via as_key_destroy().
164  *
165  * ~~~~~~~~~~{.c}
166  * as_key_destroy(key);
167  * ~~~~~~~~~~
168  *
169  * This function should be used on both stack and heap allocated keys.
170  *
171  * ## Operations
172  *
173  * The following are operations which require a key.
174  *
175  * - aerospike_key_get()
176  * - aerospike_key_select()
177  * - aerospike_key_exists()
178  * - aerospike_key_put()
179  * - aerospike_key_operate()
180  * - aerospike_key_remove()
181  * - aerospike_key_apply()
182  *
183  * ## Digest
184  *
185  * Each operation that requires a key, internally generates a digest for the
186  * key. The digest is a hash value used to locate a record in the cluster. Once
187  * calculated, the digest will be reused.
188  *
189  * To get the digest value of a key, use as_key_digest().
190  *
191  * @ingroup client_objects
192  */
193 typedef struct as_key_s {
194 
195  /**
196  * @private
197  * If true, then as_key_destroy() will free this instance.
198  */
199  bool _free;
200 
201  /**
202  * The namespace the key belongs to.
203  */
205 
206  /**
207  * The set the key belongs to.
208  */
210 
211  /**
212  * The key value.
213  */
215 
216  /**
217  * The key value pointer.
218  * If NULL, then there is no value.
219  * It can point to as_key.value or a different value.
220  */
222 
223  /**
224  * Digest for the key.
225  */
227 
228 } as_key;
229 
230 /******************************************************************************
231  * as_key FUNCTIONS
232  *****************************************************************************/
233 
234 /**
235  * Initialize a stack allocated as_key to a NULL-terminated string value.
236  *
237  * ~~~~~~~~~~{.c}
238  * as_key key;
239  * as_key_init(&key, "ns", "set", "key");
240  * ~~~~~~~~~~
241  *
242  * Use as_key_destroy() to release resources allocated to as_key via
243  * this function.
244  *
245  * @param key The key to initialize.
246  * @param ns The namespace for the key.
247  * @param set The set for the key.
248  * @param value The key's value.
249  *
250  * @return The initialized as_key on success. Otherwise NULL.
251  *
252  * @relates as_key
253  * @ingroup as_key_object
254  */
255 as_key * as_key_init(as_key * key, const as_namespace ns, const as_set set, const char * value);
256 
257 /**
258  * Initialize a stack allocated as_key to a int64_t value.
259  *
260  * ~~~~~~~~~~{.c}
261  * as_key key;
262  * as_key_init_int64(&key, "ns", "set", 123);
263  * ~~~~~~~~~~
264  *
265  * Use as_key_destroy() to release resources allocated to as_key.
266  *
267  * @param key The key to initialize.
268  * @param ns The namespace for the key.
269  * @param set The set for the key.
270  * @param value The key's value.
271  *
272  * @return The initialized as_key on success. Otherwise NULL.
273  *
274  * @relates as_key
275  * @ingroup as_key_object
276  */
277 as_key * as_key_init_int64(as_key * key, const as_namespace ns, const as_set set, int64_t value);
278 
279 /**
280  * Initialize a stack allocated as_key to a NULL-terminated string value.
281  *
282  * ~~~~~~~~~~{.c}
283  * as_key key;
284  * as_key_init_strp(&key, "ns", "set", stdup("key"), true);
285  * ~~~~~~~~~~
286  *
287  * Use as_key_destroy() to release resources allocated to as_key.
288  *
289  * @param key The key to initialize.
290  * @param ns The namespace for the key.
291  * @param set The set for the key.
292  * @param value The key's value.
293  * @param free If true, then the key's value can be freed when the key is destroyed.
294  *
295  * @return The initialized as_key on success. Otherwise NULL.
296  *
297  * @relates as_key
298  * @ingroup as_key_object
299  */
300 as_key * as_key_init_strp(as_key * key, const as_namespace ns, const as_set set, const char * value, bool free);
301 
302 /**
303  * Initialize a stack allocated as_key to a NULL-terminated string value.
304  *
305  * ~~~~~~~~~~{.c}
306  * as_key key;
307  * as_key_init_str(&key, "ns", "set", "key");
308  * ~~~~~~~~~~
309  *
310  * Use as_key_destroy() to release resources allocated to as_key.
311  *
312  * @param key The key to initialize.
313  * @param ns The namespace for the key.
314  * @param set The set for the key.
315  * @param value The key's value. Must last for the lifetime of the key.
316  *
317  * @return The initialized as_key on success. Otherwise NULL.
318  *
319  * @relates as_key
320  * @ingroup as_key_object
321  */
322 static inline as_key * as_key_init_str(as_key * key, const as_namespace ns, const as_set set, const char * value)
323 {
324  return as_key_init_strp(key, ns, set, value, false);
325 }
326 
327 /**
328  * Initialize a stack allocated as_key to bytes array.
329  *
330  * ~~~~~~~~~~{.c}
331  * uint8_t * rgb = (uint8_t *) malloc(3);
332  * rgb[0] = 255;
333  * rgb[1] = 255;
334  * rgb[3] = 255;
335  *
336  * as_key key;
337  * as_key_init_rawp(&key, "ns", "set", rgb, 3, true);
338  * ~~~~~~~~~~
339  *
340  * Use as_key_destroy() to release resources allocated to as_key.
341  *
342  * @param key The key to initialize.
343  * @param ns The namespace for the key.
344  * @param set The set for the key.
345  * @param value The key's value.
346  * @param size The number of bytes in value.
347  * @param free If true, then the key's value can be freed when the key is destroyed.
348  *
349  * @return The initialized as_key on success. Otherwise NULL.
350  *
351  * @relates as_key
352  * @ingroup as_key_object
353  */
354 as_key * as_key_init_rawp(as_key * key, const as_namespace ns, const as_set set, const uint8_t * value, uint32_t size, bool free);
355 
356 /**
357  * Initialize a stack allocated as_key to bytes array.
358  *
359  * ~~~~~~~~~~{.c}
360  * uint8_t rgb[3] = {254,254,120};
361  *
362  * as_key key;
363  * as_key_init_raw(&key, "ns", "set", rgb, 3);
364  * ~~~~~~~~~~
365  *
366  * Use as_key_destroy() to release resources allocated to as_key.
367  *
368  * @param key The key to initialize.
369  * @param ns The namespace for the key.
370  * @param set The set for the key.
371  * @param value The key's value.
372  * @param size The number of bytes in value. Must last for the lifetime of the key.
373  *
374  * @return The initialized as_key on success. Otherwise NULL.
375  *
376  * @relates as_key
377  * @ingroup as_key_object
378  */
379 static inline as_key * as_key_init_raw(as_key * key, const as_namespace ns, const as_set set, const uint8_t * value, uint32_t size)
380 {
381  return as_key_init_rawp(key, ns, set, value, size, false);
382 }
383 
384 /**
385  * Initialize a stack allocated as_key with a digest.
386  *
387  * ~~~~~~~~~~{.c}
388  * as_digest_value digest = {0};
389  *
390  * as_key key;
391  * as_key_init_digest(&key, "ns", "set", digest);
392  * ~~~~~~~~~~
393  *
394  * Use as_key_destroy() to release resources allocated to as_key.
395  *
396  * @param key The key to initialize.
397  * @param ns The namespace for the key.
398  * @param set The set for the key.
399  * @param digest The digest for the key.
400  *
401  * @return The initialized as_key on success. Otherwise NULL.
402  *
403  * @relates as_key
404  * @ingroup as_key_object
405  */
406 as_key * as_key_init_digest(as_key * key, const as_namespace ns, const as_set set, const as_digest_value digest);
407 
408 /**
409  * Initialize a stack allocated as_key to an as_key_value.
410  *
411  * ~~~~~~~~~~{.c}
412  * as_string str;
413  * as_string_init(&str, "abc", false);
414  *
415  * as_key key;
416  * as_key_init_value(&key, "ns", "set", (as_key_value *) str);
417  * ~~~~~~~~~~
418  *
419  * Use as_key_destroy() to release resources allocated to as_key.
420  *
421  * @param key The key to initialize.
422  * @param ns The namespace for the key.
423  * @param set The set for the key.
424  * @param value The key's value.
425  *
426  * @return The initialized as_key on success. Otherwise NULL.
427  *
428  * @relates as_key
429  * @ingroup as_key_object
430  */
431 as_key * as_key_init_value(as_key * key, const as_namespace ns, const as_set set, const as_key_value * value);
432 
433 
434 /**
435  * Creates and initializes a heap allocated as_key to a NULL-terminated string value.
436  *
437  * ~~~~~~~~~~{.c}
438  * as_key * key = as_key_new("ns", "set", "key");
439  * ~~~~~~~~~~
440  *
441  * Use as_key_destroy() to release resources allocated to as_key via
442  * this function.
443  *
444  * @param ns The namespace for the key.
445  * @param set The set for the key.
446  * @param value The key's value.
447  *
448  * @return A new as_key on success. Otherwise NULL.
449  *
450  * @relates as_key
451  * @ingroup as_key_object
452  */
453 as_key * as_key_new(const as_namespace ns, const as_set set, const char * value);
454 
455 /**
456  * Initialize a stack allocated as_key to a int64_t value.
457  *
458  * ~~~~~~~~~~{.c}
459  * as_key * key = as_key_new_int64("ns", "set", 123);
460  * ~~~~~~~~~~
461  *
462  * Use as_key_destroy() to release resources allocated to as_key via
463  * this function.
464  *
465  * @param ns The namespace for the key.
466  * @param set The set for the key.
467  * @param value The key's value.
468  *
469  * @return A new as_key on success. Otherwise NULL.
470  *
471  * @relates as_key
472  * @ingroup as_key_object
473  */
474 as_key * as_key_new_int64(const as_namespace ns, const as_set set, int64_t value);
475 
476 /**
477  * Creates and initializes a heap allocated as_key to a NULL-terminated string value.
478  *
479  * ~~~~~~~~~~{.c}
480  * as_key * key = as_key_new_strp("ns", "set", strdup("key"), true);
481  * ~~~~~~~~~~
482  *
483  * Use as_key_destroy() to release resources allocated to as_key via
484  * this function.
485  *
486  * @param ns The namespace for the key.
487  * @param set The set for the key.
488  * @param value The key's value.
489  * @param free If true, then the key's value can be freed when the key is destroyed.
490  *
491  * @return A new as_key on success. Otherwise NULL.
492  *
493  * @relates as_key
494  * @ingroup as_key_object
495  */
496 as_key * as_key_new_strp(const as_namespace ns, const as_set set, const char * value, bool free);
497 
498 /**
499  * Creates and initializes a heap allocated as_key to a NULL-terminated string value.
500  *
501  * ~~~~~~~~~~{.c}
502  * as_key * key = as_key_new_str("ns", "set", "key");
503  * ~~~~~~~~~~
504  *
505  * Use as_key_destroy() to release resources allocated to as_key via
506  * this function.
507  *
508  * @param ns The namespace for the key.
509  * @param set The set for the key.
510  * @param value The key's value. Must last for the lifetime of the key.
511  *
512  * @return A new as_key on success. Otherwise NULL.
513  *
514  * @relates as_key
515  * @ingroup as_key_object
516  */
517 static inline as_key * as_key_new_str(const as_namespace ns, const as_set set, const char * value)
518 {
519  return as_key_new_strp(ns, set, value, false);
520 }
521 
522 /**
523  * Initialize a stack allocated as_key to a byte array.
524  *
525  * ~~~~~~~~~~{.c}
526  * uint8_t * rgb = (uint8_t *) malloc(3);
527  * rgb[0] = 255;
528  * rgb[1] = 255;
529  * rgb[3] = 255;
530  *
531  * as_key * key = as_key_new_rawp("ns", "set", rgb, 3, true);
532  * ~~~~~~~~~~
533  *
534  * Use as_key_destroy() to release resources allocated to as_key via
535  * this function.
536  *
537  * @param ns The namespace for the key.
538  * @param set The set for the key.
539  * @param value The key's value.
540  * @param size The number of bytes in the value.
541  * @param free If true, then the key's value can be freed when the key is destroyed.
542  *
543  * @return A new as_key on success. Otherwise NULL.
544  *
545  * @relates as_key
546  * @ingroup as_key_object
547  */
548 as_key * as_key_new_rawp(const as_namespace ns, const as_set set, const uint8_t * value, uint32_t size, bool free);
549 
550 /**
551  * Initialize a stack allocated as_key to a byte array.
552  *
553  * ~~~~~~~~~~{.c}
554  * uint8_t rgb[3] = {254,254,120};
555  *
556  * as_key * key = as_key_new_raw("ns", "set", rgb, 3);
557  * ~~~~~~~~~~
558  *
559  * Use as_key_destroy() to release resources allocated to as_key via
560  * this function.
561  *
562  * @param ns The namespace for the key.
563  * @param set The set for the key.
564  * @param value The key's value. Must last for the lifetime of the key.
565  * @param size The number of bytes in the value.
566  *
567  * @return A new as_key on success. Otherwise NULL.
568  *
569  * @relates as_key
570  * @ingroup as_key_object
571  */
572 static inline as_key * as_key_new_raw(const as_namespace ns, const as_set set, const uint8_t * value, uint32_t size)
573 {
574  return as_key_new_rawp(ns, set, value, size, false);
575 }
576 
577 /**
578  * Initialize a stack allocated as_key with a digest.
579  *
580  * ~~~~~~~~~~{.c}
581  * as_digest_value digest = {0};
582  *
583  * as_key * key = as_key_new_digest("ns", "set", digest);
584  * ~~~~~~~~~~
585  *
586  * Use as_key_destroy() to release resources allocated to as_key via
587  * this function.
588  *
589  * @param ns The namespace for the key.
590  * @param set The set for the key.
591  * @param digest The key's digest.
592  *
593  * @return A new as_key on success. Otherwise NULL.
594  *
595  * @relates as_key
596  * @ingroup as_key_object
597  */
598 as_key * as_key_new_digest(const as_namespace ns, const as_set set, const as_digest_value digest);
599 
600 /**
601  * Initialize a stack allocated as_key to a an as_key_value.
602  *
603  * ~~~~~~~~~~{.c}
604  * as_string str;
605  * as_string_init(&str, "abc", false);
606  *
607  * as_key * key = as_key_new_value("ns", "set", (as_key_value *) str);
608  * ~~~~~~~~~~
609  *
610  * Use as_key_destroy() to release resources allocated to as_key via
611  * this function.
612  *
613  * @param ns The namespace for the key.
614  * @param set The set for the key.
615  * @param value The key's value.
616  *
617  * @return A new as_key on success. Otherwise NULL.
618  *
619  * @relates as_key
620  * @ingroup as_key_object
621  */
622 as_key * as_key_new_value(const as_namespace ns, const as_set set, const as_key_value * value);
623 
624 /**
625  * Destory the as_key, releasing resources.
626  *
627  * ~~~~~~~~~~{.c}
628  * as_key_destroy(key);
629  * ~~~~~~~~~~
630  *
631  * @param key The as_key to destroy.
632  *
633  * @relates as_key
634  * @ingroup as_key_object
635  */
636 void as_key_destroy(as_key * key);
637 
638 /**
639  * Get the digest for the given key.
640  *
641  * The digest is computed the first time function is called. Subsequent calls
642  * will return the previously calculated value.
643  *
644  * ~~~~~~~~~~{.c}
645  * as_digest * digest = as_key_digest(key);
646  * ~~~~~~~~~~
647  *
648  * @param key The key to get the digest for.
649  *
650  * @return The digest for the key.
651  *
652  * @relates as_key
653  * @ingroup as_key_object
654  */
as_digest digest
Definition: as_key.h:226
as_key * as_key_new_int64(const as_namespace ns, const as_set set, int64_t value)
as_key * as_key_init_strp(as_key *key, const as_namespace ns, const as_set set, const char *value, bool free)
as_key * as_key_init(as_key *key, const as_namespace ns, const as_set set, const char *value)
as_key * as_key_init_int64(as_key *key, const as_namespace ns, const as_set set, int64_t value)
as_key * as_key_init_digest(as_key *key, const as_namespace ns, const as_set set, const as_digest_value digest)
static as_key * as_key_init_raw(as_key *key, const as_namespace ns, const as_set set, const uint8_t *value, uint32_t size)
Definition: as_key.h:379
as_bytes bytes
Definition: as_key.h:117
as_namespace ns
Definition: as_scan.h:328
as_string string
Definition: as_key.h:112
static as_key * as_key_new_raw(const as_namespace ns, const as_set set, const uint8_t *value, uint32_t size)
Definition: as_key.h:572
bool init
Definition: as_key.h:88
as_key_value * valuep
Definition: as_key.h:221
as_digest_value value
Definition: as_key.h:93
bool _free
Definition: as_key.h:199
as_key * as_key_init_value(as_key *key, const as_namespace ns, const as_set set, const as_key_value *value)
char as_namespace[AS_NAMESPACE_MAX_SIZE]
Definition: as_key.h:60
as_digest * as_key_digest(as_key *key)
#define AS_NAMESPACE_MAX_SIZE
Definition: as_key.h:42
as_key_value value
Definition: as_key.h:214
as_key * as_key_init_rawp(as_key *key, const as_namespace ns, const as_set set, const uint8_t *value, uint32_t size, bool free)
#define AS_DIGEST_VALUE_SIZE
Definition: as_key.h:35
static as_key * as_key_init_str(as_key *key, const as_namespace ns, const as_set set, const char *value)
Definition: as_key.h:322
as_key * as_key_new_digest(const as_namespace ns, const as_set set, const as_digest_value digest)
uint8_t as_digest_value[AS_DIGEST_VALUE_SIZE]
Definition: as_key.h:74
as_namespace ns
Definition: as_key.h:204
as_key * as_key_new(const as_namespace ns, const as_set set, const char *value)
#define AS_SET_MAX_SIZE
Definition: as_key.h:49
as_set set
Definition: as_key.h:209
as_integer integer
Definition: as_key.h:107
as_key * as_key_new_rawp(const as_namespace ns, const as_set set, const uint8_t *value, uint32_t size, bool free)
static as_key * as_key_new_str(const as_namespace ns, const as_set set, const char *value)
Definition: as_key.h:517
as_key * as_key_new_value(const as_namespace ns, const as_set set, const as_key_value *value)
as_key * as_key_new_strp(const as_namespace ns, const as_set set, const char *value, bool free)
Definition: as_key.h:193
void as_key_destroy(as_key *key)
char as_set[AS_SET_MAX_SIZE]
Definition: as_key.h:67