/core/src/plac.h at a44d94419afc5f27ff5034674a806494477bbef6

/*
 * Copyright 2025 Shota FUJI
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * ===
 *
 * C99 header file for helper C API for Plac core library.
 * This file is not checked against a generated library file: carefully write and review
 * definitions and implementations.
 */

#ifndef PLAC_CORE_H
#define PLAC_CORE_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

// discovery.Server
typedef struct {
	void *__pri;
	char *id;
	char *name;
	char *version;
	char *ip_addr;
	uint16_t http_port;
} plac_discovery_server;
plac_discovery_server *plac_discovery_server_retain(plac_discovery_server*);
void plac_discovery_server_release(plac_discovery_server*);

// discovery.ScanResult.Code
typedef enum {
	PLAC_DISCOVERY_SCAN_RESULT_OK = 0,
	PLAC_DISCOVERY_SCAN_RESULT_UNKNOWN = 1,
	PLAC_DISCOVERY_SCAN_RESULT_NETWORK_UNAVAILABLE = 2,
	PLAC_DISCOVERY_SCAN_RESULT_SOCKET_PERMISSION_DENIED = 3,
	PLAC_DISCOVERY_SCAN_RESULT_SOCKET_ERROR = 4,
	PLAC_DISCOVERY_SCAN_RESULT_OUT_OF_MEMORY = 5,
} plac_discovery_scan_result_code;

// discovery.ScanResult
typedef struct {
	void *__pri;
	plac_discovery_server **servers_ptr;
	size_t servers_len;
	plac_discovery_scan_result_code code;
} plac_discovery_scan_result;
plac_discovery_scan_result *plac_discovery_scan_result_retain(plac_discovery_scan_result*);
void plac_discovery_scan_result_release(plac_discovery_scan_result*);

// discovery
plac_discovery_scan_result *plac_discovery_scan();
plac_discovery_scan_result *plac_discovery_find(const char *server_id);
plac_discovery_scan_result *plac_discovery_resolve(
	const char *server_id,
	const char *ip_addr,
	uint16_t http_port
);

// transport.NowPlaying
typedef struct {
	void *__pri;
	const char *one_line_line1;
	const char *two_line_line1;
	const char *two_line_line2;
	const char *three_line_line1;
	const char *three_line_line2;
	const char *three_line_line3;
	uint64_t seek_position;
	uint64_t length;
	bool has_seek_position;
	bool has_length;
	const char *image_key;
} plac_transport_now_playing;
plac_transport_now_playing *plac_transport_now_playing_retain(plac_transport_now_playing*);
void plac_transport_now_playing_release(plac_transport_now_playing*);

// transport.SeekChange
typedef struct {
	void *__pri;
	const char *zone_id;
	uint64_t seek_position;
	bool has_seek_position;
} plac_transport_seek_change;
plac_transport_seek_change *plac_transport_seek_change_retain(plac_transport_seek_change*);
void plac_transport_seek_change_release(plac_transport_seek_change*);

// transport.OutputVolumeUnit
typedef enum {
	PLAC_TRANSPORT_OUTPUT_VOLUME_UNKNOWN = 0,
	PLAC_TRANSPORT_OUTPUT_VOLUME_NUMBER = 1,
	PLAC_TRANSPORT_OUTPUT_VOLUME_DECIBEL = 2,
} plac_transport_output_volume_unit;

// transport.OutputVolume
typedef struct {
	plac_transport_output_volume_unit unit;
	double min;
	double max;
	double value;
	double step;
	bool muted;
} plac_transport_output_volume;

// transport.Output
typedef struct {
	void *__pri;
	const char *id;
	const char *display_name;
	bool is_incremental_volume;
	// This field is useless if "is_incremental_volume" is true
	plac_transport_output_volume volume;
} plac_transport_output;
plac_transport_output *plac_transport_output_retain(plac_transport_output*);
void plac_transport_output_release(plac_transport_output*);

// transport.PlaybackState
typedef enum {
	PLAC_TRANSPORT_PLAYBACK_LOADING = 0,
	PLAC_TRANSPORT_PLAYBACK_STOPPED = 1,
	PLAC_TRANSPORT_PLAYBACK_PAUSED = 2,
	PLAC_TRANSPORT_PLAYBACK_PLAYING = 3,
} plac_transport_playback_state;

// transport.Action
#define PLAC_TRANSPORT_ACTION_NEXT (1 << 0)
#define PLAC_TRANSPORT_ACTION_PREV (1 << 1)
#define PLAC_TRANSPORT_ACTION_PAUSE (1 << 2)
#define PLAC_TRANSPORT_ACTION_PLAY (1 << 3)
#define PLAC_TRANSPORT_ACTION_SEEK (1 << 4)

