json-app.h

Go to the documentation of this file.

#ifndef JSON_APP_API_H_INCLUDED
#define JSON_APP_API_H_INCLUDED

/**
 * @file
 * @brief JSON application API
 *
 * \todo TODO: XXX: Documentation to be translated and updated.
 */

#include <stdint.h>
#include <stdbool.h>
#include <http/types.h>
#include <toc/toc-app.h>

/** @cond INTERNAL */
#ifdef DEBUG
#include <lib/assert.h>
#define JSON_APP_PARANOID(x) assert(x)
#else
#define JSON_APP_PARANOID(x)
#endif
/** @endcond */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \defgroup Json application
 * \ingroup http
 * \{
 */

/**
 * ID Base for JSON TOC requests
 */
#define JSON_BASE_ID      (0x100)

/**
 * @brief Lett string gjennomføring
 *
 * I stedet av vanlig "C" stringer bruker JSON pasrer seq_t
 * primitive, som består av et par av en peker på en string
 * og lenge av stringen. Formålet er å redusere lenge beregning
 * og å bruke "levende" pekerene direkte i TCP buffere.
 *
 * @note Stringen tiny_seq_t peker på er ikke null-terminert.
 *
 * @param Ptr peker på string
 * @param Len lenge av stringen
 */
struct tiny_seq_t
{
  char *Ptr;
  uint8_t Len;
};

/**
 * @brief Enumen settes typen på generel verdi.
 */
enum val_type_t
{
  VAL_TYPE_STRING = 0,  /**< Verdien er en tiny_seq_t           */
  VAL_TYPE_INT,         /**< Verdien er en 32-bit integer       */
  VAL_TYPE_BOOL,        /**< Verdien er boolean                 */
  VAL_TYPE_STRUCT,      /**< Struktur, brukes bare i TOC tabell */
#ifdef JSON_APP_HAS_FLOAT
  VAL_TYPE_FLOAT,       /**< Verdien er en float                */
#endif
  VAL_TYPE_UNKNOWN,     /**< Reservert                          */
};

/**
 * @brief Generel verdi
 *
 * Parseren sjekker typer av data gått fra nettleseren og
 * konverterer dem følgende toc_t spesifikasjonen.
 * val_t strukturen brukes til å holde verdi av forskelige
 * typer.
 *
 * Applikasjonen skal ikke bruke intern unionen i denne struktur
 * direkte. @ref JsonValAsString, @ref JsonValAsInt,
 * @ref JsonValAsFloat, @ref JsonValAsBool må brukes i stedet.
 *
 * @param Type type av verdi
 * @param u intern verdi
 */
struct val_t
{
  /** @cond INTERNAL */
  union
  {
    struct tiny_seq_t AsString;
    int AsInt;
#ifdef JSON_APP_HAS_FLOAT
    float AsFloat;
#endif
    int AsBool;
  } u;
  /** @endcond */
  uint8_t Type;
};

/**
 * @brief val_t tilgangsmetod, gir string verdi
 *
 * @param Val generel verdi
 * @return string verdi
 */
static inline const struct tiny_seq_t *JsonValAsString(const struct val_t *Val)
{
  JSON_APP_PARANOID(Val->Type == VAL_TYPE_STRING);
  return &Val->u.AsString;
}

/**
 * @brief val_t tilgangsmetod, gir integer verdi
 *
 * @param Val generel verdi
 * @return integer verdi
 */
static inline int JsonValAsInt(const struct val_t *Val)
{
  JSON_APP_PARANOID(Val->Type == VAL_TYPE_INT);
  return Val->u.AsInt;
}

#ifdef JSON_APP_HAS_FLOAT
/**
 * @brief val_t tilgangsmetod, gir float verdi
 *
 * @param Val generel verdi
 * @return float verdi
 */
static inline float JsonValAsFloat(const struct val_t *Val)
{
  JSON_APP_PARANOID(Val->Type == VAL_TYPE_FLOAT);
  return Val->u.AsFloat;
}
#endif

/**
 * @brief val_t tilgangsmetod, gir bool verdi
 *
 * @param Val generel verdi
 * @return bool verdi
 */
static inline int JsonValAsBool(const struct val_t *Val)
{
  JSON_APP_PARANOID(Val->Type == VAL_TYPE_BOOL);
  return Val->u.AsBool;
}

/**
 * Checks if the parameter is an array.
 */
static inline bool JsonTocIsArray(const struct toc_t *Entry)
{
  return (Entry->Count > 1 || (Entry->Flags & TOC_FLAG_VIRTUAL));
}

/**
 * @brief Gir "table of content" (TOC).
 *
 * Tabellen definerer de parameterene applikasjon kan kontrollere.
 * JSON aldri skrives noe i tabellen, så den kan ligge i flash minne.
 *
 * @param Ptr applikasjonen må settes (*TocPtr) pekeren på TOC-tabel
 */
extern void JsonAppGetToc(struct toc_blob_t *Ptr);

/**
 * @brief "get" opphandler.
 *
 * JSON engine kalles funksjonen til å svare på "get" spørsmål.
 *
 * @param State peker på brukerdata.
 * @param Id indeks av parameteren i TOC tabellen.
 * @param Index indeks av parameter i tabell (gjelder bare TOC_FLAG_ARRAY-markert parametre)
 * @param Val generel verdi applikasjon må fille ut.
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke errno.h semantik.
 */
extern int JsonAppGet(struct toc_var_context_t *State, int Id, int Index, struct val_t *Val);

/**
 * @brief beginnelse av "get" opphandler for structur.
 *
 * JSON engine kalles funksjonen til å informere at den skal lese en struktur.
 *
 * @param State peker på brukerdata.
 * @param Id indeks av parameteren i TOC tabellen.
 * @param Index indeks av parameter i tabell (gjelder bare TOC_FLAG_ARRAY-markert parametre)
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppGetStructBegin(struct toc_var_context_t *State, int Id, int Index);

/**
 * @brief slutt av "get" opphandler for structur.
 *
 * JSON engine kalles funksjonen til å informere at den sluttet med strukturen.
 *
 * @param State peker på brukerdata.
 * @param Id indeks av parameteren i TOC tabellen.
 * @param Index indeks av parameter i tabell (gjelder bare TOC_FLAG_ARRAY-markert parametre)
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppGetStructEnd(struct toc_var_context_t *State, int Id, int Index);

/**
 * @brief "set" opphandler.
 *
 * JSON engine kalles funksjonen til å handle "set" kommand.
 *
 * @param State peker på brukerdata.
 * @param Id indeks av parameteren i TOC tabellen.
 * @param Index indeks av parameter i tabell (gjelder bare TOC_FLAG_ARRAY-markert parametre)
 * @param Val generel verdi applikasjon må sette. Applikasjonen må
 *   også sette levende verdien i val hvis det trenges.
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppSet(struct toc_var_context_t *State, int Id, int Index, struct val_t *Val);

/**
 * @brief beginnelse av "set" opphandler for structur.
 *
 * JSON engine kalles funksjonen til å informere at den skal skrive en struktur.
 *
 * @param State peker på brukerdata.
 * @param Id indeks av parameteren i TOC tabellen.
 * @param Index indeks av parameter i tabell (gjelder bare TOC_FLAG_ARRAY-markert parametre)
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppSetStructBegin(struct toc_var_context_t *State, int Id, int Index);

/**
 * @brief slutt av "set" opphandler for structur.
 *
 * JSON engine kalles funksjonen til å informere at den sluttet med strukturen.
 *
 * @param State peker på brukerdata.
 * @param Id indeks av parameteren i TOC tabellen.
 * @param Index indeks av parameter i tabell (gjelder bare TOC_FLAG_ARRAY-markert parametre)
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppSetStructEnd(struct toc_var_context_t *State, int Id, int Index);

/**
 * @brief Beginnelse av "file push" operasjon.
 *
 * JSON engine kalles funksjonen som en indikasjon av fil opdatering kommand.
 *
 * @param State peker på brukerdata.
 * @param File navnet av filen. Faktiske det er "query" delen av HTTP request.
 * @param Size totalt størrelse av filen.
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppPushBegin(struct toc_file_context_t *State, uint8_t Id, const char *File, unsigned Size);

/**
 * @brief Opdatere en porsjon av fil i "file push" operasjon.
 *
 * JSON engine kalles funksjonen til å lagre en del (fragment) av fil.
 *
 * @param State peker på brukerdata.
 * @param Pos skrive posisjon i filen.
 * @param Size størrelse av fragmenten.
 * @param Data fragmenten til å lagre..
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppPush(struct toc_file_context_t *State, unsigned Pos, unsigned Size, const void *Data);

/**
 * @brief "file push" operasjon er ferdig.
 *
 * JSON engine kalles funksjonen som en indikasjon at fil opdatering kommand er ferdig.
 *
 * @param State peker på brukerdata.
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppPushEnd(struct toc_file_context_t *State);

/**
 * @brief Beginnelse av "file pull" operasjon.
 *
 * JSON engine kalles funksjonen som en indikasjon av fil lesering kommand.
 *
 * @param State peker på brukerdata.
 * @param Id    //!< TODO document it.
 * @param       File navnet av filen. Faktiske det er "query" delen av HTTP request.
 * @return fil størrelse som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppPullBegin(struct toc_file_context_t *State, uint8_t Id, const char *File);

/**
 * @brief Lese en porsjon av fil i "file pull" operasjon.
 *
 * JSON engine kalles funksjonen til å lese en del (fragment) av fil.
 *
 * @param State peker på brukerdata.
 * @param Pos lese posisjon i filen.
 * @param Size størrelse av fragmenten.
 * @param Data applikasjon må kopiere data fragmenten der.
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppPull(struct toc_file_context_t *State, unsigned Pos, unsigned Size, void *Data);

/**
 * @brief "file pull" operasjon er ferdig.
 *
 * JSON engine kalles funksjonen som en indikasjon at fil lesning kommand er ferdig.
 *
 * @param State peker på brukerdata.
 * @return 0 som indikasjon av suksess.
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppPullEnd(struct toc_file_context_t *State);

/**
 * @brief slutt av alle opphandlere for structurer.
 *
 * JSON engine kalles funksjonen til å informere at prosessering av en rekvest er ferdig.
 *
 * @return negativsk errno som indikasjon av en fail. Bruke `errno.h` semantik.
 */
extern int JsonAppClear();

/**
 * @brief En mobil klient har tilkoblet på serveren.
 *
 * JSON engine kalles funksjonen til å informere at en klient har tilkoblet.
 */
extern void JsonAppClientConnect();

/**
 * @brief En mobil klienten var frakoblet fra serveren.
 *
 * JSON engine kalles funksjonen til å informere at en klient var frakoblet.
 */
extern void JsonAppClientDisconnect();

/** \} */

#ifdef __cplusplus
}
#endif

#endif