{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1752665903, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"d88af54b5d7379745dcd8f1ca9300989", "commit": {"type":"commit", "time": 1580825778, "time_ofs": 0, "oid_tree": { "oid": "41b4bc2eea43dce080640a00e5469ed7f338234f", "alias": []}, "oid":{ "oid": "414516cad45d4942e610647cb23fff5113693622", "alias": []}, "msg": "lws_system: sync README.md to recent additions", "sig_commit": { "git_time": { "time": 1580825778, "offset": 0 }, "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" }, "sig_author": { "git_time": { "time": 1579623544, "offset": 0 }, "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" }}, "body": "lws_system: sync README.md to recent additions" , "diff": "diff --git a/READMEs/README.lws_system.md b/READMEs/README.lws_system.md\nindex 499d0ac..05afa47 100644\n--- a/READMEs/README.lws_system.md\n+++ b/READMEs/README.lws_system.md\n@@ -7,51 +7,179 @@ See `include/libwebsockets/lws-system.h` for function and object prototypes.\n `lws_system` allows you to set a `system_ops` struct at context creation time,\n which can write up some function callbacks for system integration. The goal\n is the user code calls these by getting the ops struct pointer from the\n-context using `lws_system_get_ops(context)` or `lws_system_get_info()` and\n-so does not spread system dependencies around the user code.\n+context using `lws_system_get_ops(context)` and so does not spread system\n+dependencies around the user code, making it directly usable on completely\n+different platforms.\n \n ```\n typedef struct lws_system_ops {\n-\tint (*get_info)(lws_system_item_t i, lws_system_arg_t *arg);\n \tint (*reboot)(void);\n \tint (*set_clock)(lws_usec_t us);\n-\tint (*auth)(int idx, uint8_t *buf, size_t *plen, int set);\n+\tint (*attach)(struct lws_context *context, int tsi, lws_attach_cb_t cb,\n+\t\t lws_system_states_t state, void *opaque,\n+\t\t struct lws_attach_item **get);\n } lws_system_ops_t;\n ```\n \n |Item|Meaning|\n |---|---|\n-|`(*get_info)()`|Retreive system information in a standardized way|\n |`(*reboot)()`|Reboot the system|\n |`(*set_clock)()`|Set the system clock|\n-|`(*auth)()`|Set and Get dynamic auth strings|\n+|`(*attach)()`|Request an event loop callback from another thread context|\n \n-### `get_info`\n+### `reboot`\n+\n+Reboots the device\n+\n+### `set_clock`\n+\n+Set the system clock to us-resolution Unix time in seconds\n+\n+### `attach`\n+\n+Request a callback from the event loop from a foreign thread. This is used, for\n+example, for foreign threads to set up their event loop activity in their\n+callback, and eg, exit once it is done, with their event loop activity able to\n+continue wholly from the lws event loop thread and stack context.\n+\n+## Foreign thread `attach` architecture\n+\n+When lws is started, it should define an `lws_system_ops_t` at context creation\n+time which defines its `.attach` handler. In the `.attach` handler\n+implementation, it should perform platform-specific locking around a call to\n+`__lws_system_attach()`, a public lws api that actually queues the callback\n+request and does the main work. The platform-specific wrapper is just there to\n+do the locking so multiple calls from different threads to the `.attach()`\n+operation can't conflict.\n+\n+User code can indicate it wants a callback from the lws event loop like this:\n+\n+```\n+lws_system_get_ops(context)-\u003eattach(context, tsi, cb, state, opaque, NULL)\n+```\n+\n+`context` is a pointer to the lws_context, `tsi` is normally 0, `cb` is the user\n+callback in the form \n \n-This allows the user code to query some common system values without introducing\n-any system dependencies in the code itself. The defined item numbers are\n+```\n+void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque);\n+```\n+\n+`state` is the `lws_system` state we should have reached before performing the\n+callback (usually, `LWS_SYSTATE_OPERATIONAL`), and `opaque` is a user pointer that\n+will be passed into the callback.\n+\n+`cb` will normally want to create scheduled events and set up lws network-related\n+activity from the event loop thread and stack context.\n+\n+Once the event loop callback has been booked by calling this api, the thread and\n+its stack context that booked it may be freed. It will be called back and can\n+continue operations from the lws event loop thread and stack context. For that\n+reason, if `opaque` is needed it will usually point to something on the heap,\n+since the stack context active at the time the callback was booked may be long\n+dead by the time of the callback. \n+\n+See ./lib/system/README.md for more details.\n+\n+## `lws_system` blobs\n+\n+\u0022Blobs\u0022 are arbitrary binary objects that have a total length. Lws lets you set\n+them in two ways\n+\n+ - \u0022directly\u0022, by pointing to them, which has no heap implication\n+\n+ - \u0022heap\u0022, by adding one or more arbitrary chunk to a chained heap object\n+\n+In the \u0022heap\u0022 case, it can be incrementally defined and the blob doesn't all\n+have to be declared at once.\n+\n+For read, the same api allows you to read all or part of the blob into a user\n+buffer. \n+\n+The following kinds of blob are defined \n \n |Item|Meaning|\n |---|---|\n-|`LWS_SYSI_HRS_DEVICE_MODEL`|String describing device model|\n-|`LWS_SYSI_HRS_DEVICE_SERIAL`|String for the device serial number|\n-|`LWS_SYSI_HRS_FIRMWARE_VERSION`|String describing the current firmware version|\n-|`LWS_SYSI_HRS_NTP_SERVER`|String with the ntp server address (defaults to pool.ntp.org)|\n+|`LWS_SYSBLOB_TYPE_AUTH`|Auth-related blob 1, typically a registration token|\n+|`LWS_SYSBLOB_TYPE_AUTH + 1`|Auth-related blob 2, typically an auth token|\n+|`LWS_SYSBLOB_TYPE_CLIENT_CERT_DER`|Client cert public part|\n+|`LWS_SYSBLOB_TYPE_CLIENT_KEY_DER`|Client cert key part|\n+|`LWS_SYSBLOB_TYPE_DEVICE_SERIAL`|Arbitrary device serial number|\n+|`LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION`|Arbitrary firmware version|\n+|`LWS_SYSBLOB_TYPE_DEVICE_TYPE`|Arbitrary Device Type identifier|\n+|`LWS_SYSBLOB_TYPE_NTP_SERVER`|String with the ntp server address (defaults to pool.ntp.org)|\n \n-### `reboot`\n+### Blob handle api\n \n-Reboots the device\n+Returns an object representing the blob for a particular type (listed above)\n \n-### `set_clock`\n+```\n+lws_system_blob_t *\n+lws_system_get_blob(struct lws_context *context, lws_system_blob_item_t type,\n+ int idx);\n+```\n \n-Set the system clock to us-resolution Unix time in seconds\n+### Blob Setting apis\n+\n+Sets the blob to point length `len` at `ptr`. No heap allocation is used.\n+\n+```\n+void\n+lws_system_blob_direct_set(lws_system_blob_t *b, const uint8_t *ptr, size_t len);\n+```\n+\n+Allocates and copied `len` bytes from `buf` into heap and chains it on the end of\n+any existing.\n+\n+```\n+int\n+lws_system_blob_heap_append(lws_system_blob_t *b, const uint8_t *buf, size_t len)\n+```\n+\n+Remove any content from the blob, freeing it if it was on the heap\n+\n+```\n+void\n+lws_system_blob_heap_empty(lws_system_blob_t *b)\n+```\n+\n+### Blob getting apis\n \n-### `auth`\n+Get the total size of the blob (ie, if on the heap, the aggreate size of all the\n+chunks that were appeneded)\n \n-Get and set generic binary auth blobs so the rest of lws can access them\n-independently.\n+```\n+size_t\n+lws_system_blob_get_size(lws_system_blob_t *b)\n+```\n+\n+Copy part or all of the blob starting at offset ofs into a user buffer at buf.\n+`*len` should be the length of the user buffer on entry, on exit it's set to\n+the used extent of `buf`. This works the same whether the bob is a direct pointer\n+or on the heap.\n+\n+```\n+int\n+lws_system_blob_get(lws_system_blob_t *b, uint8_t *buf, size_t *len, size_t ofs)\n+```\n+\n+If you know that the blob was handled as a single direct pointer, or a single\n+allocation, you can get a pointer to it without copying using this.\n+\n+```\n+int\n+lws_system_blob_get_single_ptr(lws_system_blob_t *b, const uint8_t **ptr)\n+```\n+\n+### Blob destroy api\n+\n+Deallocates any heap allocation for the blob\n+\n+```\n+void\n+lws_system_blob_destroy(lws_system_blob_t *b)\n+```\n \n-Call with `set` 0 to get and 1 to set the auth code with the index `idx`. \n \n ## System state and notifiers\n \ndiff --git a/include/libwebsockets/lws-system.h b/include/libwebsockets/lws-system.h\nindex f6bdb0d..61ddf3b 100644\n--- a/include/libwebsockets/lws-system.h\n+++ b/include/libwebsockets/lws-system.h\n@@ -1,7 +1,7 @@\n /*\n * libwebsockets - small server side websockets and web server implementation\n *\n- * Copyright (C) 2010 - 2019 Andy Green \u003candy@warmcat.com\u003e\n+ * Copyright (C) 2010 - 2020 Andy Green \u003candy@warmcat.com\u003e\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \u0022Software\u0022), to\n","s":{"c":1752665903,"u": 2061}} ],"g": 4225,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 0, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}