// Native resource-service protocol and client helpers.

#pragma once

#include <stdint.h>
#include <ntlite/handle.h>
#include <ntlite/status.h>
#include <ntlite/string_view.h>

#define NTL_RESOURCE_PROTOCOL_VERSION 3u
#define NTL_RESOURCE_PATH_MAX 1024u
#define NTL_RESOURCE_NAME_MAX 255u

#define NTL_RESOURCE_FLAG_NONE           0x00000000u
#define NTL_RESOURCE_RESOLVE_FLAG_MODIFY 0x00000001u

#define NTL_RESOURCE_OP_LOOKUP              1u
#define NTL_RESOURCE_OP_QUERY               2u
#define NTL_RESOURCE_OP_BIND                3u
#define NTL_RESOURCE_OP_UNBIND              4u
#define NTL_RESOURCE_OP_RESOLVE             5u
#define NTL_RESOURCE_OP_ENUMERATE           6u
#define NTL_RESOURCE_OP_CREATE_DIRECTORY    7u
#define NTL_RESOURCE_OP_CREATE_SYMBOLIC_LINK 8u
#define NTL_RESOURCE_OP_CREATE_PUBLISHER     9u

#define NTL_RESOURCE_KIND_INVALID             0u
#define NTL_RESOURCE_KIND_CAPABILITY          1u
#define NTL_RESOURCE_KIND_VOLUME              2u
#define NTL_RESOURCE_KIND_DIRECTORY           3u
#define NTL_RESOURCE_KIND_DEVICE              4u
#define NTL_RESOURCE_KIND_NAMESPACE_DIRECTORY 5u
#define NTL_RESOURCE_KIND_SYMBOLIC_LINK       6u

// Request header followed by PathLength bytes of canonical native resource path and AuxLength operation-specific bytes.
typedef struct NTL_RESOURCE_REQUEST {
    uint32_t Size;
    uint32_t Version;
    uint32_t Operation;
    uint32_t Flags;
    SYS_RIGHTS Rights;
    SYS_RIGHTS ExportRights;
    uint32_t Kind;
    uint32_t PathLength;
    uint32_t AuxLength;
} NTL_RESOURCE_REQUEST;

// Every ordinary resource request receives one fixed-size reply. Enumeration appends NameLength bytes of one child name.
typedef struct NTL_RESOURCE_REPLY {
    uint32_t Size;
    uint32_t Version;
    uint32_t Operation;
    uint32_t Flags;
    KSTATUS Status;
    uint32_t Kind;
    uint32_t ResolvedLength;
    uint32_t NameLength;
} NTL_RESOURCE_REPLY;

// Stateless lexicographic enumeration cursor. Callers zero-initialize it before the first request.
typedef struct NTL_RESOURCE_ENUM_CURSOR {
    uint32_t NameLength;
    char Name[NTL_RESOURCE_NAME_MAX + 1u];
} NTL_RESOURCE_ENUM_CURSOR;

// One immediate child of an RSSRV namespace directory.
typedef struct NTL_RESOURCE_ENUM_ENTRY {
    uint32_t Kind;
    char Name[NTL_RESOURCE_NAME_MAX + 1u];
} NTL_RESOURCE_ENUM_ENTRY;

#if defined(NTL_SYSCALL_STATIC)
#define NTL_RESOURCE_API
#elif defined(NTL_SYSCALL_BUILD)
#define NTL_RESOURCE_API __declspec(dllexport)
#else
#define NTL_RESOURCE_API
#endif

// Connects one session to the globally registered resource service.
NTL_RESOURCE_API KSTATUS NtlResourceConnect(SYS_HANDLE* sessionOut);
NTL_RESOURCE_API KSTATUS NtlResourceOpenSystemRoot(SYS_RIGHTS desiredRights, SYS_HANDLE* handleOut);
// Creates an exact-path, bind/unbind-only publication listener through namespace-admin authority.
NTL_RESOURCE_API KSTATUS NtlResourceCreatePublisher(SYS_HANDLE adminSession, SYS_STRING_VIEW path,
                                                    SYS_HANDLE* listenerOut);
// Connects one session through an explicitly delegated resource-listener capability.
NTL_RESOURCE_API KSTATUS NtlResourceConnectListener(SYS_HANDLE listenerHandle, SYS_HANDLE* sessionOut);
// Resolves one canonical global resource name to an attenuated capability. Symbolic links are followed.
NTL_RESOURCE_API KSTATUS NtlResourceLookup(SYS_HANDLE session,
                                           SYS_STRING_VIEW path,
                                           SYS_RIGHTS desiredRights,
                                           SYS_HANDLE* handleOut);
// Queries the exact namespace node without following the final symbolic link.
NTL_RESOURCE_API KSTATUS NtlResourceQuery(SYS_HANDLE session,
                                          SYS_STRING_VIEW path,
                                          uint32_t* kindOut);
// Resolves the longest bound resource prefix of one canonical absolute path, following namespace symbolic links.
// ResolvedLength receives the byte length consumed from the caller's original resource path; the remaining
// path, after one optional '/', is relative to the returned volume/directory capability.
NTL_RESOURCE_API KSTATUS NtlResourceResolve(SYS_HANDLE session,
                                            SYS_STRING_VIEW path,
                                            uint32_t flags,
                                            SYS_HANDLE* rootHandleOut,
                                            uint32_t* kindOut,
                                            uint32_t* resolvedLengthOut);
// Enumerates immediate children in stable bytewise-name order using a caller-owned stateless cursor.
NTL_RESOURCE_API KSTATUS NtlResourceEnumerate(SYS_HANDLE session,
                                              SYS_STRING_VIEW directoryPath,
                                              NTL_RESOURCE_ENUM_CURSOR* cursor,
                                              NTL_RESOURCE_ENUM_ENTRY* entryOut);
// Creates one empty namespace directory through an administrative session.
NTL_RESOURCE_API KSTATUS NtlResourceCreateDirectory(SYS_HANDLE session, SYS_STRING_VIEW path);
// Creates one absolute namespace symbolic link through an administrative session.
NTL_RESOURCE_API KSTATUS NtlResourceCreateSymbolicLink(SYS_HANDLE session,
                                                        SYS_STRING_VIEW path,
                                                        SYS_STRING_VIEW target);
// Binds one capability into an administrative session with an explicit namespace-rights grant and export ceiling.
NTL_RESOURCE_API KSTATUS NtlResourceBind(SYS_HANDLE session,
                                         SYS_STRING_VIEW path,
                                         uint32_t kind,
                                         SYS_HANDLE resourceHandle,
                                         SYS_RIGHTS namespaceRights,
                                         SYS_RIGHTS exportRights);
// Removes one non-root namespace node through an administrative session. Namespace directories must be empty.
NTL_RESOURCE_API KSTATUS NtlResourceUnbind(SYS_HANDLE session, SYS_STRING_VIEW path);
// Disconnects and closes one resource session endpoint.
NTL_RESOURCE_API KSTATUS NtlResourceClose(SYS_HANDLE session);

#undef NTL_RESOURCE_API