// transport.Zone
typedef struct {
	void *__pri;
	char *id;
	char *name;
	plac_transport_output **outputs;
	size_t outputs_len;
	plac_transport_now_playing *now_playing;
	plac_transport_playback_state playback;
	uint16_t allowed_action;
} plac_transport_zone;
plac_transport_zone *plac_transport_zone_retain(plac_transport_zone*);
void plac_transport_zone_release(plac_transport_zone*);

// transport.ZoneListEvent
typedef struct {
	void *__pri;
	plac_transport_zone **added_zones_ptr;
	size_t added_zones_len;
	plac_transport_zone **changed_zones_ptr;
	size_t changed_zones_len;
	char **removed_zone_ids_ptr;
	size_t removed_zone_ids_len;
	plac_transport_seek_change **seek_changes_ptr;
	size_t seek_changes_len;
} plac_transport_zone_list_event;
plac_transport_zone_list_event *plac_transport_zone_list_event_retain(plac_transport_zone_list_event*);
void plac_transport_zone_list_event_release(plac_transport_zone_list_event*);

// transport.ControlResultCode
typedef enum {
	PLAC_TRANSPORT_CONTROL_RESULT_OK = 0,
	PLAC_TRANSPORT_CONTROL_RESULT_UNKNOWN_ERROR = 1,
	PLAC_TRANSPORT_CONTROL_RESULT_OUT_OF_MEMORY = 2,
	PLAC_TRANSPORT_CONTROL_RESULT_FAILED_TO_SEND = 3,
	PLAC_TRANSPORT_CONTROL_RESULT_CLOSED = 4,
	PLAC_TRANSPORT_CONTROL_RESULT_NO_ACTION_BIT_SET = 5,
	PLAC_TRANSPORT_CONTROL_RESULT_SERVER_ERROR = 6,
	PLAC_TRANSPORT_CONTROL_RESULT_TIMEOUT = 7,
} plac_transport_control_result_code;

// transport.SeekResultCode
typedef enum {
	PLAC_TRANSPORT_SEEK_RESULT_OK = 0,
	PLAC_TRANSPORT_SEEK_RESULT_UNKNOWN_ERROR = 1,
	PLAC_TRANSPORT_SEEK_RESULT_OUT_OF_MEMORY = 2,
	PLAC_TRANSPORT_SEEK_RESULT_FAILED_TO_SEND = 3,
	PLAC_TRANSPORT_SEEK_RESULT_CLOSED = 4,
	PLAC_TRANSPORT_SEEK_RESULT_SERVER_ERROR = 5,
	PLAC_TRANSPORT_SEEK_RESULT_TIMEOUT = 6,
} plac_transport_seek_result_code;

// transport.VolumeControlResultCode
typedef enum {
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_OK = 0,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_UNKNOWN_ERROR = 1,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_OUT_OF_MEMORY = 2,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_FAILED_TO_SEND = 3,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_CLOSED = 4,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_SERVER_ERROR = 5,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_TIMEOUT = 6,
	PLAC_TRANSPORT_VOLUME_CONTROL_RESULT_ILLEGAL_METHOD = 7,
} plac_transport_volume_control_result_code;

// browse.Hierarchy
typedef enum {
	PLAC_BROWSE_HIERARCHY_BROWSE = 0,
	PLAC_BROWSE_HIERARCHY_PLAYLISTS = 1,
	PLAC_BROWSE_HIERARCHY_SETTINGS = 2,
	PLAC_BROWSE_HIERARCHY_INTERNET_RADIO = 3,
	PLAC_BROWSE_HIERARCHY_ALBUMS = 4,
	PLAC_BROWSE_HIERARCHY_ARTISTS = 5,
	PLAC_BROWSE_HIERARCHY_GENRES = 6,
	PLAC_BROWSE_HIERARCHY_COMPOSERS = 7,
	PLAC_BROWSE_HIERARCHY_SEARCH = 8,
} plac_browse_hierarchy;

// browse.ItemHint
typedef enum {
	PLAC_BROWSE_ITEM_HINT_UNKNOWN = 0,
	PLAC_BROWSE_ITEM_HINT_ACTION = 1,
	PLAC_BROWSE_ITEM_HINT_ACTION_LIST = 2,
	PLAC_BROWSE_ITEM_HINT_LIST = 3,
	PLAC_BROWSE_ITEM_HINT_HEADER = 4,
} plac_browse_item_hint;

// browse.InputPrompt
typedef struct {
	void *__pri;
	const char* prompt;
	const char* action;
	const char* default_value;
	bool is_password;
} plac_browse_input_prompt;
plac_browse_input_prompt *plac_browse_input_prompt_retain(plac_browse_input_prompt*);
void plac_browse_input_prompt_release(plac_browse_input_prompt*);

