 |
libwebsockets
Lightweight C library for HTML5 websockets
|
|
libwebsockets
Lightweight C library for HTML5 websockets
|
Go to the source code of this file.
Data Structures | |
| struct | lws_md_ctx |
| struct | lws_md_html |
Macros | |
| #define | LMD_LINE_MAX 8192 |
| #define | LMD_HOLD_MAX LMD_LINE_MAX |
| #define | LMD_INFO_MAX 32 |
| #define | LMD_NEST_MAX 24 |
| #define | LMD_TEXT_PIECE 256 |
| #define | LMD_URL_MAX 768 |
| #define | LMD_HTML_BUF 4096 |
Typedefs | |
| typedef lws_stateful_ret_t(* | lws_md_ev_cb) (void *user, lws_md_ev_t ev, lws_md_el_t el, unsigned int aux, const uint8_t *data, size_t len) |
| typedef struct lws_md_ctx | lws_md_ctx_t |
| typedef lws_stateful_ret_t(* | lws_md_write_cb) (void *user, const uint8_t *buf, size_t len) |
| typedef size_t(* | lws_md_resolve_cb) (void *user, int is_image, const char *url, size_t len, char *dest, size_t dest_len) |
| typedef struct lws_md_html | lws_md_html_t |
Enumerations | |
| enum | lws_md_el_t { LMD_EL_NONE , LMD_EL_H , LMD_EL_P , LMD_EL_BQ , LMD_EL_UL , LMD_EL_OL , LMD_EL_LI , LMD_EL_TABLE , LMD_EL_TR , LMD_EL_CELL , LMD_EL_HR , LMD_EL_CODE , LMD_EL_EM , LMD_EL_STRONG , LMD_EL_CS , LMD_EL_A , LMD_EL_IMG } |
| enum | lws_md_ev_t { LMD_EV_TEXT = 1 , LMD_EV_URL , LMD_EV_ALT , LMD_EV_INFO , LMD_EV_BEGIN , LMD_EV_END } |
Functions | |
| LWS_VISIBLE LWS_EXTERN int | lws_md_construct (lws_md_ctx_t *ctx, lws_md_ev_cb cb, void *user) |
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t | lws_md_parse (lws_md_ctx_t *ctx, const uint8_t **buf, size_t *len) |
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t | lws_md_finish (lws_md_ctx_t *ctx) |
| LWS_VISIBLE LWS_EXTERN int | lws_md_html_construct (lws_md_html_t *h, lws_md_write_cb wc, void *user, lws_md_resolve_cb resolve, void *resolve_user) |
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t | lws_md_html_event (void *user, lws_md_ev_t ev, lws_md_el_t el, unsigned int aux, const uint8_t *data, size_t len) |
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t | lws_md_html_close (lws_md_html_t *h) |
| struct lws_md_ctx |
lws_md_ctx_t: markdown renderer context
The context is allocated by the caller (its size is known from this header and is around 2 x LMD_LINE_MAX bytes) and requires no heap. Fields below user are private.
| Data Fields | ||
|---|---|---|
| lws_md_ev_cb | cb | |
| void * | user | |
| uint32_t | evseq | |
| uint32_t | evdone | |
| uint8_t | txn | |
| uint8_t | in_link | |
| uint8_t | para | |
| uint8_t | list | |
| uint8_t | li | |
| uint8_t | table | |
| uint8_t | hold | |
| uint8_t | bq | |
| uint8_t | code_ind | |
| uint8_t | fence | |
| uint8_t | fchr | |
| uint8_t | flen | |
| uint8_t | fmatch | |
| uint8_t | fbol | |
| uint8_t | fclose | |
| uint8_t | over | |
| uint8_t | fin_n | |
| uint8_t | fin_list[3+2 *LMD_NEST_MAX] | |
| uint32_t | llen | |
| uint32_t | hlen | |
| uint32_t | infolen | |
| char | info[LMD_INFO_MAX] | |
| char | line[LMD_LINE_MAX] | |
| char | holdb[LMD_HOLD_MAX] | |
| struct lws_md_html |
lws_md_html_t: stock event sink producing CSP-safe html markup
The context is allocated by the caller (its size is known from this header). Pass lws_md_html_event() as the lws_md event callback with this struct as the callback user pointer. Text, alt text and fence content are entity-escaped, urls are restricted to http(s), mailto, fragments, absolute paths and resolver output, and each event's markup is emitted atomically through the write callback so deferred events are retried without loss or duplication.
When lws was built with LWS_WITH_HL, fenced code blocks whose info string names a known language are streamed through the lws-hl tokenizer, so fenced code in readmes is highlighted exactly like the file views.
| Data Fields | ||
|---|---|---|
| lws_md_write_cb | wc | |
| void * | user | |
| lws_md_resolve_cb | resolve | |
| void * | resolve_user | |
| char | url[LMD_URL_MAX] | |
| size_t | url_len | |
| uint8_t | pending | |
| uint8_t | a_open | |
| uint8_t | alt_open | |
| uint8_t | code_open | |
| uint8_t | pre_done | |
| char | info[LMD_INFO_MAX] | |
| uint8_t | infolen | |
| char | buf[LMD_HTML_BUF] | |
| size_t | buflen | |
| #define LMD_HOLD_MAX LMD_LINE_MAX |
| typedef lws_stateful_ret_t(* lws_md_ev_cb) (void *user, lws_md_ev_t ev, lws_md_el_t el, unsigned int aux, const uint8_t *data, size_t len) |
lws_md_ev_cb() - markdown event sink callback
| user | opaque pointer set at lws_md_construct() |
| ev | the event kind |
| el | the element for LMD_EV_BEGIN / LMD_EV_END |
| aux | for LMD_EL_H, the heading level 1..6; for LMD_EL_CELL, bit 0 marks a header cell |
| data | the datum bytes for the data events, else NULL |
| len | the number of datum bytes at data |
Text, url, alt and info data are passed in pieces of at most LMD_TEXT_PIECE bytes. Ordering obligations: LMD_EV_INFO only appears between BEGIN CODE and its first LMD_EV_TEXT; LMD_EV_URL only appears after BEGIN A / BEGIN IMG and before the element text or END.
Return LWS_SRET_OK to continue, or a nonzero lws_stateful_ret_t (for example LWS_SRET_WANT_OUTPUT) to stop rendering at this event. Rendering resumes by re-issuing the same event on the next lws_md_parse() / lws_md_finish() call; accepted events are never re-issued.
| typedef struct lws_md_ctx lws_md_ctx_t |
lws_md_ctx_t: markdown renderer context
The context is allocated by the caller (its size is known from this header and is around 2 x LMD_LINE_MAX bytes) and requires no heap. Fields below user are private.
| typedef lws_stateful_ret_t(* lws_md_write_cb) (void *user, const uint8_t *buf, size_t len) |
| typedef size_t(* lws_md_resolve_cb) (void *user, int is_image, const char *url, size_t len, char *dest, size_t dest_len) |
lws_md_resolve_cb() - repo-relative url resolver callback
| user | opaque pointer set at lws_md_html_construct() |
| is_image | nonzero if the url is for an image |
| url | the relative url bytes from the markdown |
| len | the number of bytes at url |
| dest | buffer to write the resolved url into |
| dest_len | bytes available at dest |
The stock html sink gives relative urls to the resolver for rewriting (eg, to a git web ui path). Return the number of bytes written to dest, or 0 to leave the url as it appeared in the markdown.
| typedef struct lws_md_html lws_md_html_t |
lws_md_html_t: stock event sink producing CSP-safe html markup
The context is allocated by the caller (its size is known from this header). Pass lws_md_html_event() as the lws_md event callback with this struct as the callback user pointer. Text, alt text and fence content are entity-escaped, urls are restricted to http(s), mailto, fragments, absolute paths and resolver output, and each event's markup is emitted atomically through the write callback so deferred events are retried without loss or duplication.
When lws was built with LWS_WITH_HL, fenced code blocks whose info string names a known language are streamed through the lws-hl tokenizer, so fenced code in readmes is highlighted exactly like the file views.
| enum lws_md_el_t |
structural elements the driver can open and close
Definition at line 61 of file lws-md.h.
| enum lws_md_ev_t |
event kinds issued to the sink
| Enumerator | |
|---|---|
| LMD_EV_TEXT | data = text bytes, escaped by the sink |
| LMD_EV_URL | data = url datum for the open A / IMG |
| LMD_EV_ALT | data = alt text datum for the open IMG |
| LMD_EV_INFO | data = fence info string, after BEGIN CODE |
| LMD_EV_BEGIN | aux = lws_md_el_t (+ level / header bit) |
| LMD_EV_END | aux = lws_md_el_t |
Definition at line 86 of file lws-md.h.
| LWS_VISIBLE LWS_EXTERN int lws_md_construct | ( | lws_md_ctx_t * | ctx, |
| lws_md_ev_cb | cb, | ||
| void * | user ) |
lws_md_construct() - prepare an lws_md_ctx for use
| ctx | the markdown context to prepare |
| cb | the event sink callback |
| user | opaque pointer passed to the callback |
Prepares a caller-allocated context. Returns 0 for OK or nonzero on bad arguments.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t lws_md_parse | ( | lws_md_ctx_t * | ctx, |
| const uint8_t ** | buf, | ||
| size_t * | len ) |
lws_md_parse() - render a chunk of markdown to events
| ctx | the markdown context |
| buf | pointer to pointer to the start of the chunk |
| len | pointer to the number of bytes available at *buf |
Consumes as much of *buf as it can, issuing events to the sink. Fragments may be of any size including zero or one byte; line content is staged in the context so fragments need not align to lines. On return, *buf and *len are adjusted to describe the input that has not yet been consumed-and-emitted.
Returns LWS_SRET_OK if all input was consumed (keep calling with more input, or call lws_md_finish()); the nonzero return from the event sink if it deferred an event (call again later, with the same unconsumed input, to resume); or LWS_SRET_FATAL on bad arguments.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t lws_md_finish | ( | lws_md_ctx_t * | ctx | ) |
lws_md_finish() - signal end of input and close out open structure
| ctx | the markdown context |
Must be called once after the last input fragment. Any staged or held line is rendered, open fences, lists, tables, paragraphs and blockquotes are closed, and best-guess events are issued for constructs left unterminated by the end of input. If the event sink defers, the nonzero return is passed back and lws_md_finish() must be called again.
After a successful return the context is reset and may be reused for new input.
Returns LWS_SRET_OK, the nonzero return from the event sink, or LWS_SRET_FATAL on bad arguments.
| LWS_VISIBLE LWS_EXTERN int lws_md_html_construct | ( | lws_md_html_t * | h, |
| lws_md_write_cb | wc, | ||
| void * | user, | ||
| lws_md_resolve_cb | resolve, | ||
| void * | resolve_user ) |
lws_md_html_construct() - prepare an html emit context
| h | the html emit context to prepare |
| wc | the output write callback |
| user | opaque pointer passed to wc |
| resolve | relative url resolver, or NULL to pass relative urls through unmodified |
| resolve_user | opaque pointer passed to resolve |
Returns 0 for OK or nonzero on bad arguments.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t lws_md_html_event | ( | void * | user, |
| lws_md_ev_t | ev, | ||
| lws_md_el_t | el, | ||
| unsigned int | aux, | ||
| const uint8_t * | data, | ||
| size_t | len ) |
lws_md_html_event() - event sink for lws_md_parse() producing html markup
| user | pointer to the lws_md_html_t |
| ev | the event kind |
| el | the element for begin / end events |
| aux | heading level or header-cell flag |
| data | the datum bytes for data events |
| len | the number of datum bytes |
Emits each event's markup as a single write callback call where possible, so a nonzero return from the write callback defers the event and it is retried whole. Returns LWS_SRET_OK, or the nonzero return from the write callback.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t lws_md_html_close | ( | lws_md_html_t * | h | ) |
lws_md_html_close() - close anything dangling after end of input
| h | the html emit context |
Call after lws_md_finish() returned LWS_SRET_OK; the driver closes well-formed structure itself, so this only needs to act on malformed event sequences. Returns LWS_SRET_OK, or the nonzero return from the write callback (in which case, call it again).
1.18.0 
