// Public nt-lite kernel-audio provider declarations.

#pragma once

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <ntlite/status.h>

struct DEVICE_OBJECT;
typedef struct IO_AUDIO_ENDPOINT IO_AUDIO_ENDPOINT;

// Identifies one logical render destination rather than one codec pin.
typedef enum IO_AUDIO_ENDPOINT_KIND {
    IoAudioEndpointLineOut = 1,
    IoAudioEndpointSpeakerHeadphone,
    IoAudioEndpointOtherAnalog
} IO_AUDIO_ENDPOINT_KIND;

// Identifies the canonical interleaved PCM sample representation.
typedef enum IO_AUDIO_SAMPLE_FORMAT {
    IoAudioSampleS16 = 1
} IO_AUDIO_SAMPLE_FORMAT;

// Describes interleaved PCM frames.
typedef struct IO_AUDIO_FORMAT {
    uint32_t SampleRate;
    uint16_t ChannelCount;
    uint16_t SampleFormat;
} IO_AUDIO_FORMAT;

#define IO_AUDIO_ENDPOINT_CAP_JACK_SENSE     0x00000001u
#define IO_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN  0x00000002u
#define IO_AUDIO_ENDPOINT_CAP_VALID_MASK     0x00000003u

// Bounds provider-advertised hardware gain ranges in millidecibels.
#define IO_AUDIO_HARDWARE_GAIN_LIMIT_MILLIDB 200000

// Distinguishes orderly teardown from surprise removal where registers may no longer be accessible.
typedef enum IO_AUDIO_REMOVAL_MODE {
    IoAudioOrderlyRemoval = 1,
    IoAudioSurpriseRemoval
} IO_AUDIO_REMOVAL_MODE;

#define IO_AUDIO_FAILURE_HARDWARE_INACCESSIBLE 0x00000001u
#define IO_AUDIO_FAILURE_VALID_MASK             0x00000001u

// Provider operations are invoked only at PASSIVE_LEVEL by the endpoint mixer thread.
typedef struct IO_AUDIO_PROVIDER_OPERATIONS {
    // Starts DMA only after the ring contains at least two prepared periods.
    // Failure must leave the provider stopped; Stop may still be called for partial-start cleanup.
    KSTATUS (*Start)(void* providerContext);
    // Stops DMA before unregister permits provider storage to be released.
    void (*Stop)(void* providerContext);
    // Applies endpoint gain and mute only with IO_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN.
    KSTATUS (*SetGain)(void* providerContext, int32_t gainMilliDb, bool muted);
} IO_AUDIO_PROVIDER_OPERATIONS;

// Registers one fixed-format render ring owned by a hardware provider.
// The provider must keep DMA stopped and the physical output muted until Start is called.
typedef struct IO_AUDIO_ENDPOINT_REGISTRATION {
    struct DEVICE_OBJECT* Device;
    IO_AUDIO_ENDPOINT_KIND Kind;
    uint32_t Capabilities;
    bool InitiallyAvailable;
    void* ProviderContext;
    IO_AUDIO_PROVIDER_OPERATIONS Operations;
    void* PeriodBuffer;
    size_t PeriodBufferBytes;
    uint32_t PeriodCount;
    uint32_t FramesPerPeriod;
    size_t PeriodStrideBytes;
    IO_AUDIO_FORMAT HardwareFormat;
    // Gain fields must be zero unless IO_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN is present.
    int32_t HardwareGainMinimumMilliDb;
    int32_t HardwareGainMaximumMilliDb;
    uint32_t HardwareGainStepMilliDb;
} IO_AUDIO_ENDPOINT_REGISTRATION;




__declspec(dllexport) KSTATUS IoAudioRegisterEndpoint(const IO_AUDIO_ENDPOINT_REGISTRATION* registration, IO_AUDIO_ENDPOINT** outEndpoint);
__declspec(dllexport) void IoAudioUnregisterEndpoint(IO_AUDIO_ENDPOINT* endpoint, IO_AUDIO_REMOVAL_MODE mode);
__declspec(dllexport) void IoAudioNotifyPeriod(IO_AUDIO_ENDPOINT* endpoint, uint32_t completedPeriodIndex, uint64_t presentedFrames, uint64_t hardwarePositionFrames, uint64_t interruptCount, uint64_t timestampTicks);
__declspec(dllexport) void IoAudioSetEndpointAvailable(IO_AUDIO_ENDPOINT* endpoint, bool available);
__declspec(dllexport) void IoAudioReportEndpointFailure(IO_AUDIO_ENDPOINT* endpoint, KSTATUS status, uint32_t flags);