// formsrv.h - Remote forms server library
//
// Loads .form files (protocol command sequences) and sends them to a
// remote client via a transport interface.  Receives EVENT messages
// from the client and dispatches them to a callback.

#ifndef FORMSRV_H
#define FORMSRV_H

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

// ---------------------------------------------------------------------------
// Transport interface
// ---------------------------------------------------------------------------

typedef struct {
    // Read a complete message into buf.  Returns bytes read, 0 if no
    // message is available.  Must not block.
    int  (*readMessage)(char *buf, int32_t maxLen, void *ctx);

    // Write a null-terminated message string.  Transport adds framing
    // (e.g., CR+LF for serial).
    void (*writeMessage)(const char *buf, void *ctx);

    // Opaque context pointer passed to readMessage/writeMessage.
    void *ctx;
} FormTransportT;

// ---------------------------------------------------------------------------
// Event callback
// ---------------------------------------------------------------------------

typedef void (*EventCallbackT)(int32_t formId, int32_t ctrlId,
                               const char *eventName, const char *data,
                               void *userData);

// ---------------------------------------------------------------------------
// Server handle (opaque)
// ---------------------------------------------------------------------------

typedef struct FormServerS FormServerT;

// ---------------------------------------------------------------------------
// API
// ---------------------------------------------------------------------------

FormServerT *formServerCreate(FormTransportT *transport);
void         formServerDestroy(FormServerT *server);

// Load a .form file into the server's form store.  Returns the form ID
// parsed from the first FORM.CREATE line, or -1 on error.
int32_t      formServerLoadFile(FormServerT *server, const char *path);

// Send all commands for a loaded form to the client.
void         formServerSendForm(FormServerT *server, int32_t formId);

// Send FORM.SHOW / FORM.HIDE / FORM.DESTROY commands.
void         formServerShowForm(FormServerT *server, int32_t formId);
void         formServerHideForm(FormServerT *server, int32_t formId);
void         formServerDestroyForm(FormServerT *server, int32_t formId);

// Send a CTRL.SET command to update a property on a control.
void         formServerSetProp(FormServerT *server, int32_t formId,
                               int32_t ctrlId, const char *prop,
                               const char *value);

// Send an EVENT.BIND command.
void         formServerBindEvent(FormServerT *server, int32_t formId,
                                 int32_t ctrlId, const char *eventName);

// Send an EVENT.UNBIND command.
void         formServerUnbindEvent(FormServerT *server, int32_t formId,
                                   int32_t ctrlId, const char *eventName);

// Set the callback for incoming events.
void         formServerSetEventCallback(FormServerT *server,
                                        EventCallbackT cb, void *userData);

// Poll for one incoming event.  Returns true if an event was processed.
bool         formServerPollEvent(FormServerT *server);

#endif // FORMSRV_H