Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
as_key.h
Go to the documentation of this file.
1
/******************************************************************************
2
* Copyright 2008-2013 by Aerospike.
3
*
4
* Permission is hereby granted, free of charge, to any person obtaining a copy
5
* of this software and associated documentation files (the "Software"), to
6
* deal in the Software without restriction, including without limitation the
7
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8
* sell copies of the Software, and to permit persons to whom the Software is
9
* furnished to do so, subject to the following conditions:
10
*
11
* The above copyright notice and this permission notice shall be included in
12
* all copies or substantial portions of the Software.
13
*
14
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20
* IN THE SOFTWARE.
21
*****************************************************************************/
22
23
#pragma once
24
25
#include <
aerospike/as_integer.h
>
26
#include <
aerospike/as_string.h
>
27
#include <
aerospike/as_bytes.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
*/
66
typedef
char
as_namespace
[
AS_NAMESPACE_MAX_SIZE
];
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
*/
80
typedef
uint8_t
as_digest_value
[
AS_DIGEST_VALUE_SIZE
];
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
*/
113
as_integer
integer
;
114
115
/**
116
* String value.
117
*/
118
as_string
string
;
119
120
/**
121
* Raw value.
122
*/
123
as_bytes
bytes
;
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
*/
220
as_key_value
value
;
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
*/
227
as_key_value
*
valuep
;
228
229
/**
230
* Digest for the key.
231
*/
232
as_digest
digest
;
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
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
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
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
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
*/
661
as_digest
*
as_key_digest
(
as_key
* key);