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