1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12
13. 13
14. 14
15. 15
16. 16
17. 17
18. 18
19. 19
20. 20
21. 21
22. 22
23. 23
24. 24
25. 25
26. 26
27. 27
28. 28
29. 29
30. 30
31. 31
32. 32
33. 33
34. 34
35. 35
36. 36
37. 37
38. 38
39. 39
40. 40
41. 41
42. 42
43. 43
44. 44
45. 45
46. 46
47. 47
48. 48
49. 49
50. 50
51. 51
52. 52
53. 53
54. 54
55. 55
56. 56
57. 57
58. 58
59. 59
60. 60
61. 61
62. 62
63. 63
64. 64
65. 65
66. 66
67. 67
68. 68
69. 69
70. 70
71. 71
72. 72
73. 73
74. 74
75. 75
76. 76
77. 77
78. 78
79. 79
80. 80
81. 81
82. 82
83. 83
84. 84
85. 85
86. 86
87. 87
88. 88
89. 89
90. 90
91. 91
92. 92
93. 93
94. 94
95. 95
96. 96
97. 97
98. 98
99. 99
100. 100
101. 101
102. 102
103. 103
104. 104
105. 105
106. 106
107. 107
108. 108
109. 109
110. 110
111. 111
112. 112
113. 113
114. 114
115. 115
116. 116
117. 117
118. 118
119. 119
120. 120
121. 121
122. 122
123. 123
124. 124
125. 125
126. 126
127. 127
128. 128
129. 129
130. 130
131. 131
132. 132
133. 133
134. 134
135. 135
136. 136
137. 137

// Copyright 2025 Shota FUJI
//
// Licensed under the Zero-Clause BSD License or the Apache License, Version 2.0, at your option.
// You may not use, copy, modify, or distribute this file except according to those terms. You can
// find a copy of the Zero-Clause BSD License at LICENSES/0BSD.txt, and a copy of the Apache License,
// Version 2.0 at LICENSES/Apache-2.0.txt. You may also obtain a copy of the Apache License, Version
// 2.0 at <https://www.apache.org/licenses/LICENSE-2.0>
//
// SPDX-License-Identifier: 0BSD OR Apache-2.0
//
// ===
//
// C99 header file for the C-compatible library binary (compile artifact of `c.zig`).
// As there is no check process/tool for verifying C header file and ABI, you should carefully
// review the code here.
//
// Here is the design guideline for this C-API:
// * No allocation. (internal Zig code uses stack a lot so it's not that efficient though.)
// * No opaque struct. Add fields carefully.
// * Don't use macro for enums. You can copy and paste enum body between C<->Zig.
// * Keep the usage of preprocessors as low as possible.

#ifndef SOOD_H
#define SOOD_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

typedef enum {
	SOOD_MESSAGE_UNKNOWN = 0,
	SOOD_MESSAGE_QUERY = 1,
	SOOD_MESSAGE_RESPONSE = 2,
} sood_message_kind;

typedef struct {
	const char *raw_ptr;
	size_t raw_len;
	sood_message_kind kind;
} sood_message;

typedef enum {
	SOOD_PARSE_OK = 0,
	SOOD_PARSE_ERROR_HEADER_SIZE_MISMATCH = 1,
	SOOD_PARSE_ERROR_INVALID_SIGNATURE = 2,
} sood_parse_result;

/**
 * Parse bytes as SOOD message.
 *
 * This function ONLY parses header part: remaining bytes (properties) are unchecked.
 * Validations are performed on "sood_message_iter_next". Getting "SOOD_PARSE_OK"
 * does not mean the message is valid.
 *
 * @param dst - Pointer for message struct to set parsed data.
 * @param ptr - Pointer for the source bytes.
 * @param len - Length of the source bytes.
 */
sood_parse_result sood_parse(sood_message *dst, const char *ptr, size_t len);

typedef struct {
	const char *key_ptr;
	size_t key_len;
	const char *value_ptr;
	size_t value_len;
} sood_message_property;

typedef enum {
	SOOD_READ_PROPERTY_OK = 0,
	SOOD_READ_PROPERTY_DONE = 1,
	SOOD_READ_PROPERTY_ERROR_EMPTY_KEY = 2,
	SOOD_READ_PROPERTY_ERROR_KEY_SIZE_MISMATCH = 3,
	SOOD_READ_PROPERTY_ERROR_NON_UTF8_KEY = 4,
	SOOD_READ_PROPERTY_ERROR_VALUE_SIZE_CORRUPTED = 5,
	SOOD_READ_PROPERTY_ERROR_VALUE_SIZE_MISMATCH = 6,
	SOOD_READ_PROPERTY_ERROR_NON_UTF8_VALUE = 7,
} sood_message_read_property_result;

typedef struct {
	const sood_message *msg;
	size_t i;
} sood_message_iter;

/**
 * Initializes an iterator for message properties.
 *
 * @param dst - Pointer for property struct to initialize.
 * @param msg - Message to iterate on.
 */
void sood_message_iterator(sood_message_iter *dst, const sood_message *msg);

/**
 * Moves iterator next and parse next property into "dst".
 *
 * If iterator is at the end of body, this function returns "SOOD_READ_PROPERTY_DONE".
 * This function returns "SOOD_READ_PROPERTY_ERROR_*" when encountered message fields
 * violating SOOD message properties schema.
 *
 * @param iter - Iterator to iterate on.
 * @param dst - Pointer for property struct to put read key/value in.
 */
sood_message_read_property_result sood_message_iter_next(
	sood_message_iter *iter,
	sood_message_property *dst
);

/**
 * Minimum pre-constructed bytes of SOOD discovery query.
 *
 * If you don't use "_tid" field, simply send this bytes over UDP.
 */
extern const char sood_discovery_query_prebuilt[61];

/**
 * IPv4 address for IP multicast.
 *
 * This constant is big endian (network byte order).
 */
extern const uint32_t sood_discovery_multicast_ipv4_address_be;

/**
 * IPv4 address for IP multicast.
 */
extern const uint8_t sood_discovery_multicast_ipv4_address[4];

/**
 * Destination UDP port for IP multicast and broadcast.
 */
extern const uint16_t sood_discovery_server_udp_port;

#ifdef __cplusplus
}
#endif

#endif // SOOD_H