Overview

You start with the people document, store its entities, and read their names through a query. Later pages use the same people to explain each step of that sequence.

Before you create resources, activate the core with your license token.

Example

The example follows the complete call sequence, including the release of each result.

Store people and query their names

seed_text holds this document:

TRON

449 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	3C 616765	txt "age"
008	02 24000000000000 00	i64 36
011	0F 0A 04000000 0800 0000	map leaf, size 10: @4 → @8
01B	4C 726F6C65	txt "role"
020	8C 656E67696E6565 72	txt "engineer"
029	0F 0A 1B000000 2000 0000	map leaf, size 10: @1B → @20
033	4C 6E616D65	txt "name"
038	3C 416461	txt "Ada"
03C	0F 0A 33000000 3800 0000	map leaf, size 10: @33 → @38
046	07 12 00910000 1100 0000 29000000 3C00 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @11 → @29 → @3C
058	5C 236C696E6B	txt "#link"
05E	5C 235F616461	txt "#_ada"
064	0F 0A 58000000 5E00 0000	map leaf, size 10: @58 → @5E
06E	3C 616765	txt "age"
072	02 29000000000000 00	i64 41
07B	0F 0A 6E000000 7200 0000	map leaf, size 10: @6E → @72
085	6C 6D656E746F72	txt "mentor"
08C	0F 0A 85000000 6400 0000	map leaf, size 10: @85 → @64
096	4C 726F6C65	txt "role"
09B	8C 656E67696E6565 72	txt "engineer"
0A4	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
0AE	4C 6E616D65	txt "name"
0B3	3C 426F62	txt "Bob"
0B7	0F 0A AE000000 B300 0000	map leaf, size 10: @AE → @B3
0C1	07 16 00990000 7B00 0000 8C000000 A400 0000 B7000000	map branch, size 22, depth 0 (root), slots 8, 11, 12, 15: @7B → @8C → @A4 → @B7
0D7	3C 616765	txt "age"
0DB	02 1D000000000000 00	i64 29
0E4	0F 0A D7000000 DB00 0000	map leaf, size 10: @D7 → @DB
0EE	4C 726F6C65	txt "role"
0F3	8C 64657369676E65 72	txt "designer"
0FC	0F 0A EE000000 F300 0000	map leaf, size 10: @EE → @F3
106	4C 6E616D65	txt "name"
10B	2C 4379	txt "Cy"
10E	0F 0A 06010000 0B01 0000	map leaf, size 10: @106 → @10B
118	07 12 00910000 E400 0000 FC000000 0E01 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @E4 → @FC → @10E
12A	6C 617574686F72	txt "author"
131	5C 736D6F6B65	txt "smoke"
137	0F 0A 2A010000 3101 0000	map leaf, size 10: @12A → @131
141	6C 726561736F6E	txt "reason"
148	4C 73656564	txt "seed"
14D	0F 0A 41010000 4801 0000	map leaf, size 10: @141 → @148
157	07 0E 40080000 3701 0000 4D010000	map branch, size 14, depth 0 (root), slots 6, 11: @137 → @14D
165	4C 235F7478	txt "#_tx"
16A	0F 0A 65010000 5701 0000	map leaf, size 10: @165 → @157
174	4C 235F6379	txt "#_cy"
179	0F 0A 74010000 1801 0000	map leaf, size 10: @174 → @118
183	5C 235F626F62	txt "#_bob"
189	0F 0A 83010000 C100 0000	map leaf, size 10: @183 → @C1
193	5C 235F616461	txt "#_ada"
199	0F 0A 93010000 4600 0000	map leaf, size 10: @193 → @46
1A3	07 16 88210000 6A01 0000 79010000 8901 0000 99010000	map branch, size 22, depth 0 (root), slots 3, 7, 8, 13: @16A → @179 → @189 → @199
1B9	A3010000 00000000	root → @1A3; previous: none

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

1.5 kB