// browse.Item
typedef struct {
	void *__pri;
	const char *title;
	const char *subtitle;
	const char *image_key;
	const char *item_key;
	plac_browse_item_hint hint;
	plac_browse_input_prompt *prompt;
} plac_browse_item;
plac_browse_item *plac_browse_item_retain(plac_browse_item*);
void plac_browse_item_release(plac_browse_item*);

// browse.ResultCode
typedef enum {
	PLAC_BROWSE_RESULT_OK = 0,
	PLAC_BROWSE_RESULT_UNKNOWN_ERROR = 1,
	PLAC_BROWSE_RESULT_MISSING_PROPERTY = 2,
	PLAC_BROWSE_RESULT_OUT_OF_MEMORY = 3,
	PLAC_BROWSE_RESULT_FAILED_TO_SEND = 4,
	PLAC_BROWSE_RESULT_CLOSED = 5,
	PLAC_BROWSE_RESULT_TIMEOUT = 6,
} plac_browse_result_code;

// browse.ResultAction
typedef enum {
	PLAC_BROWSE_RESULT_ACTION_NONE = 0,
	PLAC_BROWSE_RESULT_ACTION_REPLACE_ITEM = 1,
	PLAC_BROWSE_RESULT_ACTION_REMOVE_ITEM = 2,
	PLAC_BROWSE_RESULT_ACTION_LIST = 3,
	PLAC_BROWSE_RESULT_ACTION_ERROR_MESSAGE = 4,
	PLAC_BROWSE_RESULT_ACTION_MESSAGE = 5,
} plac_browse_result_action;

// browse.ReplaceItemAction
typedef struct {
	void *__pri;
	plac_browse_item *item;
} plac_browse_replace_item_action;
plac_browse_replace_item_action *plac_browse_replace_item_action_retain(plac_browse_replace_item_action*);
void plac_browse_replace_item_action_release(plac_browse_replace_item_action*);

// browse.ListAction
typedef struct {
	void *__pri;
	const char *title;
	const char *subtitle;
	const char *image_key;
	uint64_t level;
	plac_browse_item **items_ptr;
	size_t items_len;
} plac_browse_list_action;
plac_browse_list_action *plac_browse_list_action_retain(plac_browse_list_action*);
void plac_browse_list_action_release(plac_browse_list_action*);

// browse.ErrorMessageAction
typedef struct {
	void *__pri;
	const char *message;
} plac_browse_error_message_action;
plac_browse_error_message_action *plac_browse_error_message_action_retain(plac_browse_error_message_action*);
void plac_browse_error_message_action_release(plac_browse_error_message_action*);

// browse.MessageAction
typedef struct {
	void *__pri;
	const char *message;
} plac_browse_message_action;
plac_browse_message_action *plac_browse_message_action_retain(plac_browse_message_action*);
void plac_browse_message_action_release(plac_browse_message_action*);

// browse.Result
typedef struct {
	void *__pri;
	plac_browse_result_code code;
	plac_browse_result_action action;
} plac_browse_result;
plac_browse_result *plac_browse_result_retain(plac_browse_result*);
void plac_browse_result_release(plac_browse_result*);
plac_browse_replace_item_action *plac_browse_result_get_replace_item_action(plac_browse_result*);
plac_browse_list_action *plac_browse_result_get_list_action(plac_browse_result*);
plac_browse_error_message_action *plac_browse_result_get_error_message_action(plac_browse_result*);
plac_browse_message_action *plac_browse_result_get_message_action(plac_browse_result*);

// browse.Label
typedef struct {
	void *__pri;
	const char* plain_text;
} plac_browse_label;
plac_browse_label *plac_browse_label_from_string(const char*);
plac_browse_label *plac_browse_label_retain(plac_browse_label*);
void plac_browse_label_release(plac_browse_label*);

// image.ScalingMethod
typedef enum {
	PLAC_IMAGE_SCALING_METHOD_FIT = 0,
	PLAC_IMAGE_SCALING_METHOD_FILL = 1,
	PLAC_IMAGE_SCALING_METHOD_STRETCH = 2,
} plac_image_scaling_method;

// image.ContentType
typedef enum {
	PLAC_IMAGE_CONTENT_TYPE_JPEG = 0,
	PLAC_IMAGE_CONTENT_TYPE_PNG = 1,
} plac_image_content_type;

// image.GetResultCode
typedef enum {
	PLAC_IMAGE_GET_RESULT_OK = 0,
	PLAC_IMAGE_GET_RESULT_UNKNOWN_ERROR = 1,
	PLAC_IMAGE_GET_RESULT_OUT_OF_MEMORY = 2,
	PLAC_IMAGE_GET_RESULT_UNEXPECTED_RESPONSE = 3,
	PLAC_IMAGE_GET_RESULT_SOCKET_CLOSED = 4,
	PLAC_IMAGE_GET_RESULT_FAILED_TO_SEND = 5,
	PLAC_IMAGE_GET_RESULT_TIMEOUT = 6,
} plac_image_get_result_code;

