/src/c.h at 6bbc2d16eebe1a54835573b2066c0c8455d61dda

// 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.
 *
 * If you just want to perform service discovery, use "sood_discovery_response_parse" instead.
 * This function is for advanced use-cases.
 *
 * @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;

typedef enum {
	SOOD_DISCOVERY_RESPONSE_PARSE_OK = 0,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_HEADER_SIZE_MISMATCH = 1,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_INVALID_SIGNATURE = 2,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_EMPTY_KEY = 3,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_KEY_SIZE_MISMATCH = 4,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_NON_UTF8_KEY = 5,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_VALUE_SIZE_CORRUPTED = 6,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_VALUE_SIZE_MISMATCH = 7,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_NON_UTF8_VALUE = 8,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_UNEXPECTED_KIND = 9,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_MISSING_PROPERTY = 10,
	SOOD_DISCOVERY_RESPONSE_PARSE_ERROR_UNEXPECTED_VALUE = 11,
} sood_discovery_response_parse_result;

typedef struct {
	uint16_t http_port;
	const char *name_ptr;
	size_t name_len;
	const char *display_version_ptr;
	size_t display_version_len;
	const char *unique_id_ptr;
	size_t unique_id_len;
} sood_discovery_response;

/**
 * Parse bytes as SOOD response message.
 *
 * This function completely scans properties field and returns SOOD_DISCOVERY_RESPONSE_PARSE_OK
 * only when the whole message is valid and every required field exists.
 *
 * @param dst - Pointer for response struct to set parsed properties.
 * @param message_ptr - Pointer for source bytes.
 * @param message_len - Byte size of the source bytes.
 */
sood_discovery_response_parse_result sood_discovery_response_parse(
	sood_discovery_response *dst,
	const char *message_ptr,
	size_t message_len
);

#ifdef __cplusplus
}
#endif

#endif // SOOD_H