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-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
*/
60
typedef
char
as_namespace
[
AS_NAMESPACE_MAX_SIZE
];
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
*/
74
typedef
uint8_t
as_digest_value
[
AS_DIGEST_VALUE_SIZE
];
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
*/
93
as_digest_value
value
;
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
*/
107
as_integer
integer
;
108
109
/**
110
* String value.
111
*/
112
as_string
string
;
113
114
/**
115
* Raw value.
116
*/
117
as_bytes
bytes
;
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
*/
204
as_namespace
ns
;
205
206
/**
207
* The set the key belongs to.
208
*/
209
as_set
set
;
210
211
/**
212
* The key value.
213
*/
214
as_key_value
value
;
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
*/
221
as_key_value
*
valuep
;
222
223
/**
224
* Digest for the key.
225
*/
226
as_digest
digest
;
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
*/
655
as_digest
*
as_key_digest
(
as_key
* key);