stardust_db *opened = NULL;
stardust_document *seed = NULL;
stardust_document *definition = NULL;
stardust_result *seeded = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
stardust_bytes path = {(const uint8_t *)database_path, (int64_t)strlen(database_path)};
stardust_result *opening = NULL;
uint32_t status = stardust_db_open(path, NULL, &opened, &opening);
stardust_result_release(opening);
if (status == STARDUST_OK) status = stardust_parse(seed_text, STARDUST_TRON, &seed);
if (status == STARDUST_OK) status = stardust_db_merge_patch(opened, seed, NULL, NULL, &seeded);
if (status == STARDUST_OK) status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(opened, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
stardust_result_release(seeded);
stardust_document_release(seed);
stardust_db_close(opened);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

Ownership and lifetimes

Value	Lifetime	Your action
Owned result	Until you release it	Release it when you finish with it.
Borrowed value	The lifetime that its operation states	Stop using it when that lifetime ends.
Owned document	Continues after you release the handle that produced it	Release it separately from that handle.

Each operation states its ownership rule. Use that rule to find the values that you must release.

Concurrency

Calls can overlap unless an operation requires exclusive use of its receiver. Each such operation states that requirement beside its signature.

Before you release a handle, stop the calls that can still use it.
An owned result has its own lifetime, so another call can use it after its producer finishes.

Terms

Term	Meaning
document	A tree of native values that you can read, build, or serialize.
node	One value in a document, identified within that document.
handle	A reference to a native resource with an explicit lifetime.
owned	A result whose lifetime you control and whose release you must arrange.
borrowed	A value whose lifetime depends on its stated owner.
absent	A value or field that the operation does not supply.
entity	A database object identified independently of its field values.
transaction	A committed database change that orders the recorded facts.
fact	A recorded field value associated with an entity and a transaction.
variable	A named value supplied to an expression or document operation.
clause	One part of a query or mutation document that specifies its behavior.
tick	The ABI unit for a duration or UTC instant: 100 ns. Time and units defines it.

Operations

Operation	Returns	Summary
stardust_abi_version	`uint32_t`	version() returns the loaded library's ABI version.
check_version	Unavailable	check_version(found) verifies that found matches this binding's ABI version.
stardust_plugins	Status. document through output	plugins() returns an owned array document describing the plugins this library can use, followed by any unavailable plugin libraries.
stardust_activate	Status. none through output	activate(token) verifies a license token and licenses this process.
stardust_license	Status. license through output	license() returns the process license state.

stardust_abi_version

36 B

uint32_t stardust_abi_version(void);

Parameters

This call has no parameters.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Examples

version

40 B

int64_t result = stardust_abi_version();

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 01000000000000 00	i64 1
0D	04000000 00000000	root → @4; previous: none

version

128 B

uint32_t found = stardust_abi_version();
if (found != STARDUST_ABI_VERSION) return STARDUST_UNSUPPORTED;
int64_t result = found;

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 01000000000000 00	i64 1
0D	04000000 00000000	root → @4; previous: none

check_version

Compare stardust_abi_version with STARDUST_ABI_VERSION.

Also calls: stardust_abi_version

stardust_plugins

52 B

uint32_t stardust_plugins(stardust_result **output);

92 B

uint32_t stardust_result_take_document(stardust_result *result, stardust_document **output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_plugins

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Examples

Read the compiled plugin inventory

318 B

stardust_result *inventory = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_plugins(&inventory);
if (status == STARDUST_OK) status = stardust_result_take_document(inventory, &result);
stardust_result_release(inventory);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

1.2 kB

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 6261636B757073	txt "backups"
00C	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
019	7C 76657273696F6E	txt "version"
021	1C 31	txt "1"
023	0F 0A 19000000 2100 0000	map leaf, size 10: @19 → @21
02D	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
03B	09	bit true
03C	0F 0A 2D000000 3B00 0000	map leaf, size 10: @2D → @3B
046	07 0E 00810000 2300 0000 3C000000	map branch, size 14, depth 1, slots 8, 15: @23 → @3C
054	FC 77696C6C4E6F74 576F726B57697468	txt "willNotWorkWith"
064	0F 0A 54000000 0C00 0000	map leaf, size 10: @54 → @C
06E	4C 6E616D65	txt "name"
073	7C 686973746F7279	txt "history"
07B	0F 0A 6E000000 7300 0000	map leaf, size 10: @6E → @73
085	BC 64657363726970 74696F6E	txt "description"
091	14 49 486973746F72 7920726574656E74 696F6E3A20707572 67657320656E7469 747920686973746F 7279206279206561 6368207374617264 7573742F68697374 6F72792073657474 696E67	txt "History retention: purge…"
0DC	0F 0A 85000000 9100 0000	map leaf, size 10: @85 → @91
0E6	07 0E 88000000 7B00 0000 DC000000	map branch, size 14, depth 2, slots 3, 7: @7B → @DC
0F4	07 0A 02000000 E600 0000	map branch, size 10, depth 1, slots 1: @E6
0FE	07 12 08C00000 4600 0000 64000000 F400 0000	map branch, size 18, depth 0 (root), slots 3, 14, 15: @46 → @64 → @F4
110	7C 76657273696F6E	txt "version"
118	1C 31	txt "1"
11A	0F 0A 10010000 1801 0000	map leaf, size 10: @110 → @118
124	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
132	09	bit true
133	0F 0A 24010000 3201 0000	map leaf, size 10: @124 → @132
13D	07 0E 00810000 1A01 0000 33010000	map branch, size 14, depth 1, slots 8, 15: @11A → @133
14B	4C 6E616D65	txt "name"
150	14 16 616461707469 76655F7175657279 5F706C616E6E6572	txt "adaptive_query_planner"
168	0F 0A 4B010000 5001 0000	map leaf, size 10: @14B → @150
172	BC 64657363726970 74696F6E	txt "description"

Show all 85 nodes

Offset (hex)	Bytes (hex)	Meaning
17E	14 4E 416461707469 7665206A6F696E20 6F72646572733A20 6C6561726E732066 726F6D2072756E73 20616E642073746F 7265732074686520 706C616E73207468 61742070726F7665 6420626574746572	txt "Adaptive join orders: le…"
1CE	0F 0A 72010000 7E01 0000	map leaf, size 10: @172 → @17E
1D8	07 0E 88000000 6801 0000 CE010000	map branch, size 14, depth 2, slots 3, 7: @168 → @1CE
1E6	07 0A 02000000 D801 0000	map branch, size 10, depth 1, slots 1: @1D8
1F0	07 0E 08800000 3D01 0000 E6010000	map branch, size 14, depth 0 (root), slots 3, 15: @13D → @1E6
1FE	7C 76657273696F6E	txt "version"
206	1C 31	txt "1"
208	0F 0A FE010000 0602 0000	map leaf, size 10: @1FE → @206
212	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
220	09	bit true
221	0F 0A 12020000 2002 0000	map leaf, size 10: @212 → @220
22B	07 0E 00810000 0802 0000 21020000	map branch, size 14, depth 1, slots 8, 15: @208 → @221
239	4C 6E616D65	txt "name"
23E	7C 6F626A65637473	txt "objects"
246	0F 0A 39020000 3E02 0000	map leaf, size 10: @239 → @23E
250	BC 64657363726970 74696F6E	txt "description"
25C	14 47 4F626A656374 2073746F72653A20 636F6E74656E742D 6164647265737365 64207061796C6F61 647320696E206E61 6D65642066696C65 7320616E64206469 726563746F726965 73	txt "Object store: content-ad…"
2A5	0F 0A 50020000 5C02 0000	map leaf, size 10: @250 → @25C
2AF	07 0E 88000000 4602 0000 A5020000	map branch, size 14, depth 2, slots 3, 7: @246 → @2A5
2BD	07 0A 02000000 AF02 0000	map branch, size 10, depth 1, slots 1: @2AF
2C7	07 0E 08800000 2B02 0000 BD020000	map branch, size 14, depth 0 (root), slots 3, 15: @22B → @2BD
2D5	7C 76657273696F6E	txt "version"
2DD	1C 31	txt "1"
2DF	0F 0A D5020000 DD02 0000	map leaf, size 10: @2D5 → @2DD
2E9	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
2F7	09	bit true
2F8	0F 0A E9020000 F702 0000	map leaf, size 10: @2E9 → @2F7
302	07 0E 00810000 DF02 0000 F8020000	map branch, size 14, depth 1, slots 8, 15: @2DF → @2F8
310	4C 6E616D65	txt "name"
315	8C 72656163746F72 73	txt "reactors"
31E	0F 0A 10030000 1503 0000	map leaf, size 10: @310 → @315
328	BC 64657363726970 74696F6E	txt "description"
334	14 41 4C697665206D 75746174696F6E73 3A2073746F726564 206D75746174696F 6E73207769746820 6C6976653A207472 7565207265616374 20746F20636F6D6D 697473	txt "Live mutations: stored m…"
377	0F 0A 28030000 3403 0000	map leaf, size 10: @328 → @334
381	07 0E 88000000 1E03 0000 77030000	map branch, size 14, depth 2, slots 3, 7: @31E → @377
38F	07 0A 02000000 8103 0000	map branch, size 10, depth 1, slots 1: @381
399	07 0E 08800000 0203 0000 8F030000	map branch, size 14, depth 0 (root), slots 3, 15: @302 → @38F
3A7	7C 76657273696F6E	txt "version"
3AF	1C 31	txt "1"
3B1	0F 0A A7030000 AF03 0000	map leaf, size 10: @3A7 → @3AF
3BB	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
3C9	09	bit true
3CA	0F 0A BB030000 C903 0000	map leaf, size 10: @3BB → @3C9
3D4	07 0E 00810000 B103 0000 CA030000	map branch, size 14, depth 1, slots 8, 15: @3B1 → @3CA
3E2	4C 6E616D65	txt "name"
3E7	3C 73646B	txt "sdk"
3EB	0F 0A E2030000 E703 0000	map leaf, size 10: @3E2 → @3E7
3F5	BC 64657363726970 74696F6E	txt "description"
401	14 5E 53444B206765 6E65726174696F6E 3A207075626C6973 6865732061207479 706564207061636B 616765206F662074 68652073746F7265 6420646566696E69 74696F6E73207768 696C652074686520 6461746162617365 206973206F70656E	txt "SDK generation: publishe…"
461	0F 0A F5030000 0104 0000	map leaf, size 10: @3F5 → @401
46B	07 0E 88000000 EB03 0000 61040000	map branch, size 14, depth 2, slots 3, 7: @3EB → @461
479	07 0A 02000000 6B04 0000	map branch, size 10, depth 1, slots 1: @46B
483	07 0E 08800000 D403 0000 79040000	map branch, size 14, depth 0 (root), slots 3, 15: @3D4 → @479
491	0E 1D 00 1F00 050000 00 FE000000 F00100 00 C7020000 990300 00 83040000	array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @FE → @1F0 → @2C7 → @399 → @483

Offset (hex)	Bytes (hex)	Meaning
4AE	91040000 00000000	root → @491; previous: none

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_activate

49 B

uint32_t stardust_activate(stardust_bytes token);

57 B

uint32_t stardust_license(stardust_license_view *output);

Parameters

stardust_activate

Parameter	Type	Ownership	Default	Meaning
`token`	`stardust_bytes`	Value	Required	The PASETO v4.public license token text.

stardust_license

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_license_view *`	Caller-owned output	Required	Initialize its size/version header. Returned pointers borrow the source owner.

Errors

Status	When
`STARDUST_UNLICENSED`	the token is refused; the error names the reason
`STARDUST_INVALID_ARGUMENT`	the token is empty or longer than 4096 bytes

Notes

A refused token preserves the current license. Activation is required before parsing, building resources or opening a database. Existing resources keep working after license replacement or expiry.

Examples

Activate the license from a token file

569 B

char token[4097];
FILE *file = fopen("license.token", "rb");
if (file == NULL) return STARDUST_INVALID_ARGUMENT;
size_t length = fread(token, 1, sizeof token, file);
fclose(file);
while (length > 0 && (token[length - 1] == '\n' || token[length - 1] == '\r')) length--;
stardust_bytes bytes = {(const uint8_t *)token, (int64_t)length};
stardust_license_view result = {.size = sizeof(stardust_license_view), .version = 1};
uint32_t status = stardust_activate(bytes);
if (status == STARDUST_OK) status = stardust_license(&result);
if (status != STARDUST_OK) return status;

TRON

332 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	5C 6275696C64	txt "build"
00A	00	nil
00B	0F 0A 04000000 0A00 0000	map leaf, size 10: @4 → @A
015	4C 74696572	txt "tier"
01A	0C	txt ""
01B	0F 0A 15000000 1A00 0000	map leaf, size 10: @15 → @1A
025	07 0E 20080000 0B00 0000 1B000000	map branch, size 14, depth 1, slots 5, 11: @B → @1B
033	14 13 726566757365 645F737570706F72 745F656E64	txt "refused_support_end"
048	00	nil
049	0F 0A 33000000 4800 0000	map leaf, size 10: @33 → @48
053	AC 6C6963656E7365 5F6964	txt "license_id"
05E	4C 74657374	txt "test"
063	0F 0A 53000000 5E00 0000	map leaf, size 10: @53 → @5E
06D	07 0E 08020000 4900 0000 63000000	map branch, size 14, depth 1, slots 3, 9: @49 → @63
07B	7C 6661696C757265	txt "failure"
083	4C 6E6F6E65	txt "none"
088	0F 0A 7B000000 8300 0000	map leaf, size 10: @7B → @83
092	7C 6C6963656E7365	txt "license"
09A	0C	txt ""
09B	0F 0A 92000000 9A00 0000	map leaf, size 10: @92 → @9A
0A5	7C 7375626A656374	txt "subject"
0AD	4C 74657374	txt "test"
0B2	0F 0A A5000000 AD00 0000	map leaf, size 10: @A5 → @AD
0BC	BC 737570706F7274 5F656E64	txt "support_end"
0C8	02 00C0489F6ADB01 01	i64 72580320000000000
0D1	0F 0A BC000000 C800 0000	map leaf, size 10: @BC → @C8
0DB	6C 616374697665	txt "active"
0E2	09	bit true
0E3	0F 0A DB000000 E200 0000	map leaf, size 10: @DB → @E2
0ED	4C 6E616D65	txt "name"
0F2	0C	txt ""
0F3	0F 0A ED000000 F200 0000	map leaf, size 10: @ED → @F2
0FD	7C 65787069726573	txt "expires"
105	00	nil
106	0F 0A FD000000 0501 0000	map leaf, size 10: @FD → @105
110	07 0E 06000000 F300 0000 06010000	map branch, size 14, depth 1, slots 1, 2: @F3 → @106
11E	07 26 219F0000 2500 0000 6D000000 8800 0000 9B000000 B200 0000 D1000000 E300 0000 10010000	map branch, size 38, depth 0 (root), slots 0, 5, 8, 9, 10, 11, 12, 15: @25 → @6D → @88 → @9B → @B2 → @D1 → @E3 → @110
144	1E010000 00000000	root → @11E; previous: none

Also calls: stardust_license

stardust_license

57 B

uint32_t stardust_license(stardust_license_view *output);

Parameters

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_license_view *`	Caller-owned output	Required	Initialize its size/version header. Returned pointers borrow the source owner.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Examples

Read the process license

172 B

stardust_license_view result = {.size = sizeof(stardust_license_view), .version = 1};
uint32_t status = stardust_license(&result);
if (status != STARDUST_OK) return status;

TRON

332 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	5C 6275696C64	txt "build"
00A	00	nil
00B	0F 0A 04000000 0A00 0000	map leaf, size 10: @4 → @A
015	4C 74696572	txt "tier"
01A	0C	txt ""
01B	0F 0A 15000000 1A00 0000	map leaf, size 10: @15 → @1A
025	07 0E 20080000 0B00 0000 1B000000	map branch, size 14, depth 1, slots 5, 11: @B → @1B
033	14 13 726566757365 645F737570706F72 745F656E64	txt "refused_support_end"
048	00	nil
049	0F 0A 33000000 4800 0000	map leaf, size 10: @33 → @48
053	AC 6C6963656E7365 5F6964	txt "license_id"
05E	4C 74657374	txt "test"
063	0F 0A 53000000 5E00 0000	map leaf, size 10: @53 → @5E
06D	07 0E 08020000 4900 0000 63000000	map branch, size 14, depth 1, slots 3, 9: @49 → @63
07B	7C 6661696C757265	txt "failure"
083	4C 6E6F6E65	txt "none"
088	0F 0A 7B000000 8300 0000	map leaf, size 10: @7B → @83
092	7C 6C6963656E7365	txt "license"
09A	0C	txt ""
09B	0F 0A 92000000 9A00 0000	map leaf, size 10: @92 → @9A
0A5	7C 7375626A656374	txt "subject"
0AD	4C 74657374	txt "test"
0B2	0F 0A A5000000 AD00 0000	map leaf, size 10: @A5 → @AD
0BC	BC 737570706F7274 5F656E64	txt "support_end"
0C8	02 00C0489F6ADB01 01	i64 72580320000000000
0D1	0F 0A BC000000 C800 0000	map leaf, size 10: @BC → @C8
0DB	6C 616374697665	txt "active"
0E2	09	bit true
0E3	0F 0A DB000000 E200 0000	map leaf, size 10: @DB → @E2
0ED	4C 6E616D65	txt "name"
0F2	0C	txt ""
0F3	0F 0A ED000000 F200 0000	map leaf, size 10: @ED → @F2
0FD	7C 65787069726573	txt "expires"
105	00	nil
106	0F 0A FD000000 0501 0000	map leaf, size 10: @FD → @105
110	07 0E 06000000 F300 0000 06010000	map branch, size 14, depth 1, slots 1, 2: @F3 → @106
11E	07 26 219F0000 2500 0000 6D000000 8800 0000 9B000000 B200 0000 D1000000 E300 0000 10010000	map branch, size 38, depth 0 (root), slots 0, 5, 8, 9, 10, 11, 12, 15: @25 → @6D → @88 → @9B → @B2 → @D1 → @E3 → @110
144	1E010000 00000000	root → @11E; previous: none

stardust_license_view

This record contains the result of license. Text fields are copies.

Note

Supply size and version with each record. NULL options select the defaults of the call.

Field	C type	Unit	Range	Default	Meaning
`size`	`uint32_t`	Bytes	Unsigned u32	Required: sizeof(stardust_license_view)	—
`version`	`uint32_t`	None	Unsigned u32	Required: 1	—
`active`	`uint32_t`	None	Unsigned u32	The call sets it	The process holds a verified license.
`failure`	`uint32_t`	None	Unsigned u32	The call sets it	Why the last activation failed; none when it succeeded or none was tried.
`support_end_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The last build date the license covers, as a UTC instant.
`expires_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The expiry checked at activation and database open, as a UTC instant. Existing resources keep working.
`build_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The build date of this library, at UTC midnight.
`refused_support_end_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The support end of the token the last activation refused as `support_ended`, as a UTC instant.
`subject`	`stardust_bytes`	None	C type range	The call sets it	The OAuth sign-in identity of the license. Empty when not active.
`license_id`	`stardust_bytes`	None	C type range	The call sets it	The unique license token ID. Empty when not active.
`name`	`stardust_bytes`	None	C type range	The call sets it	The project name, or account display name for Community. Empty when absent.
`license`	`stardust_bytes`	None	C type range	The call sets it	The ID of the purchased license, a ULID. Empty when absent.
`tier`	`stardust_bytes`	None	C type range	The call sets it	The license tier: community, solo or team. Empty when absent.