// image.GetOptions
typedef struct { void *__pri; } plac_image_get_options;
plac_image_get_options *plac_image_get_options_make();
plac_image_get_options *plac_image_get_options_retain(plac_image_get_options*);
void *plac_image_get_options_release(plac_image_get_options*);
void *plac_image_get_options_set_size(plac_image_get_options*, plac_image_scaling_method, size_t width, size_t height);
void *plac_image_get_options_set_content_type(plac_image_get_options*, plac_image_content_type);

// image.Image
typedef struct {
	void *__pri;
	plac_image_content_type content_type;
	const uint8_t *data_ptr;
	size_t data_len;
} plac_image_image;
plac_image_image *plac_image_image_retain(plac_image_image*);
void plac_image_image_release(plac_image_image*);

// image.GetResult
typedef struct {
	void *__pri;
	plac_image_get_result_code code;
	plac_image_image *image;
} plac_image_get_result;
plac_image_get_result *plac_image_get_result_retain(plac_image_get_result*);
void plac_image_get_result_release(plac_image_get_result*);

// connection.ConnectedEvent
typedef struct {
	void *__pri;
	char *token;
} plac_connection_connected_event;
plac_connection_connected_event *plac_connection_connected_event_retain(plac_connection_connected_event*);
void plac_connection_connected_event_release(plac_connection_connected_event*);

// connection.ConnectionError
typedef enum {
	PLAC_CONNECTION_ERROR_UNKNOWN = 0,
	PLAC_CONNECTION_ERROR_CLOSED_BY_SERVER = 1,
	PLAC_CONNECTION_ERROR_OUT_OF_MEMORY = 2,
	PLAC_CONNECTION_ERROR_UNEXPECTED_RESPONSE = 3,
	PLAC_CONNECTION_ERROR_NETWORK_UNAVAILABLE = 4,
	PLAC_CONNECTION_ERROR_NETWORK_ERROR = 5,
} plac_connection_connection_error;

// connection.ConnectionErrorEvent
typedef struct {
	void *__pri;
	plac_connection_connection_error code;
} plac_connection_connection_error_event;
plac_connection_connection_error_event *plac_connection_connection_error_event_retain(plac_connection_connection_error_event*);
void plac_connection_connection_error_event_release(plac_connection_connection_error_event*);

// connection.Event.Kind
typedef enum {
	PLAC_CONNECTION_EVENT_ERROR = 0,
	PLAC_CONNECTION_EVENT_CONNECTED = 1,
	PLAC_CONNECTION_EVENT_ZONE_LIST = 10,
} plac_connection_event_kind;

// connection.Event
typedef struct {
	void *__pri;
	plac_connection_event_kind kind;
} plac_connection_event;
plac_connection_event *plac_connection_event_retain(plac_connection_event*);
void plac_connection_event_release(plac_connection_event*);
plac_connection_connection_error_event *plac_connection_event_get_connection_error_event(plac_connection_event*);
plac_connection_connected_event *plac_connection_event_get_connected_event(plac_connection_event*);
plac_transport_zone_list_event *plac_connection_event_get_zone_list_event(plac_connection_event*);

// connection.Connection
typedef struct { void *__pri; } plac_connection;
plac_connection *plac_connection_make(plac_discovery_server*, const char *token);
plac_connection *plac_connection_retain(plac_connection*);
void plac_connection_release(plac_connection*);
void plac_connection_disconnect(plac_connection*);
plac_connection_event *plac_connection_get_event(plac_connection*);
void plac_connection_subscribe_zones(plac_connection*);
plac_transport_control_result_code plac_connection_control(plac_connection*, plac_transport_zone*, uint16_t action);
plac_transport_seek_result_code plac_connection_seek(plac_connection*, plac_transport_zone*, int64_t seconds);
plac_transport_volume_control_result_code plac_connection_change_volume(plac_connection*, plac_transport_output*, double abs_value);
plac_transport_volume_control_result_code plac_connection_increase_volume(plac_connection*, plac_transport_output*);
plac_transport_volume_control_result_code plac_connection_decrease_volume(plac_connection*, plac_transport_output*);
plac_browse_result *plac_connection_browse(plac_connection*, plac_browse_hierarchy, plac_transport_zone*, plac_browse_item*, bool pop);
plac_image_get_result *plac_connection_get_image(plac_connection*, const char *image_key, plac_image_get_options*);
const char *plac_connection_get_image_url(plac_connection*, const char *image_key, plac_image_get_options*);

#endif