/src/c.h at c41485ecde23fd6c25c07616f9df8d4f3314b5c1

// 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_OK = 0,
	SOOD_ITERATOR_DONE = 1,
	SOOD_ERR_PARSE_HEADER_SIZE_MISMATCH = 2,
	SOOD_ERR_PARSE_INVALID_SIGNATURE = 3,
	SOOD_ERR_PARSE_EMPTY_KEY = 4,
	SOOD_ERR_PARSE_KEY_SIZE_MISMATCH = 5,
	SOOD_ERR_PARSE_NON_UTF8_KEY = 6,
	SOOD_ERR_PARSE_VALUE_SIZE_CORRUPTED = 7,
	SOOD_ERR_PARSE_VALUE_SIZE_MISMATCH = 8,
	SOOD_ERR_PARSE_NON_UTF8_VALUE = 9,
	SOOD_ERR_VALIDATE_MISSING_REQUIRED_PROPERTY = 10,
	SOOD_ERR_VALIDATE_UNEXPECTED_VALUE_TYPE = 11,
	SOOD_ERR_VALIDATE_UNEXPECTED_MESSAGE_KIND = 12,
} sood_result;

/**
 * Get text representation of "sood_result". Text does not have "SOOD_" prefix.
 *
 * Returns an address of a null-terminated string (C string).
 *
 * Returns a NULL (0) when "result" is not a valid "sood_result" value.
 */
const char* sood_get_result_string(sood_result result);

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;

/**
 * Parse bytes as SOOD message.
 *
 * If you just want to perform service discovery, use "sood_discovery_response_parse" instead.
 * This function is for advanced use-cases.
 *
 * Returns "SOOD_OK" when message header is valid and body part is ready to read.
 * The body part is not checked thus user should not assume a message is valid until iterating
 * through body.
 *
 * Returns "SOOD_ERR_PARSE_HEADER_SIZE_MISMATCH" or "SOOD_ERR_PARSE_INVALID_SIGNATURE"
 * when receiving bytes is not a valid SOOD message header.
 *
 * @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_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 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".
 *
 * Returns "SOOD_OK" when it reads property into "dst".
 *
 * Returns "SOOD_ITERATOR_DONE" when no more properties to read.
 * "dst" is intact.
 *
 * Returns below error results when a message is not valid SOOD message:
 *
 * - SOOD_ERR_PARSE_EMPTY_KEY
 * - SOOD_ERR_PARSE_KEY_SIZE_MISMATCH
 * - SOOD_ERR_PARSE_NON_UTF8_KEY
 * - SOOD_ERR_PARSE_VALUE_SIZE_CORRUPTED
 * - SOOD_ERR_PARSE_VALUE_SIZE_MISMATCH
 * - SOOD_ERR_PARSE_NON_UTF8_VALUE
 *
 * @param iter - Iterator to iterate on.
 * @param dst - Pointer for property struct to put read key/value in.
 */
sood_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 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.
 *
 * Returns "SOOD_OK" when the whole bytes consists valid SOOD message and read into "dst".
 *
 * Returns "SOOD_ERR_PARSE_*" when the received bytes is not a valid SOOD message.
 *
 * Returns "SOOD_ERR_VALIDATE_*" when the received bytes is valid but the parsed message
 * does not qualify as a response message sent by Roon Server.
 *
 * @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_result sood_discovery_response_parse(
	sood_discovery_response *dst,
	const char *message_ptr,
	size_t message_len
);

#ifdef __cplusplus
}
#endif

#endif // SOOD_H