第一次提交

CCU_design.dot

@@ -0,0 +1,82 @@
+
+digraph CompanyHierarchy {
+    // 关键配置：指定支持中文的字体
+    graph [fontname="SimHei, Microsoft YaHei, Heiti TC"];
+    node [fontname="SimHei, Microsoft YaHei, Heiti TC", shape=box, style="filled,rounded", color="#4a86e8", fillcolor="#e6f2ff"];
+    edge [fontname="SimHei, Microsoft YaHei, Heiti TC", color="#666666", arrowhead="normal"];
+    
+    // 布局方向
+    rankdir= LR;
+    
+    // 节点定义
+    T0 [label="SYSTGBTM", fillcolor="#b3d1ff", fontsize=12, fontweight="bold"];
+    
+    OCPP [label="OCPP16"];
+    TCU [label="QTTCU"];
+    PCU [label="PCU"];
+    CCU [label="CCU"];
+    SECC [label="SECC"];
+    GBT [label="GBT27930"];
+    V2G [label="V2GContext"];
+    
+    OCPP1 [label="start_transation"];
+    OCPP2 [label="stop_transaction"];
+    OCPP3 [label="authorizate"];
+    OCPP4 [label="report_status"];
+    OCPP5 [label="report_meter_values"];
+
+    CCU1 [label="checkIO"];
+    CCU2 [label="checkGUNA"];
+    CCU3 [label="checkGUNB"];
+    CCU4 [label="checkMeters"];
+    CCU5 [label="checkGround"];
+
+    TCU1 [label="startup"];
+    TCU2 [label="shutdown"];
+    TCU3 [label="report_GUNInfo"];
+    TCU4 [label="report_ChargingInfo"];
+
+    V2G1 [label="startup_slac"];
+    V2G2 [label="startup_sdp"];
+    V2G3 [label="startup_listen"];
+    V2G4 [label="shutdown"];
+    V2G5 [label="authrizate"];
+    V2G6 [label="cablecheck"];
+    V2G7 [label="precharge"];
+    V2G8 [label="charging"];
+    V2G9 [label="stopping"];
+    
+    PCU1 [label="request_power"];
+    PCU2 [label="report_state_error"];
+    PCU3 [label="report_K1K2_state"];
+
+    SECC1 [label="startup"];
+    SECC2 [label="shutdown"];
+    SECC3 [label="authorizate"];
+    SECC4 [label="start_transation"];
+    SECC5 [label="stop_transation"];
+    SECC6 [label="report_meter_values"];
+    
+    GBT1 [label="trylock"];
+    GBT2 [label="handshake"];
+    GBT3 [label="insulation"];
+    GBT4 [label="precharge"];
+    GBT5 [label="charging"];
+    GBT6 [label="finshing"];
+
+    // 层次关系
+    T0 -> {OCPP, TCU, PCU, SECC, GBT, V2G, CCU};
+    OCPP -> {OCPP1, OCPP2, OCPP3, OCPP4, OCPP5};
+    TCU -> {TCU1, TCU2, TCU3, TCU4};
+    PCU -> {PCU1, PCU2, PCU3};
+    SECC -> {SECC1, SECC2, SECC3, SECC4, SECC5, SECC6};
+    GBT -> {GBT1, GBT2, GBT3, GBT4, GBT5, GBT6};
+    V2G -> {V2G1, V2G2, V2G3, V2G4, V2G5, V2G6, V2G7, V2G8, V2G9}
+    CCU -> {CCU1, CCU2, CCU3, CCU4, CCU5}
+    
+    // 标题设置（同样指定字体）
+    labelloc="t";
+    label="CCU detail";
+    fontsize=16;
+    fontweight="bold";
+}

CMakeLists.txt

@@ -0,0 +1,60 @@
+cmake_minimum_required(VERSION 3.10)  # 必须
+set(CMAKE_CXX_STANDARD 14)	# C++14
+
+project(app_CCU)  #工程名,比如APP_TCU，APP_CCU，APP_PCU
+
+# set(CMAKE_ROOTFS /home/sunjt/myir-am62x/oe-layersetup/build/arago-tmp-default-glibc/work/myd_am62x-oe-linux/myir-image-full/1.0-r0_edgeai_0/recipe-sysroot-native)
+# include_directories(${CMAKE_ROOTFS}/usr/include) # 头文件目录
+# link_directories(${CMAKE_ROOTFS}/usr/lib)
+
+include_directories(${CMAKE_SYSROOT}/usr/local/include) # 头文件目录
+link_directories(${CMAKE_SYSROOT}/usr/local/lib/) # 链接库目录
+
+include_directories(${PROJECT_SOURCE_DIR}/include)
+include_directories(${PROJECT_SOURCE_DIR}/src)
+include_directories(${PROJECT_SOURCE_DIR}/src/comm)
+include_directories(${PROJECT_SOURCE_DIR}/src/bsp)
+include_directories(${PROJECT_SOURCE_DIR}/src/GUIHMI)
+include_directories(${PROJECT_SOURCE_DIR}/src/OCPP16)
+include_directories(${PROJECT_SOURCE_DIR}/src/GBT2015)
+include_directories(${PROJECT_SOURCE_DIR}/src/CCS2015)
+include_directories(${PROJECT_SOURCE_DIR}/src/CCS2015/din)
+include_directories(${PROJECT_SOURCE_DIR}/src/CCS2015/iso)
+include_directories(${PROJECT_SOURCE_DIR}/src/CCS2015/slac)
+include_directories(${PROJECT_SOURCE_DIR}/src/CCS2015/common)
+include_directories(${PROJECT_SOURCE_DIR}/src/CCS2015/app_handshake)
+include_directories(${PROJECT_SOURCE_DIR}/src/HW12)
+include_directories(${PROJECT_SOURCE_DIR}/src/TCX2)
+
+link_directories(${PROJECT_SOURCE_DIR}/lib)
+
+aux_source_directory(./src SRCS) # 源文件
+aux_source_directory(./src/comm SRCS)
+aux_source_directory(./src/bsp SRCS)
+aux_source_directory(./src/GUIHMI SRCS)
+aux_source_directory(./src/OCPP16 SRCS)
+aux_source_directory(./src/GBT2015 SRCS)
+aux_source_directory(./src/CCS2015 SRCS)
+aux_source_directory(./src/CCS2015/din SRCS)
+aux_source_directory(./src/CCS2015/iso SRCS)
+aux_source_directory(./src/CCS2015/slac SRCS)
+aux_source_directory(./src/CCS2015/common SRCS)
+aux_source_directory(./src/CCS2015/app_handshake SRCS)
+aux_source_directory(./src/HW12 SRCS)
+aux_source_directory(./src/TCX2 SRCS)
+
+set(CMAKE_C_FLAGS "-O1 -g") # 设置C工程的 CFLAGS
+set(CMAKE_CXX_FLAGS "-O0 -Werror -g") # 设置C++ 工程的 CXX_FLAGS
+
+add_executable(${PROJECT_NAME} ${SRCS}) # 生成可执行文件，这里程序名即为功能名
+
+target_link_libraries(${PROJECT_NAME} gpiod ssl crypto pthread m dl) # 链接库
+
+# 下面使用install作为项目打包使用
+set(CMAKE_INSTALL_PREFIX ./bin)  # 自定义安装目录，打包使用
+install(TARGETS ${PROJECT_NAME} RUNTIME DESTINATION bin) # 打包二进制文件
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS TRUE)
+
+set(CONFIGS ${PROJECT_SOURCE_DIR}/etc/ccu_config.json) 
+install(FILES ${CONFIGS} DESTINATION config) # 打包配置文件

Makefile

@@ -0,0 +1,67 @@
+PWDDIR  = $(shell pwd)
+OBJDIR  = $(PWDDIR)/../obj
+BINDIR	= $(PWDDIR)/../bin
+LIBDIR  = $(PWDDIR)/../lib
+
+TARGET = $(shell basename $(PWDDIR))
+
+AS      = as
+CC      = gcc
+CPP     = g++
+AR      = ar
+LD      = ld
+
+OBJCOPY = objcopy
+OBJDUMP = objdump
+MAKE    = make
+
+ASFLAGS  = -D -g -I$(PWDDIR)
+CCFLAGS  = -O3 -c -ffunction-sections -fdata-sections -I$(PWDDIR)
+CPPFLAGS = -O3 -c -ffunction-sections -fdata-sections -I$(PWDDIR)
+ARFLAGS  = rcsv
+LDFLAGS  = -L$(LIBDIR) -lm -lc
+
+EXCNAME = $(TARGET)
+LIBNAME = lib$(TARGET)
+DLLNAME = dll$(TARGET)
+
+ASFILES  = $(wildcard date/*.S)
+CCFILES  = $(wildcard date/*.c)
+CPPFILES = $(wildcard date/*.cpp)
+
+ASOBJS = $(patsubst %.c, $(OBJDIR)/%.o, $(ASFILES))
+CCOBJS = $(patsubst %.c, $(OBJDIR)/%.o, $(CCFILES))
+CPPOBJS = $(patsubst %.cpp, $(OBJDIR)/%.o, $(CPPFILES))
+
+ALLOBJS = $(ASOBJS)  $(CCOBJS)  $(CPPOBJS)
+
+
+all:$(ALLOBJS)
+	@echo "TARGET = $(TARGET)"
+	@echo "PWDDIR = $(PWDDIR)"
+	@echo "CPPFILES = $(CPPFILES)"
+	# $(MAKE) -C ccvui
+	# $(MAKE) -C hardware
+	$(AR) $(ARFLAGS) $(LIBDIR)/$(LIBNAME).a $(ALLOBJS)
+	# $(LD) $(LDFLAGS) -o $(BINDIR)/$(EXCNAME).elf $(ALLOBJS)
+
+.PHONY:$(LIBNAME)
+$(LIBNAME):$(ALLOBJS)
+	$(AR) $(ARFLAGS) $(LIBDIR)/$(LIBNAME).a $(ALLOBJS)
+
+.PHONY:$(DLLNAME)
+$(DLLNAME):$(ALLOBJS)
+	$(CC) $(LDFLAGS) $(ALLOBJS) -o $(BINDIR)/$(DLLNAME).so
+	
+$(OBJDIR)/%.o : %.S
+	$(AS) $(ASFLAGS) $< -o $@
+	
+$(OBJDIR)/%.o : %.c
+	$(CC) $(CCFLAGS) $< -o $@
+	
+$(OBJDIR)/%.o : %.cpp
+	$(CPP) $(CPPFLAGS) $< -o $@
+
+.PHONY : clean
+clean:
+	rm -f $(BINDIR)/*app_*.bin  $(BINDIR)/*.elf $(BINDIR)/*.dis $(BINDIR)/*.map  $(BINDIR)/*.c $(OBJDIR)/*.o

YT800KW.dot

@@ -0,0 +1,65 @@
+
+digraph CompanyHierarchy {
+    // 关键配置：指定支持中文的字体
+    graph [fontname="SimHei, Microsoft YaHei, Heiti TC"];
+    node [fontname="SimHei, Microsoft YaHei, Heiti TC", shape=box, style="filled,rounded", color="#4a86e8", fillcolor="#e6f2ff"];
+    edge [fontname="SimHei, Microsoft YaHei, Heiti TC", color="#666666", arrowhead="normal"];
+    
+    // 布局方向
+    rankdir= LR;
+    
+    // 节点定义
+    T0 [label="YT800KW", fillcolor="#b3d1ff", fontsize=12, fontweight="bold"];
+    
+    T1 [label="硬件"];
+    T2 [label="软件"];
+    T3 [label="云平台"];
+    T4 [label="功率管理"];
+    T5 [label="价格管理"];
+    
+    A1 [label="单板电路板"];
+    A2 [label="可搭建主从备份"];
+    A3 [label="兼容一体桩和端机，充电堆主机"];
+    A4 [label="集成TCU显示接口"];
+    A5 [label="集成GB车桩通信接口"];
+    A5 [label="集成欧标，美标，特斯拉车桩通信接口"];
+    A6 [label="集成功率管理接口"];
+
+    B1 [label="QT本地操作界面"];
+    B2 [label="OCPP16云平台接口"];
+    B3 [label="CCU充电功率电流控制系统"];
+    B4 [label="PCU兼容华为充电堆，途充充电堆，单机功率柜"];
+    B5 [label="GBT27930-2015车桩通信协议"];
+    B6 [label="DIN70121-2012车桩通信协议"];
+    B7 [label="ISO15118-2013车桩通信协议"];
+    
+    C1 [label="标准OCPP1.6接口"];
+    C2 [label="远程升级"];
+    C3 [label="远程抓取log分析维护"];
+
+    D1 [label="OCPP限桩的功率或者电流"];
+    D2 [label="OCPP限单个充电枪的功率或者电流"];
+    D3 [label="OCPP限单次充电的功率或者电流"];
+    D4 [label="QT界面限单个充电枪的功率或者电流定时"];
+    D5 [label="QT界面限单个充电枪的功率或者电流每周"];
+    D6 [label="QT界面限单个充电枪的功率或者电流每日"];
+    
+    E1 [label="OCPP统一设置所有桩的电费价格和服务费价格，或者占位费价格"];
+    E2 [label="OCPP独立设置桩或者充电枪的电费价格和服务费价格，或者占位费价格"];
+    E3 [label="QT统一设置所有桩的电费价格和服务费价格，或者占位费价格"];
+    E4 [label="QT独立设置桩或者充电枪的电费价格和服务费价格，或者占位费价格"];
+
+    // 层次关系
+    T0 -> {T1, T2, T3, T4, T5};
+    T1 -> {A1, A2, A3, A4, A5, A6};
+    T2 -> {B1, B2, B3, B4, B5, B6, B7};
+    T3 -> {C1, C2, C3};
+    T4 -> {D1, D2, D3, D4, D5, D6};
+    T5 -> {E1, E2, E3, E4};
+    
+    // 标题设置（同样指定字体）
+    labelloc="t";
+    label="YT800KW系统设计和简介";
+    fontsize=16;
+    fontweight="bold";
+}

YT800KW.svg

@@ -0,0 +1,386 @@
+<?xml version="1.0" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="564pt" height="1421pt" viewBox="0.00 0.00 563.51 1421.2">
+<g id="graph0" class="graph" transform="translate(4,1417.199951171875) scale(1)" data-name="CompanyHierarchy">
+
+<polygon fill="white" stroke="none" points="-4,4 -4,-1417.2 559.51,-1417.2 559.51,4 -4,4"/>
+<text text-anchor="middle" x="277.75" y="-1394.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="16.00">YT800KW系统设计和简介</text>
+<!-- CEO -->
+<g id="node1" class="node" pointer-events="visible" data-name="T0" data-comment="CEO">
+
+<path fill="#b3d1ff" stroke="#4a86e8" d="M57.98,-630C57.98,-630 12.01,-630 12.01,-630 6.01,-630 0.01,-624 0.01,-618 0.01,-618 0.01,-606 0.01,-606 0.01,-600 6.01,-594 12.01,-594 12.01,-594 57.98,-594 57.98,-594 63.98,-594 69.98,-600 69.98,-606 69.98,-606 69.98,-618 69.98,-618 69.98,-624 63.98,-630 57.98,-630"/>
+<text text-anchor="middle" x="34.99" y="-608.4" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="12.00">YT800KW</text>
+</g>
+<!-- CTO -->
+<g id="node2" class="node" pointer-events="visible" data-name="T1" data-comment="CTO">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M149.99,-1224C149.99,-1224 119.99,-1224 119.99,-1224 113.99,-1224 107.99,-1218 107.99,-1212 107.99,-1212 107.99,-1200 107.99,-1200 107.99,-1194 113.99,-1188 119.99,-1188 119.99,-1188 149.99,-1188 149.99,-1188 155.99,-1188 161.99,-1194 161.99,-1200 161.99,-1200 161.99,-1212 161.99,-1212 161.99,-1218 155.99,-1224 149.99,-1224"/>
+<text text-anchor="middle" x="134.99" y="-1201.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">硬件</text>
+</g>
+<!-- CEO&#45;&gt;CTO -->
+<g id="edge1" class="edge" data-name="T0-&gt;T1" data-comment="CEO-&gt;CTO">
+
+<path fill="none" stroke="#666666" d="M39.03,-630.43C53.08,-715.57 111.74,-1071.17 129.12,-1176.49"/>
+<polygon fill="#666666" stroke="#666666" points="125.66,-1177 130.74,-1186.29 132.56,-1175.86 125.66,-1177"/>
+</g>
+<!-- CFO -->
+<g id="node3" class="node" pointer-events="visible" data-name="T2" data-comment="CFO">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M149.99,-873C149.99,-873 119.99,-873 119.99,-873 113.99,-873 107.99,-867 107.99,-861 107.99,-861 107.99,-849 107.99,-849 107.99,-843 113.99,-837 119.99,-837 119.99,-837 149.99,-837 149.99,-837 155.99,-837 161.99,-843 161.99,-849 161.99,-849 161.99,-861 161.99,-861 161.99,-867 155.99,-873 149.99,-873"/>
+<text text-anchor="middle" x="134.99" y="-850.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">软件</text>
+</g>
+<!-- CEO&#45;&gt;CFO -->
+<g id="edge2" class="edge" data-name="T0-&gt;T2" data-comment="CEO-&gt;CFO">
+
+<path fill="none" stroke="#666666" d="M43.36,-630.26C60.24,-672.13 101.85,-775.31 122.28,-825.98"/>
+<polygon fill="#666666" stroke="#666666" points="118.99,-827.15 125.97,-835.12 125.48,-824.54 118.99,-827.15"/>
+</g>
+<!-- COO -->
+<g id="node4" class="node" pointer-events="visible" data-name="T3" data-comment="COO">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M149.99,-630C149.99,-630 119.99,-630 119.99,-630 113.99,-630 107.99,-624 107.99,-618 107.99,-618 107.99,-606 107.99,-606 107.99,-600 113.99,-594 119.99,-594 119.99,-594 149.99,-594 149.99,-594 155.99,-594 161.99,-600 161.99,-606 161.99,-606 161.99,-618 161.99,-618 161.99,-624 155.99,-630 149.99,-630"/>
+<text text-anchor="middle" x="134.99" y="-607.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">云平台</text>
+</g>
+<!-- CEO&#45;&gt;COO -->
+<g id="edge3" class="edge" data-name="T0-&gt;T3" data-comment="CEO-&gt;COO">
+
+<path fill="none" stroke="#666666" d="M70.27,-612C78.69,-612 87.76,-612 96.33,-612"/>
+<polygon fill="#666666" stroke="#666666" points="96.1,-615.5 106.1,-612 96.1,-608.5 96.1,-615.5"/>
+</g>
+<!-- DevTeam -->
+<g id="node7" class="node" pointer-events="visible" data-name="A1" data-comment="DevTeam">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M399.75,-1386C399.75,-1386 355.75,-1386 355.75,-1386 349.75,-1386 343.75,-1380 343.75,-1374 343.75,-1374 343.75,-1362 343.75,-1362 343.75,-1356 349.75,-1350 355.75,-1350 355.75,-1350 399.75,-1350 399.75,-1350 405.75,-1350 411.75,-1356 411.75,-1362 411.75,-1362 411.75,-1374 411.75,-1374 411.75,-1380 405.75,-1386 399.75,-1386"/>
+<text text-anchor="middle" x="377.75" y="-1363.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">单板电路板</text>
+</g>
+<!-- CTO&#45;&gt;DevTeam -->
+<g id="edge6" class="edge" data-name="T1-&gt;A1" data-comment="CTO-&gt;DevTeam">
+
+<path fill="none" stroke="#666666" d="M139.05,-1224.3C145.04,-1253.98 161.29,-1312.19 199.99,-1341 237.9,-1369.22 293.24,-1373.42 331.87,-1372.2"/>
+<polygon fill="#666666" stroke="#666666" points="331.94,-1375.7 341.77,-1371.73 331.61,-1368.7 331.94,-1375.7"/>
+</g><g id="edge4" class="edge" data-name="T0-&gt;T4" data-comment="CTO-&gt;DevTeam">
+
+<path fill="none" stroke="#666666" d="M44.35,-593.58C61.45,-555.88 100.56,-469.68 121,-424.62"/>
+<polygon fill="#666666" stroke="#666666" points="124.08,-426.3 125.03,-415.75 117.71,-423.41 124.08,-426.3"/>
+</g>
+<!-- QAteam -->
+<g id="node8" class="node" pointer-events="visible" data-name="A2" data-comment="QAteam">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M410.25,-1332C410.25,-1332 345.25,-1332 345.25,-1332 339.25,-1332 333.25,-1326 333.25,-1320 333.25,-1320 333.25,-1308 333.25,-1308 333.25,-1302 339.25,-1296 345.25,-1296 345.25,-1296 410.25,-1296 410.25,-1296 416.25,-1296 422.25,-1302 422.25,-1308 422.25,-1308 422.25,-1320 422.25,-1320 422.25,-1326 416.25,-1332 410.25,-1332"/>
+<text text-anchor="middle" x="377.75" y="-1309.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">可搭建主从备份</text>
+</g>
+<!-- CTO&#45;&gt;QAteam -->
+<g id="edge7" class="edge" data-name="T1-&gt;A2" data-comment="CTO-&gt;QAteam">
+
+<path fill="none" stroke="#666666" d="M145.19,-1224.49C155.69,-1243.49 174.74,-1272.31 199.99,-1287 236.67,-1308.34 284.58,-1314.59 321.27,-1315.78"/>
+<polygon fill="#666666" stroke="#666666" points="321.18,-1319.27 331.24,-1315.97 321.31,-1312.28 321.18,-1319.27"/>
+</g><g id="edge5" class="edge" data-name="T0-&gt;T5" data-comment="CTO-&gt;QAteam">
+
+<path fill="none" stroke="#666666" d="M39.72,-593.54C54.57,-519.87 109.7,-246.45 128.02,-155.58"/>
+<polygon fill="#666666" stroke="#666666" points="131.42,-156.45 129.96,-145.96 124.56,-155.07 131.42,-156.45"/>
+</g>
+<!-- ITOps -->
+<g id="node9" class="node" pointer-events="visible" data-name="A3" data-comment="ITOps">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M447.25,-1278C447.25,-1278 308.25,-1278 308.25,-1278 302.25,-1278 296.25,-1272 296.25,-1266 296.25,-1266 296.25,-1254 296.25,-1254 296.25,-1248 302.25,-1242 308.25,-1242 308.25,-1242 447.25,-1242 447.25,-1242 453.25,-1242 459.25,-1248 459.25,-1254 459.25,-1254 459.25,-1266 459.25,-1266 459.25,-1272 453.25,-1278 447.25,-1278"/>
+<text text-anchor="middle" x="377.75" y="-1255.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">兼容一体桩和端机，充电堆主机</text>
+</g>
+<!-- CTO&#45;&gt;ITOps -->
+<g id="edge8" class="edge" data-name="T1-&gt;A3" data-comment="CTO-&gt;ITOps">
+
+<path fill="none" stroke="#666666" d="M162.24,-1218.81C173.61,-1223.9 187.22,-1229.39 199.99,-1233 227.03,-1240.64 257.05,-1246.26 284.56,-1250.32"/>
+<polygon fill="#666666" stroke="#666666" points="283.89,-1253.76 294.28,-1251.7 284.87,-1246.83 283.89,-1253.76"/>
+</g>
+<!-- Accounting -->
+<g id="node13" class="node" pointer-events="visible" data-name="B1" data-comment="Accounting">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M414.41,-1062C414.41,-1062 341.09,-1062 341.09,-1062 335.09,-1062 329.09,-1056 329.09,-1050 329.09,-1050 329.09,-1038 329.09,-1038 329.09,-1032 335.09,-1026 341.09,-1026 341.09,-1026 414.41,-1026 414.41,-1026 420.41,-1026 426.41,-1032 426.41,-1038 426.41,-1038 426.41,-1050 426.41,-1050 426.41,-1056 420.41,-1062 414.41,-1062"/>
+<text text-anchor="middle" x="377.75" y="-1039.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">QT本地操作界面</text>
+</g>
+<!-- CFO&#45;&gt;Accounting -->
+<g id="edge9" class="edge" data-name="T1-&gt;A4" data-comment="CFO-&gt;Accounting">
+
+<path fill="none" stroke="#666666" d="M162.21,-1206C197.98,-1206 263.23,-1206 312.41,-1206"/>
+<polygon fill="#666666" stroke="#666666" points="312.39,-1209.5 322.39,-1206 312.39,-1202.5 312.39,-1209.5"/>
+</g>
+<!-- Finance -->
+<g id="node14" class="node" pointer-events="visible" data-name="B2" data-comment="Finance">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M424.27,-1008C424.27,-1008 331.23,-1008 331.23,-1008 325.23,-1008 319.23,-1002 319.23,-996 319.23,-996 319.23,-984 319.23,-984 319.23,-978 325.23,-972 331.23,-972 331.23,-972 424.27,-972 424.27,-972 430.27,-972 436.27,-978 436.27,-984 436.27,-984 436.27,-996 436.27,-996 436.27,-1002 430.27,-1008 424.27,-1008"/>
+<text text-anchor="middle" x="377.75" y="-985.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">OCPP16云平台接口</text>
+</g>
+<!-- CFO&#45;&gt;Finance -->
+<g id="edge10" class="edge" data-name="T1-&gt;A5" data-comment="CFO-&gt;Finance">
+
+<path fill="none" stroke="#666666" d="M162.24,-1193.19C173.61,-1188.1 187.22,-1182.61 199.99,-1179 222.07,-1172.76 246.13,-1167.87 269.19,-1164.08"/>
+<polygon fill="#666666" stroke="#666666" points="269.59,-1167.56 278.92,-1162.54 268.5,-1160.64 269.59,-1167.56"/>
+</g>
+<!-- HR -->
+<g id="node20" class="node" pointer-events="visible" data-name="C1" data-comment="HR">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M420.77,-684C420.77,-684 334.73,-684 334.73,-684 328.73,-684 322.73,-678 322.73,-672 322.73,-672 322.73,-660 322.73,-660 322.73,-654 328.73,-648 334.73,-648 334.73,-648 420.77,-648 420.77,-648 426.77,-648 432.77,-654 432.77,-660 432.77,-660 432.77,-672 432.77,-672 432.77,-678 426.77,-684 420.77,-684"/>
+<text text-anchor="middle" x="377.75" y="-661.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">标准OCPP1.6接口</text>
+</g>
+<!-- COO&#45;&gt;HR -->
+<g id="edge11" class="edge" data-name="T1-&gt;A6" data-comment="COO-&gt;HR">
+
+<path fill="none" stroke="#666666" d="M145.19,-1187.51C155.69,-1168.51 174.74,-1139.69 199.99,-1125 234.98,-1104.65 280.18,-1098.02 316.11,-1096.42"/>
+<polygon fill="#666666" stroke="#666666" points="316.03,-1099.93 325.92,-1096.12 315.81,-1092.93 316.03,-1099.93"/>
+</g>
+<!-- Marketing -->
+<g id="node21" class="node" pointer-events="visible" data-name="C2" data-comment="Marketing">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M394.75,-630C394.75,-630 360.75,-630 360.75,-630 354.75,-630 348.75,-624 348.75,-618 348.75,-618 348.75,-606 348.75,-606 348.75,-600 354.75,-594 360.75,-594 360.75,-594 394.75,-594 394.75,-594 400.75,-594 406.75,-600 406.75,-606 406.75,-606 406.75,-618 406.75,-618 406.75,-624 400.75,-630 394.75,-630"/>
+<text text-anchor="middle" x="377.75" y="-607.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">远程升级</text>
+</g>
+<!-- COO&#45;&gt;Marketing -->
+<g id="edge12" class="edge" data-name="T2-&gt;B1" data-comment="COO-&gt;Marketing">
+
+<path fill="none" stroke="#666666" d="M137.45,-873.26C141.22,-907.4 154.47,-980.71 199.99,-1017 232.76,-1043.13 280.14,-1049.21 317.6,-1049.12"/>
+<polygon fill="#666666" stroke="#666666" points="317.43,-1052.62 327.36,-1048.93 317.3,-1045.62 317.43,-1052.62"/>
+</g>
+<!-- Sales -->
+<!-- C3 -->
+<g id="node22" class="node" pointer-events="visible" data-name="C3">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M424.64,-576C424.64,-576 330.86,-576 330.86,-576 324.86,-576 318.86,-570 318.86,-564 318.86,-564 318.86,-552 318.86,-552 318.86,-546 324.86,-540 330.86,-540 330.86,-540 424.64,-540 424.64,-540 430.64,-540 436.64,-546 436.64,-552 436.64,-552 436.64,-564 436.64,-564 436.64,-570 430.64,-576 424.64,-576"/>
+<text text-anchor="middle" x="377.75" y="-553.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">远程抓取log分析维护</text>
+</g>
+<!-- COO&#45;&gt;Sales -->
+
+<!-- COO&#45;&gt;C3 -->
+<!-- COO&#45;&gt;C3 -->
+<!-- COO&#45;&gt;C3 -->
+<g id="edge13" class="edge" data-name="T2-&gt;B2" data-comment="COO-&gt;C3">
+
+<path fill="none" stroke="#666666" d="M141.38,-873.34C149.66,-898.05 168.01,-941.42 199.99,-963 231.33,-984.16 272.87,-991.29 307.8,-992.96"/>
+<polygon fill="#666666" stroke="#666666" points="307.27,-996.44 317.38,-993.27 307.5,-989.45 307.27,-996.44"/>
+</g>
+<!-- Frontend -->
+
+<!-- DevTeam&#45;&gt;Frontend -->
+<g id="edge14" class="edge" data-name="T2-&gt;B3" data-comment="DevTeam-&gt;Frontend">
+
+<path fill="none" stroke="#666666" d="M152.34,-873.29C164.3,-885.44 181.59,-900.65 199.99,-909 228.31,-921.86 261.54,-928.79 291.5,-932.46"/>
+<polygon fill="#666666" stroke="#666666" points="290.97,-935.92 301.3,-933.55 291.75,-928.97 290.97,-935.92"/>
+</g>
+<!-- Backend -->
+<g id="node10" class="node" pointer-events="visible" data-name="A4" data-comment="Backend">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M419.25,-1224C419.25,-1224 336.25,-1224 336.25,-1224 330.25,-1224 324.25,-1218 324.25,-1212 324.25,-1212 324.25,-1200 324.25,-1200 324.25,-1194 330.25,-1188 336.25,-1188 336.25,-1188 419.25,-1188 419.25,-1188 425.25,-1188 431.25,-1194 431.25,-1200 431.25,-1200 431.25,-1212 431.25,-1212 431.25,-1218 425.25,-1224 419.25,-1224"/>
+<text text-anchor="middle" x="377.75" y="-1201.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">集成TCU显示接口</text>
+</g>
+<!-- DevTeam&#45;&gt;Backend -->
+<g id="edge15" class="edge" data-name="T2-&gt;B4" data-comment="DevTeam-&gt;Backend">
+
+<path fill="none" stroke="#666666" d="M162.21,-857.94C182.87,-860.26 213.37,-863.68 244.92,-867.22"/>
+<polygon fill="#666666" stroke="#666666" points="244.28,-870.67 254.61,-868.3 245.06,-863.71 244.28,-870.67"/>
+</g>
+<!-- Mobile -->
+<g id="node11" class="node" pointer-events="visible" data-name="A5" data-comment="Mobile">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M462.75,-1170C462.75,-1170 292.75,-1170 292.75,-1170 286.75,-1170 280.75,-1164 280.75,-1158 280.75,-1158 280.75,-1146 280.75,-1146 280.75,-1140 286.75,-1134 292.75,-1134 292.75,-1134 462.75,-1134 462.75,-1134 468.75,-1134 474.75,-1140 474.75,-1146 474.75,-1146 474.75,-1158 474.75,-1158 474.75,-1164 468.75,-1170 462.75,-1170"/>
+<text text-anchor="middle" x="377.75" y="-1147.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">集成欧标，美标，特斯拉车桩通信接口</text>
+</g>
+<!-- DevTeam&#45;&gt;Mobile -->
+<g id="edge16" class="edge" data-name="T2-&gt;B5" data-comment="DevTeam-&gt;Mobile">
+
+<path fill="none" stroke="#666666" d="M162.21,-852.06C190.29,-848.91 236.55,-843.72 278.93,-838.97"/>
+<polygon fill="#666666" stroke="#666666" points="279.13,-842.47 288.68,-837.88 278.35,-835.51 279.13,-842.47"/>
+</g>
+<g id="node15" class="node" pointer-events="visible" data-name="B3" data-comment="DevTeam-&gt;Mobile">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M440.53,-954C440.53,-954 314.96,-954 314.96,-954 308.96,-954 302.96,-948 302.96,-942 302.96,-942 302.96,-930 302.96,-930 302.96,-924 308.96,-918 314.96,-918 314.96,-918 440.53,-918 440.53,-918 446.53,-918 452.53,-924 452.53,-930 452.53,-930 452.53,-942 452.53,-942 452.53,-948 446.53,-954 440.53,-954"/>
+<text text-anchor="middle" x="377.75" y="-931.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">CCU充电功率电流控制系统</text>
+</g><g id="node12" class="node" pointer-events="visible" data-name="A6" data-comment="DevTeam-&gt;Mobile">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M415.75,-1116C415.75,-1116 339.75,-1116 339.75,-1116 333.75,-1116 327.75,-1110 327.75,-1104 327.75,-1104 327.75,-1092 327.75,-1092 327.75,-1086 333.75,-1080 339.75,-1080 339.75,-1080 415.75,-1080 415.75,-1080 421.75,-1080 427.75,-1086 427.75,-1092 427.75,-1092 427.75,-1104 427.75,-1104 427.75,-1110 421.75,-1116 415.75,-1116"/>
+<text text-anchor="middle" x="377.75" y="-1093.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">集成功率管理接口</text>
+</g><g id="edge17" class="edge" data-name="T2-&gt;B6" data-comment="DevTeam-&gt;Mobile">
+
+<path fill="none" stroke="#666666" d="M152.34,-836.71C164.3,-824.56 181.59,-809.35 199.99,-801 224.84,-789.71 253.48,-783 280.37,-779.04"/>
+<polygon fill="#666666" stroke="#666666" points="280.82,-782.51 290.27,-777.71 279.89,-775.57 280.82,-782.51"/>
+</g>
+<!-- B4 -->
+<!-- B4 -->
+<g id="node16" class="node" pointer-events="visible" data-name="B4">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M486.98,-900C486.98,-900 268.51,-900 268.51,-900 262.51,-900 256.51,-894 256.51,-888 256.51,-888 256.51,-876 256.51,-876 256.51,-870 262.51,-864 268.51,-864 268.51,-864 486.98,-864 486.98,-864 492.98,-864 498.98,-870 498.98,-876 498.98,-876 498.98,-888 498.98,-888 498.98,-894 492.98,-900 486.98,-900"/>
+<text text-anchor="middle" x="377.75" y="-877.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">PCU兼容华为充电堆，途充充电堆，单机功率柜</text>
+</g>
+<!-- B -->
+
+<g id="edge19" class="edge" data-name="T3-&gt;C1" data-comment="B">
+
+<path fill="none" stroke="#666666" d="M162.24,-624.81C173.61,-629.9 187.22,-635.39 199.99,-639 236.09,-649.2 277.49,-655.79 311.15,-659.9"/>
+<polygon fill="#666666" stroke="#666666" points="310.4,-663.34 320.74,-661.02 311.22,-656.38 310.4,-663.34"/>
+</g>
+<g id="node17" class="node" pointer-events="visible" data-name="B5" data-comment="B">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M452.91,-846C452.91,-846 302.59,-846 302.59,-846 296.59,-846 290.59,-840 290.59,-834 290.59,-834 290.59,-822 290.59,-822 290.59,-816 296.59,-810 302.59,-810 302.59,-810 452.91,-810 452.91,-810 458.91,-810 464.91,-816 464.91,-822 464.91,-822 464.91,-834 464.91,-834 464.91,-840 458.91,-846 452.91,-846"/>
+<text text-anchor="middle" x="377.75" y="-823.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">GBT27930-2015车桩通信协议</text>
+</g><g id="edge18" class="edge" data-name="T2-&gt;B7" data-comment="B">
+
+<path fill="none" stroke="#666666" d="M141.38,-836.66C149.66,-811.95 168.01,-768.58 199.99,-747 223.73,-730.98 253.31,-723 281.44,-719.34"/>
+<polygon fill="#666666" stroke="#666666" points="281.5,-722.86 291.05,-718.28 280.72,-715.9 281.5,-722.86"/>
+</g>
+<!-- B -->
+<!-- B6 -->
+<g id="node18" class="node" pointer-events="visible" data-name="B6">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M451.29,-792C451.29,-792 304.2,-792 304.2,-792 298.2,-792 292.2,-786 292.2,-780 292.2,-780 292.2,-768 292.2,-768 292.2,-762 298.2,-756 304.2,-756 304.2,-756 451.29,-756 451.29,-756 457.29,-756 463.29,-762 463.29,-768 463.29,-768 463.29,-780 463.29,-780 463.29,-786 457.29,-792 451.29,-792"/>
+<text text-anchor="middle" x="377.75" y="-769.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">DIN70121-2012车桩通信协议</text>
+</g>
+<!-- B -->
+
+<!-- T3&#45;&gt;C3 -->
+<g id="edge21" class="edge" data-name="T3-&gt;C3">
+
+<path fill="none" stroke="#666666" d="M162.24,-599.19C173.61,-594.1 187.22,-588.61 199.99,-585 234.73,-575.18 274.38,-568.71 307.31,-564.58"/>
+<polygon fill="#666666" stroke="#666666" points="307.65,-568.06 317.16,-563.39 306.81,-561.11 307.65,-568.06"/>
+</g>
+<g id="node19" class="node" pointer-events="visible" data-name="B7" data-comment="T3-&gt;C3">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M450.47,-738C450.47,-738 305.03,-738 305.03,-738 299.03,-738 293.03,-732 293.03,-726 293.03,-726 293.03,-714 293.03,-714 293.03,-708 299.03,-702 305.03,-702 305.03,-702 450.47,-702 450.47,-702 456.47,-702 462.47,-708 462.47,-714 462.47,-714 462.47,-726 462.47,-726 462.47,-732 456.47,-738 450.47,-738"/>
+<text text-anchor="middle" x="377.75" y="-715.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">ISO15118-2013车桩通信协议</text>
+</g><g id="edge20" class="edge" data-name="T3-&gt;C2" data-comment="T3-&gt;C3">
+
+<path fill="none" stroke="#666666" d="M162.21,-612C204.41,-612 287.65,-612 337.12,-612"/>
+<polygon fill="#666666" stroke="#666666" points="336.81,-615.5 346.81,-612 336.81,-608.5 336.81,-615.5"/>
+</g>
+<!-- T -->
+<!-- T4 -->
+<g id="node5" class="node" pointer-events="visible" data-name="T4">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M151.99,-414C151.99,-414 117.99,-414 117.99,-414 111.99,-414 105.99,-408 105.99,-402 105.99,-402 105.99,-390 105.99,-390 105.99,-384 111.99,-378 117.99,-378 117.99,-378 151.99,-378 151.99,-378 157.99,-378 163.99,-384 163.99,-390 163.99,-390 163.99,-402 163.99,-402 163.99,-408 157.99,-414 151.99,-414"/>
+<text text-anchor="middle" x="134.99" y="-391.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">功率管理</text>
+</g>
+<!-- T -->
+
+
+<g id="node6" class="node" pointer-events="visible" data-name="T5" data-comment="T">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M151.99,-144C151.99,-144 117.99,-144 117.99,-144 111.99,-144 105.99,-138 105.99,-132 105.99,-132 105.99,-120 105.99,-120 105.99,-114 111.99,-108 117.99,-108 117.99,-108 151.99,-108 151.99,-108 157.99,-108 163.99,-114 163.99,-120 163.99,-120 163.99,-132 163.99,-132 163.99,-138 157.99,-144 151.99,-144"/>
+<text text-anchor="middle" x="134.99" y="-121.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">价格管理</text>
+</g>
+<!-- D -->
+<g id="node23" class="node" pointer-events="visible" data-name="D1" data-comment="D">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M438.27,-522C438.27,-522 317.23,-522 317.23,-522 311.23,-522 305.23,-516 305.23,-510 305.23,-510 305.23,-498 305.23,-498 305.23,-492 311.23,-486 317.23,-486 317.23,-486 438.27,-486 438.27,-486 444.27,-486 450.27,-492 450.27,-498 450.27,-498 450.27,-510 450.27,-510 450.27,-516 444.27,-522 438.27,-522"/>
+<text text-anchor="middle" x="377.75" y="-499.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">OCPP限桩的功率或者电流</text>
+</g>
+<!-- D -->
+<g id="node24" class="node" pointer-events="visible" data-name="D2" data-comment="D">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M459.27,-468C459.27,-468 296.23,-468 296.23,-468 290.23,-468 284.23,-462 284.23,-456 284.23,-456 284.23,-444 284.23,-444 284.23,-438 290.23,-432 296.23,-432 296.23,-432 459.27,-432 459.27,-432 465.27,-432 471.27,-438 471.27,-444 471.27,-444 471.27,-456 471.27,-456 471.27,-462 465.27,-468 459.27,-468"/>
+<text text-anchor="middle" x="377.75" y="-445.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">OCPP限单个充电枪的功率或者电流</text>
+</g>
+<!-- D -->
+<g id="node25" class="node" pointer-events="visible" data-name="D3" data-comment="D">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M454.27,-414C454.27,-414 301.23,-414 301.23,-414 295.23,-414 289.23,-408 289.23,-402 289.23,-402 289.23,-390 289.23,-390 289.23,-384 295.23,-378 301.23,-378 301.23,-378 454.27,-378 454.27,-378 460.27,-378 466.27,-384 466.27,-390 466.27,-390 466.27,-402 466.27,-402 466.27,-408 460.27,-414 454.27,-414"/>
+<text text-anchor="middle" x="377.75" y="-391.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">OCPP限单次充电的功率或者电流</text>
+</g><g id="edge22" class="edge" data-name="T4-&gt;D1" data-comment="D">
+
+<path fill="none" stroke="#666666" d="M145.19,-414.49C155.69,-433.49 174.74,-462.31 199.99,-477 227.95,-493.26 262.43,-500.76 293.5,-503.93"/>
+<polygon fill="#666666" stroke="#666666" points="293,-507.4 303.26,-504.78 293.6,-500.43 293,-507.4"/>
+</g>
+<!-- D -->
+<!-- D4 -->
+<!-- D4 -->
+<g id="node26" class="node" pointer-events="visible" data-name="D4">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M472.41,-360C472.41,-360 283.09,-360 283.09,-360 277.09,-360 271.09,-354 271.09,-348 271.09,-348 271.09,-336 271.09,-336 271.09,-330 277.09,-324 283.09,-324 283.09,-324 472.41,-324 472.41,-324 478.41,-324 484.41,-330 484.41,-336 484.41,-336 484.41,-348 484.41,-348 484.41,-354 478.41,-360 472.41,-360"/>
+<text text-anchor="middle" x="377.75" y="-337.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">QT界面限单个充电枪的功率或者电流定时</text>
+</g>
+<!-- D -->
+
+<!-- D5 -->
+<g id="edge25" class="edge" data-name="T4-&gt;D4" data-comment="D5">
+
+<path fill="none" stroke="#666666" d="M164.44,-382.21C175.34,-377.41 188.04,-372.38 199.99,-369 219.02,-363.62 239.52,-359.25 259.59,-355.71"/>
+<polygon fill="#666666" stroke="#666666" points="259.91,-359.21 269.19,-354.09 258.74,-352.31 259.91,-359.21"/>
+</g>
+<!-- D5 -->
+<g id="node27" class="node" pointer-events="visible" data-name="D5">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M472.41,-306C472.41,-306 283.09,-306 283.09,-306 277.09,-306 271.09,-300 271.09,-294 271.09,-294 271.09,-282 271.09,-282 271.09,-276 277.09,-270 283.09,-270 283.09,-270 472.41,-270 472.41,-270 478.41,-270 484.41,-276 484.41,-282 484.41,-282 484.41,-294 484.41,-294 484.41,-300 478.41,-306 472.41,-306"/>
+<text text-anchor="middle" x="377.75" y="-283.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">QT界面限单个充电枪的功率或者电流每周</text>
+</g>
+<!-- D -->
+<g id="edge23" class="edge" data-name="T4-&gt;D2" data-comment="D">
+
+<path fill="none" stroke="#666666" d="M164.44,-409.79C175.34,-414.59 188.04,-419.62 199.99,-423 223.2,-429.56 248.6,-434.62 272.73,-438.5"/>
+<polygon fill="#666666" stroke="#666666" points="272.17,-441.95 282.59,-440.02 273.24,-435.03 272.17,-441.95"/>
+</g>
+<!-- D6 -->
+<g id="edge26" class="edge" data-name="T4-&gt;D5" data-comment="D6">
+
+<path fill="none" stroke="#666666" d="M145.19,-377.51C155.69,-358.51 174.74,-329.69 199.99,-315 218.07,-304.48 238.88,-297.63 259.73,-293.24"/>
+<polygon fill="#666666" stroke="#666666" points="260.3,-296.7 269.48,-291.39 259,-289.82 260.3,-296.7"/>
+</g>
+<!-- D6 -->
+<g id="node28" class="node" pointer-events="visible" data-name="D6">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M472.41,-252C472.41,-252 283.09,-252 283.09,-252 277.09,-252 271.09,-246 271.09,-240 271.09,-240 271.09,-228 271.09,-228 271.09,-222 277.09,-216 283.09,-216 283.09,-216 472.41,-216 472.41,-216 478.41,-216 484.41,-222 484.41,-228 484.41,-228 484.41,-240 484.41,-240 484.41,-246 478.41,-252 472.41,-252"/>
+<text text-anchor="middle" x="377.75" y="-229.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">QT界面限单个充电枪的功率或者电流每日</text>
+</g>
+<g id="edge24" class="edge" data-name="T4-&gt;D3" data-comment="D6">
+
+<path fill="none" stroke="#666666" d="M164.08,-396C191.97,-396 236.38,-396 277.42,-396"/>
+<polygon fill="#666666" stroke="#666666" points="277.38,-399.5 287.38,-396 277.38,-392.5 277.38,-399.5"/>
+</g>
+<!-- T4&#45;&gt;D6 -->
+<g id="edge27" class="edge" data-name="T4-&gt;D6">
+
+<path fill="none" stroke="#666666" d="M139.05,-377.7C145.04,-348.02 161.29,-289.81 199.99,-261 217.27,-248.14 238.17,-240.26 259.47,-235.62"/>
+<polygon fill="#666666" stroke="#666666" points="259.97,-239.09 269.13,-233.76 258.65,-232.21 259.97,-239.09"/>
+</g>
+<!-- 1 -->
+
+<!-- T4&#45;&gt;D6 -->
+
+<!-- E1 -->
+<g id="node29" class="node" pointer-events="visible" data-name="E1">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M527.77,-198C527.77,-198 227.73,-198 227.73,-198 221.73,-198 215.73,-192 215.73,-186 215.73,-186 215.73,-174 215.73,-174 215.73,-168 221.73,-162 227.73,-162 227.73,-162 527.77,-162 527.77,-162 533.77,-162 539.77,-168 539.77,-174 539.77,-174 539.77,-186 539.77,-186 539.77,-192 533.77,-198 527.77,-198"/>
+<text text-anchor="middle" x="377.75" y="-175.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">OCPP统一设置所有桩的电费价格和服务费价格，或者占位费价格</text>
+</g>
+<!-- E -->
+<g id="edge28" class="edge" data-name="T5-&gt;E1" data-comment="E">
+
+<path fill="none" stroke="#666666" d="M164.44,-139.79C175.34,-144.59 188.04,-149.62 199.99,-153 207.79,-155.21 215.85,-157.24 224.01,-159.12"/>
+<polygon fill="#666666" stroke="#666666" points="223.22,-162.53 233.73,-161.26 224.72,-155.69 223.22,-162.53"/>
+</g>
+<!-- E2 -->
+<g id="node30" class="node" pointer-events="visible" data-name="E2">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M543.27,-144C543.27,-144 212.23,-144 212.23,-144 206.23,-144 200.23,-138 200.23,-132 200.23,-132 200.23,-120 200.23,-120 200.23,-114 206.23,-108 212.23,-108 212.23,-108 543.27,-108 543.27,-108 549.27,-108 555.27,-114 555.27,-120 555.27,-120 555.27,-132 555.27,-132 555.27,-138 549.27,-144 543.27,-144"/>
+<text text-anchor="middle" x="377.75" y="-121.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">OCPP独立设置桩或者充电枪的电费价格和服务费价格，或者占位费价格</text>
+</g>
+<!-- E -->
+<g id="edge29" class="edge" data-name="T5-&gt;E2" data-comment="E">
+
+<path fill="none" stroke="#666666" d="M164.08,-126C171.31,-126 179.65,-126 188.76,-126"/>
+<polygon fill="#666666" stroke="#666666" points="188.7,-129.5 198.7,-126 188.7,-122.5 188.7,-129.5"/>
+</g>
+<g id="node31" class="node" pointer-events="visible" data-name="E3" data-comment="E">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M519.41,-90C519.41,-90 236.09,-90 236.09,-90 230.09,-90 224.09,-84 224.09,-78 224.09,-78 224.09,-66 224.09,-66 224.09,-60 230.09,-54 236.09,-54 236.09,-54 519.41,-54 519.41,-54 525.41,-54 531.41,-60 531.41,-66 531.41,-66 531.41,-78 531.41,-78 531.41,-84 525.41,-90 519.41,-90"/>
+<text text-anchor="middle" x="377.75" y="-67.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">QT统一设置所有桩的电费价格和服务费价格，或者占位费价格</text>
+</g>
+<!-- E -->
+<g id="edge30" class="edge" data-name="T5-&gt;E3" data-comment="E">
+
+<path fill="none" stroke="#666666" d="M164.44,-112.21C175.34,-107.41 188.04,-102.38 199.99,-99 207.79,-96.79 215.85,-94.76 224.01,-92.88"/>
+<polygon fill="#666666" stroke="#666666" points="224.72,-96.31 233.73,-90.74 223.22,-89.47 224.72,-96.31"/>
+</g><g id="node32" class="node" pointer-events="visible" data-name="E4" data-comment="E">
+
+<path fill="#e6f2ff" stroke="#4a86e8" d="M535.41,-36C535.41,-36 220.09,-36 220.09,-36 214.09,-36 208.09,-30 208.09,-24 208.09,-24 208.09,-12 208.09,-12 208.09,-6 214.09,0 220.09,0 220.09,0 535.41,0 535.41,0 541.41,0 547.41,-6 547.41,-12 547.41,-12 547.41,-24 547.41,-24 547.41,-30 541.41,-36 535.41,-36"/>
+<text text-anchor="middle" x="377.75" y="-13.8" font-family="SimHei, Microsoft YaHei, Heiti TC" font-size="14.00">QT独立设置桩或者充电枪的电费价格和服务费价格，或者占位费价格</text>
+</g>
+<g id="edge31" class="edge" data-name="T5-&gt;E4" data-comment="E">
+
+<path fill="none" stroke="#666666" d="M145.19,-107.51C155.69,-88.51 174.74,-59.69 199.99,-45 202.22,-43.7 204.5,-42.46 206.81,-41.27"/>
+<polygon fill="#666666" stroke="#666666" points="208.25,-44.46 215.8,-37.03 205.27,-38.13 208.25,-44.46"/>
+</g></g>
+</svg>

arm-linux-setup.cmake

@@ -0,0 +1,14 @@
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR arm)
+
+# compiler/linker flags
+set(CMAKE_SYSROOT /opt/arago-2023.04/sysroots/aarch64-oe-linux)
+
+set(tools /opt/arago-2023.04/sysroots/x86_64-arago-linux/usr/bin/aarch64-oe-linux)
+set(CMAKE_C_COMPILER ${tools}/aarch64-oe-linux-gcc)
+set(CMAKE_CXX_COMPILER ${tools}/aarch64-oe-linux-g++)
+
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

bitstream.c

@@ -0,0 +1,115 @@
+#include "bitstream.h"
+
+#define BITS_IN_BYTE 8
+#define EXI_ERROR_INPUT_STREAM_EOF -10
+#define EXI_ERROR_OUTPUT_STREAM_EOF -11
+
+int bitstream_putNBits(bitstream_t* stream, int nbits, uint32_t value)
+{
+    int errn;
+	if (nbits <= stream->xbits) {
+		/* all bits fit into the current temp */
+		stream->tmp = (uint8_t)(stream->tmp << (nbits)) | (uint8_t)(value & (uint32_t)(0xff >> (uint32_t)(BITS_IN_BYTE - nbits)));
+		stream->xbits = stream->xbits - nbits;
+		/* if the temp is full write byte */
+		if (stream->xbits == 0) {
+
+			if (stream->pos >= stream->size) {
+				errn = EXI_ERROR_OUTPUT_STREAM_EOF;
+			} else {
+				stream->data[stream->pos++] = stream->tmp;
+			}
+
+			stream->xbits = BITS_IN_BYTE;
+			stream->tmp = 0;
+		}
+	} else {
+		/* the temp is not enough * fill the temp */
+		stream->tmp = (uint8_t)(stream->tmp << stream->xbits) | ( (uint8_t)(value >> (nbits - stream->xbits)) & (uint8_t)(0xff >> (BITS_IN_BYTE - stream->xbits)) );
+
+		nbits = (nbits - stream->xbits);
+
+		if (stream->pos >= stream->size) {
+			errn = EXI_ERROR_OUTPUT_STREAM_EOF;
+		} else {
+			stream->data[stream->pos++] = stream->tmp;
+		}
+		stream->tmp = 0;
+
+		/* write whole bytes */
+		while (errn == 0 && nbits >= BITS_IN_BYTE) {
+			nbits = (nbits - BITS_IN_BYTE);
+			if (stream->pos >= stream->size) {
+				errn = EXI_ERROR_OUTPUT_STREAM_EOF;
+			} else {
+				stream->data[stream->pos++] = (uint8_t)(value >> (nbits));
+			}
+		}
+
+		/* spared bits are kept in the temp */
+		stream->tmp = (uint8_t)value; /* Note: the high bits will be shifted out during further filling */
+		stream->xbits = (uint8_t)(BITS_IN_BYTE - (nbits));
+	}
+
+	return errn;    
+}
+
+int bitstream_getNBits(bitstream_t* stream, int nbits, uint32_t *value)
+{
+	int errn = 0;
+	*value = 0;
+
+	if (nbits <= 0) return errn;
+	
+	if(stream->xbits == 0)
+	{
+		if ( stream->pos < stream->size ) {
+			stream->tmp = stream->data[stream->pos++];
+			stream->xbits = BITS_IN_BYTE;
+		} else {
+			errn = EXI_ERROR_INPUT_STREAM_EOF;
+		}
+	}
+
+	if (errn == 0) {
+		/* read the bits in one step */
+		if(nbits <= stream->xbits) {
+			stream->xbits = (uint8_t)(stream->xbits - nbits);
+			*value = (uint32_t)((stream->tmp >> stream->xbits) & (0xff >> (BITS_IN_BYTE - nbits)));
+		} else {
+			/* read bits as much as possible */
+			*value = (uint32_t)(stream->tmp & (0xff >> (BITS_IN_BYTE - stream->xbits)));
+			nbits = (nbits - stream->xbits);
+			stream->xbits = 0;
+
+			/* read whole bytes */
+			while(errn == 0 && nbits >= 8)
+			{
+				errn = readBuffer(stream);
+				*value = ((*value) << BITS_IN_BYTE) | stream->tmp;
+				nbits = (nbits - BITS_IN_BYTE);
+				stream->xbits = 0;
+			}
+
+			/* read the spare bits in the buffer */
+			if(errn == 0 && nbits > 0)
+			{
+				errn = readBuffer(stream);
+				if (errn == 0) {
+					*value = ( (*value) << nbits) | (uint8_t)(stream->tmp  >> (BITS_IN_BYTE - nbits)) ;
+					stream->xbits = (uint8_t)(BITS_IN_BYTE - nbits);
+				}
+			}
+		}
+	}
+
+	return errn;
+}
+
+int bitstream_getBool(bitstream_t* stream, int *value)
+{
+	uint32_t out;
+	int ret = bitstream_getNBits(stream, 1, &out);
+	*value = (out==0x0? 0 : 1);
+	return ret;
+}

bitstream.h

@@ -0,0 +1,21 @@
+#ifndef __BITSTREAM_H__
+#define __BITSTREAM_H__
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <string.h>
+
+
+typedef struct bitstream
+{
+    int pos;   // stream pointer in index
+    int size;  // stream memsize in bytes
+    uint8_t* data;
+    
+    int xbits; // tmp remain bits
+    uint8_t  tmp;
+    uint8_t  resv0;
+    uint16_t resv1;
+}bitstream_t;
+
+#endif//__BITSTREAM_H__

etc/ccu_config.json

@@ -0,0 +1,119 @@
+{
+
+  "TCU_ID": 0,
+  "CCU_SN" : "TC2025010210002",
+  "CCU_ProductID" : "YT800KW",
+  "CCU_VendorID" : "TCharge Co.,Ltd",
+  "CCU_Available" : true,
+
+  "enalbe_offline_price":true,
+  "ISO4217_CurrencySymbol" : "CNY",
+  "ISO4217_MinorUnit" : 100,
+  "ISO4217_LeastSign" : 100,
+
+  "enable_WATFB":true,
+  "enable_GATFB":true,
+  "enable_EMGFB":true,
+  "enable_SMOKE":false,
+  "enable_LGPTA":true,
+  "enable_LGPTB":false,
+  "enable_POWERLOSS":false,
+
+  "enable_FanFBA":true,
+  "enable_FanFBB":true,
+  "enable_FanFBC":false,
+  "enable_FanPWM":false,
+  "enable_BoxTempNum":2,
+  "enable_SSR1":true,
+  "enable_SSR2":false,
+  "enable_SSR3":false,
+
+  "BoxTempThreshold":60,
+
+  "username": "test",
+  "password": "HCYhMPmnSS8M5id6",
+
+  "GUN_Numb" : 2,
+  "GUN_config" : [{
+		"connectorId" : 1,
+		"GUN_Type": "GBDC",
+		"GUN_Available" : true,
+		"GUN_maxI": 200,
+
+		"slac_ifname": "eth3",
+		"can_ifname": "can0",
+
+		"QRCode_enable" : true,
+		"QRCode_URL" : "https://abc",
+    
+		"requestPowerByMinutes":false,
+		"requestPowerByPowerKW":false,
+		"requestPowerBySOC":false,
+		"GUNTempThreshold":100
+  }, {
+		"connectorId" : 2,
+		"GUN_type": "CCS1",
+		"GUN_Available" : false,
+		"GUN_maxI": 250,
+
+		"slac_ifname": "eth2",
+		"can_ifname": "can1",
+
+		"QRCode_enable" : true,
+		"QRCode_URL" : "https://abc",
+    
+		"requestPowerByMinutes":false,
+		"requestPowerByPowerKW":false,
+		"requestPowerBySOC":false,
+		"GUNTempThreshold":100
+  }],
+
+  "pcuhw":{
+    "enable" : false,
+    "connect_ip_string": "192.168.11.1",
+    "connect_port": 502,
+    "enable_ssl": true
+  },
+  
+  "pcutc":{
+    "enable" : true,
+    "connect_ip_string": "eth0",
+    "connect_port": 502,
+    "enable_ssl": false
+  },
+
+  "qttcu":{
+    "enable" : true,
+    "connect_ip_string": "eth0",
+    "connect_port": 3001,
+    "enable_ssl": false
+  },
+
+  "ocpp16" :[{
+    "enable" : true,
+    "connect_ip_string" : "47.102.124.18",
+    "connect_port" : 80,
+    "ssl_ca_filepath": "~/app_run/ca_ocpp16/ca.crt",
+    "ssl_cert_filepath": "~/app_run/ca_ocpp16/client.crt",
+    "ssl_private_key_filepath": "~/app_run/ca_ocpp16/client.key",
+    "enable_ssl": false
+  },{
+    "enable" : false,
+    "connect_ip_string" : "47.102.124.18",
+    "connect_port" : 80,
+    "ssl_ca_filepath": "~/app_run/ca_ocpp16/ca.crt",
+    "ssl_cert_filepath": "~/app_run/ca_ocpp16/client.crt",
+    "ssl_private_key_filepath": "~/app_run/ca_ocpp16/client.key",
+    "enable_ssl": false
+  }],
+
+  "ocpp21" :[{
+    "enable" : false,
+    "connect_ip_string" : "47.102.124.18",
+    "connect_port" : 80,
+    "ssl_ca_filepath": "~/app_run/ca_ocpp21/ca.crt",
+    "ssl_cert_filepath": "~/app_run/ca_ocpp21/client.crt",
+    "ssl_private_key_filepath": "~/app_run/ca_ocpp21/client.key",
+    "enable_ssl": false
+  }]
+}

etc/ccu_config_lu.json

@@ -0,0 +1,102 @@
+{
+
+  "TCU_ID": 0,
+  "CCU_SN" : "TC2025010210002",
+  "CCU_ProductID" : "YT800KW",
+  "CCU_VendorID" : "TCharge lto",
+  "CCU_Available" : true,
+
+  "BoxOverTemp_Warning":30,
+  "BoxOverTemp_Stopping":70,
+
+  "username": "test",
+  "password": "HCYhMPmnSS8M5id6",
+
+  "enalbe_offline_price":true,
+  "ISO4217_CurrencySymbol" : "CNY",
+  "ISO4217_MinorUnit" : 100,
+  "ISO4217_LeastSign" : 100,
+
+  "GUN_Numb" : 2,
+  "GUN_config" : [{
+		"connectorId" : 1,
+		"GUN_Type": "GBDC",
+		"GUN_Available" : true,
+		"GUN_maxI": 200,
+
+		"slac_ifname": "eth3",
+		"can_ifname": "can0",
+
+		"QRCode_enable" : true,
+		"QRCode_URL" : "https://abc",
+    
+		"requestPowerByMinutes":true,
+		"requestPowerByPowerKW":true,
+		"requestPowerBySOC":true,
+		"GUNOverTemp_Warning":30,
+		"GUNOverTemp_Stopping":70
+  }, {
+		"connectorId" : 2,
+		"GUN_type": "CCS1",
+		"GUN_Available" : true,
+		"GUN_maxI": 250,
+		"slac_ifname": "eth2",
+		"can_ifname": "can1",
+		"QRCode_enable" : true,
+		"QRCode_URL" : "https://abc",
+	  "requestPowerByMinutes":true,
+	  "requestPowerByPowerKW":true,
+	  "requestPowerBySOC":true,
+		"GUNOverTemp_Warning":30,
+		"GUNOverTemp_Stopping":70
+  }],
+
+  "pcuhw":{
+    "enable" : false,
+    "connect_ip_string": "192.168.11.1",
+    "connect_port": 502,
+    "enable_ssl": true
+  },
+  
+  "pcutc":{
+    "enable" : true,
+    "connect_ip_string": "192.168.11.31",
+    "connect_port": 502,
+    "enable_ssl": false
+  },
+
+  "qttcu":{
+    "enable" : true,
+    "connect_ip_string": "192.168.11.22",
+    "connect_port": 3001,
+    "enable_ssl": false
+  },
+
+  "ocpp16" :[{
+    "enable" : true,
+    "connect_ip_string" : "47.102.124.18",
+    "connect_port" : 80,
+    "ssl_ca_filepath": "~/app_run/etc/ca.crt",
+    "ssl_cert_filepath": "~/app_run/etc/client.crt",
+    "ssl_private_key_filepath": "~/app_run/etc/client.key",
+    "enable_ssl": false
+  },{
+    "enable" : false,
+    "connect_ip_string" : "47.102.124.18",
+    "connect_port" : 80,
+    "ssl_ca_filepath": "~/app_run/etc/ca.crt",
+    "ssl_cert_filepath": "~/app_run/etc/client.crt",
+    "ssl_private_key_filepath": "~/app_run/etc/client.key",
+    "enable_ssl": false
+  }],
+
+  "ocpp21" :[{
+    "enable" : false,
+    "connect_ip_string" : "47.102.124.18",
+    "connect_port" : 80,
+    "ssl_ca_filepath": "~/app_run/etc/ca.crt",
+    "ssl_cert_filepath": "~/app_run/etc/client.crt",
+    "ssl_private_key_filepath": "~/app_run/etc/client.key",
+    "enable_ssl": false
+  }]
+}

etc/ocpp16_ChargingPrice.json

@@ -0,0 +1,31 @@
+{
+	"type" : "Energy",
+	"timeZone" : "Asia/Shanghai",
+	"minAllowBalance" : "1.0",
+	"price" : [
+		{
+			"startTime" : "2024-12-20T20:30:00Z", 
+			"stopTime" : "2024-12-21T04:30:00Z", 
+			
+			"electrPrice" : "1.0",
+			"servicePrice" : "1.0", 
+			"durationPrice" : "1.0"
+		},
+		{
+			"startTime" : "2024-12-20T20:30:00Z", 
+			"stopTime" : "2024-12-21T04:30:00Z", 
+			
+			"electrPrice" : "1.0",
+			"servicePrice" : "1.0", 
+			"durationPrice" : "1.0"
+		},
+		{
+			"startTime" : "2024-12-20T20:30:00Z", 
+			"stopTime" : "2024-12-21T04:30:00Z", 
+			
+			"electrPrice" : "1.0",
+			"servicePrice" : "1.0", 
+			"durationPrice" : "1.0"
+		}
+	]
+}

etc/ocpp16_ChargingProfiles.json

@@ -0,0 +1,78 @@
+{
+	"count" : 2,
+	"maxLength" : 20,
+	"ChargingProfiles" : [
+		{
+			"chargingProfileId" : 0, 
+			"connectorId" : 0, 
+			"stackLevel" : 0, 
+			
+			"chargingProfilePurpose" : "ChargePointMaxProfile",
+			"chargingProfileKind" : "Absolute", 
+			"recurrencyKind" : "NULL", 
+
+			"validFrom" : "2024-12-20T20:30:00Z", 
+			"validTo" : "2024-12-21T04:30:00Z", 
+
+			"chargingSchedule" : {
+				"duration" : 0, 
+				"startTime" : "2024-12-20T20:30:00Z", 
+				"chargingRateUnit" : "W", 
+				"minChargingRate" : 200,
+				"chargingSchedulePeriod" : [{
+					"startPeriod" : 0,
+					"limit" : 200000, 
+					"numberPhases" : 3
+				}]
+			}
+		},
+		{
+			"chargingProfileId" : 0, 
+			"connectorId" : 0, 
+			"stackLevel" : 0, 
+			
+			"chargingProfilePurpose" : "TxDefaultProfile",
+			"chargingProfileKind" : "Absolute", 
+			"recurrencyKind" : "NULL", 
+
+			"validFrom" : "2024-12-20T20:30:00Z", 
+			"validTo" : "2024-12-21T04:30:00Z", 
+
+			"chargingSchedule" : {
+				"duration" : 0, 
+				"startTime" : "2024-12-20T20:30:00Z", 
+				"chargingRateUnit" : "W", 
+				"minChargingRate" : 200,
+				"chargingSchedulePeriod" : [{
+					"startPeriod" : 0,
+					"limit" : 200000, 
+					"numberPhases" : 3
+				}]
+			}
+		},
+		{
+			"chargingProfileId" : 0, 
+			"connectorId" : 0, 
+			"stackLevel" : 0, 
+			
+			"chargingProfilePurpose" : "TxProfile",
+			"chargingProfileKind" : "Absolute", 
+			"recurrencyKind" : "NULL", 
+
+			"validFrom" : "2024-12-20T20:30:00Z", 
+			"validTo" : "2024-12-21T04:30:00Z", 
+
+			"chargingSchedule" : {
+				"duration" : 0, 
+				"startTime" : "2024-12-20T20:30:00Z", 
+				"chargingRateUnit" : "W", 
+				"minChargingRate" : 200,
+				"chargingSchedulePeriod" : [{
+					"startPeriod" : 0,
+					"limit" : 200000, 
+					"numberPhases" : 3
+				}]
+			}
+		}
+	]
+}

etc/ocpp16_OfflineChargingPrice.json

@@ -0,0 +1,31 @@
+{
+	"type" : "Energy",
+	"timeZone" : "Asia/Shanghai",
+	"minAllowBalance" : "1.0",
+	"price" : [
+		{
+			"startTime" : "2024-12-20T20:30:00Z", 
+			"stopTime" : "2024-12-21T04:30:00Z", 
+			
+			"electrPrice" : "1.0",
+			"servicePrice" : "1.0", 
+			"durationPrice" : "1.0"
+		},
+		{
+			"startTime" : "2024-12-20T20:30:00Z", 
+			"stopTime" : "2024-12-21T04:30:00Z", 
+			
+			"electrPrice" : "1.0",
+			"servicePrice" : "1.0", 
+			"durationPrice" : "1.0"
+		},
+		{
+			"startTime" : "2024-12-20T20:30:00Z", 
+			"stopTime" : "2024-12-21T04:30:00Z", 
+			
+			"electrPrice" : "1.0",
+			"servicePrice" : "1.0", 
+			"durationPrice" : "1.0"
+		}
+	]
+}

etc/ocpp16_OfflineChargingRecords.json

@@ -0,0 +1,23 @@
+{
+	"count" : 2,
+	"maxLength" : 2000,
+	"maxCacheDays" : 7,
+	"ChargingRecords" : [
+		{
+			"connectorId" : 0, 
+			"transactionId" : 0, 
+			"start_Datetime" : "2024-12-20T20:30:00Z", 
+			"end_Datetime" : "2024-12-21T04:30:00Z",
+			"start_MeterKWh" : 200000,
+			"end_MeterKWh" : 200000
+		},
+		{
+			"connectorId" : 0, 
+			"transactionId" : 0, 
+			"start_Datetime" : "2024-12-20T20:30:00Z", 
+			"end_Datetime" : "2024-12-21T04:30:00Z",
+			"start_MeterKWh" : 200000,
+			"end_MeterKWh" : 200000
+		}
+	]
+}

etc/ocpp16_authorization.json

@@ -0,0 +1,10 @@
+{
+	"LocalAuthorizationList" : [
+		{"idTag" : "NFCA0004010203040508", "expiryDate" : "2025-12-13T23:59:59Z", "parentIdTag" : "NULL", "status" : "Invalid"},
+		{"idTag" : "NFCA0004010203040509", "expiryDate" : "2025-12-13T23:59:59Z", "parentIdTag" : "NULL", "status" : "Invalid"}
+	],
+	"AuthorizationCache" : [
+		{"idTag" : "NFCA0004010203040506", "expiryDate" : "2025-12-13T23:59:59Z", "parentIdTag" : "NULL", "status" : "Invalid"},
+		{"idTag" : "NFCA0004010203040507", "expiryDate" : "2025-12-13T23:59:59Z", "parentIdTag" : "NULL", "status" : "Invalid"}
+	]
+}

etc/ocpp16_configkey.json

@@ -0,0 +1,59 @@
+{
+	"CoreProfile" : {
+		"AllowOfflineTxForUnknownId" : false,
+		"AuthorizationCacheEnabled" : true,
+		"AuthorizeRemoteTxRequests" : false,
+		"BlinkRepeat" : 100,
+		
+		"ClockAlignedDataInterval" : 0,
+		"ConnectionTimeOut" : 10,
+		"ConnectorPhaseRotation" : "0.RST,1.RST,2.RTS",
+		"ConnectorPhaseRotationMaxLength" : 3,
+		"GetConfigurationMaxKeys" : 45,
+		"HeartbeatInterval" :30,
+		"LightIntensity" : 50,
+		"LocalAuthorizeOffline" : true,
+		"LocalPreAuthorize" : true,
+		"MaxEnergyOnInvalidId" : 10000000000,
+		"MeterValuesAlignedData" : "Current.Import, Energy.Active.Import.Register, Power.Active.Import, SoC, Temperature, Voltage",
+		"MeterValuesAlignedDataMaxLength" : 6,
+		"MeterValuesSampledData" : "Current.Import, Energy.Active.Import.Register, Power.Active.Import, SoC, Temperature, Voltage",
+		"MeterValuesSampledDataMaxLength" : 6,
+		"MeterValueSampleInterval" : 30,
+		"MinimumStatusDuration" : 100,
+		"NumberOfConnectors" : 2,
+		"ResetRetries" : 3,
+		"StopTransactionOnEVSideDisconnect" : true,
+		"StopTransactionOnInvalidId" : true,
+		"StopTxnAlignedData" : "Energy.Active.Import.Register, SoC",
+		"StopTxnAlignedDataMaxLength" : 2,
+		"StopTxnSampledData" : "Energy.Active.Import.Register, SoC",
+		"StopTxnSampledDataMaxLength" : 2,
+		"SupportedFeatureProfiles" : "Core, FirmwareManagement, LocalAuthListManagement, Reservation, SmartCharging, RemoteTrigger",
+		"SupportedFeatureProfilesMaxLength" : 6,
+		"TransactionMessageAttempts" : 3,
+		"TransactionMessageRetryInterval" : 60,
+		"UnlockConnectorOnEVSideDisconnect" : false,
+		"WebSocketPingInterval" : 60,
+		"AuthorizationKey" : "0000000",
+		"AuthorizationCacheMaxLength" : 100
+	},
+	
+	"LocalAuthListManagementProfile" : {
+		"LocalAuthListEnabled" : true,
+		"LocalAuthListMaxLength" : 100,
+		"SendLocalListMaxLength" : 100
+	},
+	
+	"ReservationProfile" : {
+		"ReserveConnectorZeroSupported" : false
+	},
+	
+	"SmartChargingProfile" : {
+		"ChargeProfileMaxStackLevel" : 3,
+		"ChargingScheduleAllowedChargingRateUnit" : "Power,Current",
+		"ChargingScheduleMaxPeriods" : 10,
+		"ConnectorSwitch3to1PhaseSupported" : false,
+		"MaxChargingProfilesInstalled" : 5
+	}
+}

etc/pcu_config.json

@@ -0,0 +1,17 @@
+{
+  "listen_if_name" : "eth0",
+  "listen_ip_string" : "NULL",
+  "listen_port": 502,
+
+  "acdc_can_ifame" : "can1",
+  "adc_can_bitrate" : 250000,
+  "pdu_can_ifame" : "can0",
+  "pdu_can_bitrate" : 250000,
+
+  "GUN_NUMB" : 2,
+  "PDU_NUMB" : 2,
+  "ACDC_NUMB" : 2,
+  "ACDC_unit_kW" : 40,
+  
+  "ACDC_module_vendor_name": "ACDC_HuaWei"
+}

getVersion.c

@@ -0,0 +1,162 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+/*
+***************************************************************************************************
+**   touch /home/root/app_run/bin/app_CCU_V1R2B20250512
+**   ln -s /home/root/app_run/bin/app_CCU_V1R2B20250512 /home/root/app_run/bin/app_CCU
+**   touch /home/root/app_run/bin/app_TCU_V1R2B20250611
+**   ln -s /home/root/app_run/bin/app_TCU_V1R2B20250611 /home/root/app_run/bin/app_TCU
+**   touch /home/root/app_run/bin/app_PCU_V1R2B20250710
+**   ln -s /home/root/app_run/bin/app_PCU_V1R2B20250710 /home/root/app_run/bin/app_PCU 
+**   touch /home/root/app_run/bin/YT800KW_V1R2B20250407
+**   ln -s /home/root/app_run/bin/YT800KW_V1R2B20250407 /home/root/app_run/bin/HWVersion 
+***************************************************************************************************
+*/
+
+
+/*
+**  int major;
+**  int minor;
+**  int build;
+**  char linkname[256];
+**  int ret = get_App_Version("app_CCU", linkname, sizeof(linkname), &major, &minor, &build)
+**  if (ret == 0)
+**  {
+**      
+**  }
+*/
+int get_App_Version(const char* appname, char* linkname, int linkname_size, int *major, int *minor, int *build)
+{
+    if (appname == NULL) return -1;
+    if (linkname == NULL) return -1;
+    if (linkname_size < 256) return -1;
+    if (major == NULL) return -1; *major=0;
+    if (minor == NULL) return -1; *minor=0;
+    if (build == NULL) return -1; *build=0;
+    
+    char fullname[256];
+    memset(linkname, 0, linkname_size);
+    sprintf(fullname, "/home/root/app_run/bin/%s", appname);
+    int ret = readlink(fullname, linkname, linkname_size);
+    printf("%s.linkname=%s\n", appname, linkname);
+    if (0 <= ret && ret < linkname_size)
+    {
+        char* basename = strstr(linkname, appname);
+        if (strncmp(basename, "app_CCU", 7)==0)
+        {
+            sscanf(basename, "app_CCU_V%dR%dB%d", major, minor, build);
+            sprintf(linkname, "%s", basename);
+            // printf("%s_%d_%d_%d\n", appname, *major, *minor, *build);
+            return 0;
+        }
+        if (strncmp(basename, "app_TCU", 7)==0)
+        {
+            sscanf(basename, "app_TCU_V%dR%dB%d", major, minor, build);
+            sprintf(linkname, "%s", basename);
+            // printf("%s_%d_%d_%d\n", appname, *major, *minor, *build);
+            return 0;
+        }
+        if (strncmp(basename, "app_PCU", 7)==0)
+        {
+            sscanf(basename, "app_PCU_V%dR%dB%d", major, minor, build);
+            sprintf(linkname, "%s", basename);
+            // printf("%s_%d_%d_%d\n", appname, *major, *minor, *build);
+            return 0;
+        }
+        return -1;
+    }
+    return -1;
+}
+/*
+**  char HWString[256];
+**  int ret = get_HW_Version(HWString, sizeof(HWString))
+**  if (ret == 0)
+**  {
+**      
+**  }
+*/
+int get_HW_Version(char* version, int version_size)
+{
+    if (version == NULL) return -1;
+    if (version_size < 256) return -1;
+    memset(version, 0, version_size);
+    int ret = readlink("/home/root/app_run/bin/HWVersion", version, version_size);
+    if (0 <= ret && ret < version_size)
+    {
+        version[ret] = '\0';
+        // printf("HW.LinkString=%s, ret=%d\n", version, ret);
+        return 0;
+    }
+    return -1;
+}
+
+
+int main(int argc, char* argv[])
+{
+    if (argc != 2)
+    {
+        printf("\n\n\tUsage:\n");
+        printf("\tgetVersion app_CCU\n");
+        printf("\tgetVersion app_TCU\n");
+        printf("\tgetVersion app_PCU\n");
+        printf("\tgetVersion HW\n");
+        return -1;
+    }
+    if (strncmp(argv[1], "app_CCU", 7) == 0)
+    {
+        int major;
+        int minor;
+        int build;
+        char linkname[256];
+        int ret = get_App_Version(argv[1], linkname, sizeof(linkname), &major, &minor, &build);
+        if (ret == 0)
+        {
+            printf("linkname=%s, major:%d, minor:%d, build:%d\n", linkname, major, minor, build);
+        }else{
+            printf("failed\n");
+        }
+    }
+    if (strncmp(argv[1], "app_TCU", 7) == 0)
+    {
+        int major;
+        int minor;
+        int build;
+        char linkname[256];
+        int ret = get_App_Version(argv[1], linkname, sizeof(linkname), &major, &minor, &build);
+        if (ret == 0)
+        {
+            printf("linkname=%s, major:%d, minor:%d, build:%d\n", linkname, major, minor, build);
+        }else{
+            printf("failed.\n");
+        }
+    }
+    if (strncmp(argv[1], "app_PCU", 7) == 0)
+    {
+        int major;
+        int minor;
+        int build;
+        char linkname[256];
+        int ret = get_App_Version(argv[1], linkname, sizeof(linkname), &major, &minor, &build);
+        if (ret == 0)
+        {
+            printf("linkname=%s, major:%d, minor:%d, build:%d\n", linkname, major, minor, build);
+        }else{
+            printf("failed\n");
+        }
+    }
+    if (strncmp(argv[1], "HW", 2) == 0)
+    {
+        char linkname[256];
+        int ret = get_HW_Version(linkname, sizeof(linkname));
+        if (ret == 0)
+        {
+            printf("HW.linkname=%s\n", linkname);
+        }else{
+            printf("failed.\n");
+        }
+    }
+    return 0;
+}

include/gpiod.h

@@ -0,0 +1,1775 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * This file is part of libgpiod.
+ *
+ * Copyright (C) 2017-2018 Bartosz Golaszewski <bartekgola@gmail.com>
+ */
+
+#ifndef __LIBGPIOD_GPIOD_H__
+#define __LIBGPIOD_GPIOD_H__
+
+#include <stdbool.h>
+#include <stdlib.h>
+#include <time.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @file gpiod.h
+ */
+
+/**
+ * @mainpage libgpiod public API
+ *
+ * This is the complete documentation of the public API made available to
+ * users of libgpiod.
+ *
+ * <p>The public header is logically split into two high-level parts: the
+ * simple API and the low-level API. The former allows users to easily
+ * interact with the GPIOs in the system without dealing with the low-level
+ * data structures and resource control. The latter gives the user much more
+ * fine-grained control over the GPIO interface.
+ *
+ * <p>The low-level API is further logically split into several parts such
+ * as: GPIO chip & line operators, iterators, GPIO events handling etc.
+ *
+ * <p>General note on error handling: all routines exported by libgpiod  set
+ * errno to one of the error values defined in errno.h upon failure. The way
+ * of notifying the caller that an error occurred varies between functions,
+ * but in general a function that returns an int, returns -1 on error, while
+ * a function returning a pointer bails out on error condition by returning
+ * a NULL pointer.
+ */
+
+struct gpiod_chip;
+struct gpiod_line;
+struct gpiod_chip_iter;
+struct gpiod_line_iter;
+struct gpiod_line_bulk;
+
+/**
+ * @defgroup common Common helper macros
+ * @{
+ *
+ * Commonly used utility macros.
+ */
+
+/**
+ * @brief Makes symbol visible.
+ */
+#define GPIOD_API		__attribute__((visibility("default")))
+
+/**
+ * @brief Marks a function argument or variable as potentially unused.
+ */
+#define GPIOD_UNUSED		__attribute__((unused))
+
+/**
+ * @brief Shift 1 by given offset.
+ * @param nr Bit position.
+ * @return 1 shifted by nr.
+ */
+#define GPIOD_BIT(nr)		(1UL << (nr))
+
+/**
+ * @brief Marks a public function as deprecated.
+ */
+#define GPIOD_DEPRECATED	__attribute__((deprecated))
+
+/**
+ * @}
+ *
+ * @defgroup high_level High-level API
+ * @{
+ *
+ * Simple high-level routines for straightforward GPIO manipulation without
+ * the need to use the gpiod_* structures or to keep track of resources.
+ */
+
+/**
+ * @brief Miscellaneous GPIO flags.
+ */
+enum {
+	GPIOD_CTXLESS_FLAG_OPEN_DRAIN		= GPIOD_BIT(0),
+	/**< The line is an open-drain port. */
+	GPIOD_CTXLESS_FLAG_OPEN_SOURCE		= GPIOD_BIT(1),
+	/**< The line is an open-source port. */
+	GPIOD_CTXLESS_FLAG_BIAS_DISABLE		= GPIOD_BIT(2),
+	/**< The line has neither either pull-up nor pull-down resistor */
+	GPIOD_CTXLESS_FLAG_BIAS_PULL_DOWN	= GPIOD_BIT(3),
+	/**< The line has pull-down resistor enabled */
+	GPIOD_CTXLESS_FLAG_BIAS_PULL_UP		= GPIOD_BIT(4),
+	/**< The line has pull-up resistor enabled */
+};
+
+/**
+ * @brief Read current value from a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offset Offset of the GPIO line.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @return 0 or 1 (GPIO value) if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_get_value(const char *device, unsigned int offset,
+			    bool active_low, const char *consumer) GPIOD_API;
+
+/**
+ * @brief Read current value from a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offset Offset of the GPIO line.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param flags The flags for the line.
+ * @return 0 or 1 (GPIO value) if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_get_value_ext(const char *device, unsigned int offset,
+				bool active_low, const char *consumer,
+				int flags) GPIOD_API;
+
+/**
+ * @brief Read current values from a set of GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offsets Array of offsets of lines whose values should be read.
+ * @param values Buffer in which the values will be stored.
+ * @param num_lines Number of lines, must be > 0.
+ * @param active_low The active state of the lines - true if low.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_get_value_multiple(const char *device,
+				     const unsigned int *offsets, int *values,
+				     unsigned int num_lines, bool active_low,
+				     const char *consumer) GPIOD_API;
+
+/**
+ * @brief Read current values from a set of GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offsets Array of offsets of lines whose values should be read.
+ * @param values Buffer in which the values will be stored.
+ * @param num_lines Number of lines, must be > 0.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param flags The flags for the lines.
+ * @return 0 if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_get_value_multiple_ext(const char *device,
+					 const unsigned int *offsets,
+					 int *values, unsigned int num_lines,
+					 bool active_low, const char *consumer,
+					 int flags) GPIOD_API;
+
+/**
+ * @brief Simple set value callback signature.
+ */
+typedef void (*gpiod_ctxless_set_value_cb)(void *);
+
+/**
+ * @brief Set value of a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offset The offset of the GPIO line.
+ * @param value New value (0 or 1).
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param cb Optional callback function that will be called right after setting
+ *           the value. Users can use this, for example, to pause the execution
+ *           after toggling a GPIO.
+ * @param data Optional user data that will be passed to the callback function.
+ * @return 0 if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_set_value(const char *device, unsigned int offset, int value,
+			    bool active_low, const char *consumer,
+			    gpiod_ctxless_set_value_cb cb,
+			    void *data) GPIOD_API;
+
+/**
+ * @brief Set value of a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offset The offset of the GPIO line.
+ * @param value New value (0 or 1).
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param cb Optional callback function that will be called right after setting
+ *           the value. Users can use this, for example, to pause the execution
+ *           after toggling a GPIO.
+ * @param data Optional user data that will be passed to the callback function.
+ * @param flags The flags for the line.
+ * @return 0 if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_set_value_ext(const char *device, unsigned int offset,
+				int value, bool active_low,
+				const char *consumer,
+				gpiod_ctxless_set_value_cb cb,
+				void *data, int flags) GPIOD_API;
+
+/**
+ * @brief Set values of multiple GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offsets Array of offsets of lines the values of which should be set.
+ * @param values Array of integers containing new values.
+ * @param num_lines Number of lines, must be > 0.
+ * @param active_low The active state of the lines - true if low.
+ * @param consumer Name of the consumer.
+ * @param cb Optional callback function that will be called right after setting
+ *           all values. Works the same as in ::gpiod_ctxless_set_value.
+ * @param data Optional user data that will be passed to the callback function.
+ * @return 0 if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_set_value_multiple(const char *device,
+				     const unsigned int *offsets,
+				     const int *values, unsigned int num_lines,
+				     bool active_low, const char *consumer,
+				     gpiod_ctxless_set_value_cb cb,
+				     void *data) GPIOD_API;
+
+/**
+ * @brief Set values of multiple GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offsets Array of offsets of lines the values of which should be set.
+ * @param values Array of integers containing new values.
+ * @param num_lines Number of lines, must be > 0.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param cb Optional callback function that will be called right after setting
+ *           all values. Works the same as in ::gpiod_ctxless_set_value.
+ * @param data Optional user data that will be passed to the callback function.
+ * @param flags The flags for the lines.
+ * @return 0 if the operation succeeds, -1 on error.
+ */
+int gpiod_ctxless_set_value_multiple_ext(const char *device,
+					 const unsigned int *offsets,
+					 const int *values,
+					 unsigned int num_lines,
+					 bool active_low,
+					 const char *consumer,
+					 gpiod_ctxless_set_value_cb cb,
+					 void *data, int flags) GPIOD_API;
+
+/**
+ * @brief Event types that the ctxless event monitor can wait for.
+ */
+enum {
+	/**< Wait for rising edge events only. */
+	GPIOD_CTXLESS_EVENT_RISING_EDGE = 1,
+	/**< Wait for falling edge events only. */
+	GPIOD_CTXLESS_EVENT_FALLING_EDGE,
+	/**< Wait for both types of events. */
+	GPIOD_CTXLESS_EVENT_BOTH_EDGES,
+};
+
+/**
+ * @brief Event types that can be passed to the ctxless event callback.
+ */
+enum {
+	GPIOD_CTXLESS_EVENT_CB_TIMEOUT = 1,
+	/**< Waiting for events timed out. */
+	GPIOD_CTXLESS_EVENT_CB_RISING_EDGE,
+	/**< Rising edge event occured. */
+	GPIOD_CTXLESS_EVENT_CB_FALLING_EDGE,
+	/**< Falling edge event occured. */
+};
+
+/**
+ * @brief Return status values that the ctxless event callback can return.
+ */
+enum {
+	GPIOD_CTXLESS_EVENT_CB_RET_ERR = -1,
+	/**< Stop processing events and indicate an error. */
+	GPIOD_CTXLESS_EVENT_CB_RET_OK = 0,
+	/**< Continue processing events. */
+	GPIOD_CTXLESS_EVENT_CB_RET_STOP = 1,
+	/**< Stop processing events. */
+};
+
+/**
+ * @brief Simple event callback signature.
+ *
+ * The callback function takes the following arguments: event type (int),
+ * GPIO line offset (unsigned int), event timestamp (const struct timespec *)
+ * and a pointer to user data (void *).
+ *
+ * This callback is called by the ctxless event loop functions for each GPIO
+ * event. If the callback returns ::GPIOD_CTXLESS_EVENT_CB_RET_ERR, it should
+ * also set errno.
+ */
+typedef int (*gpiod_ctxless_event_handle_cb)(int, unsigned int,
+					     const struct timespec *, void *);
+
+/**
+ * @brief Return status values that the ctxless event poll callback can return.
+ *
+ * Positive value returned from the polling callback indicates the number of
+ * events that occurred on the set of monitored lines.
+ */
+enum {
+	GPIOD_CTXLESS_EVENT_POLL_RET_STOP = -2,
+	/**< The event loop should stop processing events. */
+	GPIOD_CTXLESS_EVENT_POLL_RET_ERR = -1,
+	/**< Polling error occurred (the polling function should set errno). */
+	GPIOD_CTXLESS_EVENT_POLL_RET_TIMEOUT = 0,
+	/**< Poll timed out. */
+};
+
+/**
+ * @brief Helper structure for the ctxless event loop poll callback.
+ */
+struct gpiod_ctxless_event_poll_fd {
+	int fd;
+	/**< File descriptor number. */
+	bool event;
+	/**< Indicates whether an event occurred on this file descriptor. */
+};
+
+/**
+ * @brief Simple event poll callback signature.
+ *
+ * The poll callback function takes the following arguments: number of lines
+ * (unsigned int), an array of file descriptors on which input events should
+ * be monitored (struct gpiod_ctxless_event_poll_fd *), poll timeout
+ * (const struct timespec *) and a pointer to user data (void *).
+ *
+ * The callback should poll for input events on the set of descriptors and
+ * return an appropriate value that can be interpreted by the event loop
+ * routine.
+ */
+typedef int (*gpiod_ctxless_event_poll_cb)(unsigned int,
+				struct gpiod_ctxless_event_poll_fd *,
+				const struct timespec *, void *);
+
+/**
+ * @brief Wait for events on a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offset GPIO line offset to monitor.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param timeout Maximum wait time for each iteration.
+ * @param poll_cb Callback function to call when waiting for events.
+ * @param event_cb Callback function to call for each line event.
+ * @param data User data passed to the callback.
+ * @return 0 if no errors were encountered, -1 if an error occurred.
+ * @note The way the ctxless event loop works is described in detail in
+ *       ::gpiod_ctxless_event_loop_multiple - this is just a wrapper aound
+ *       this routine which calls it for a single GPIO line.
+ * @deprecated This function suffers from an issue where HW may not allow
+ *             setting up both rising and falling egde interrupts at the same
+ *             time.
+ */
+int gpiod_ctxless_event_loop(const char *device, unsigned int offset,
+			     bool active_low, const char *consumer,
+			     const struct timespec *timeout,
+			     gpiod_ctxless_event_poll_cb poll_cb,
+			     gpiod_ctxless_event_handle_cb event_cb,
+			     void *data) GPIOD_API GPIOD_DEPRECATED;
+
+/**
+ * @brief Wait for events on multiple GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param offsets Array of GPIO line offsets to monitor.
+ * @param num_lines Number of lines to monitor.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param timeout Maximum wait time for each iteration.
+ * @param poll_cb Callback function to call when waiting for events. Can
+ *                be NULL.
+ * @param event_cb Callback function to call on event occurrence.
+ * @param data User data passed to the callback.
+ * @return 0 no errors were encountered, -1 if an error occurred.
+ * @note The poll callback can be NULL in which case the routine will fall
+ *       back to a basic, ppoll() based callback.
+ * @deprecated This function suffers from an issue where HW may not allow
+ *             setting up both rising and falling egde interrupts at the same
+ *             time.
+ *
+ * Internally this routine opens the GPIO chip, requests the set of lines for
+ * both-edges events and calls the polling callback in a loop. The role of the
+ * polling callback is to detect input events on a set of file descriptors and
+ * notify the caller about the fds ready for reading.
+ *
+ * The ctxless event loop then reads each queued event from marked descriptors
+ * and calls the event callback. Both callbacks can stop the loop at any
+ * point.
+ *
+ * The poll_cb argument can be NULL in which case the function falls back to
+ * a default, ppoll() based callback.
+ */
+int gpiod_ctxless_event_loop_multiple(const char *device,
+				      const unsigned int *offsets,
+				      unsigned int num_lines, bool active_low,
+				      const char *consumer,
+				      const struct timespec *timeout,
+				      gpiod_ctxless_event_poll_cb poll_cb,
+				      gpiod_ctxless_event_handle_cb event_cb,
+				      void *data) GPIOD_API GPIOD_DEPRECATED;
+
+/**
+ * @brief Wait for events on a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param event_type Type of events to listen for.
+ * @param offset GPIO line offset to monitor.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param timeout Maximum wait time for each iteration.
+ * @param poll_cb Callback function to call when waiting for events.
+ * @param event_cb Callback function to call for each line event.
+ * @param data User data passed to the callback.
+ * @return 0 if no errors were encountered, -1 if an error occurred.
+ * @note The way the ctxless event loop works is described in detail in
+ *       ::gpiod_ctxless_event_monitor_multiple - this is just a wrapper aound
+ *       this routine which calls it for a single GPIO line.
+ */
+int gpiod_ctxless_event_monitor(const char *device, int event_type,
+				unsigned int offset, bool active_low,
+				const char *consumer,
+				const struct timespec *timeout,
+				gpiod_ctxless_event_poll_cb poll_cb,
+				gpiod_ctxless_event_handle_cb event_cb,
+				void *data) GPIOD_API;
+
+/**
+ * @brief Wait for events on a single GPIO line.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param event_type Type of events to listen for.
+ * @param offset GPIO line offset to monitor.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param timeout Maximum wait time for each iteration.
+ * @param poll_cb Callback function to call when waiting for events.
+ * @param event_cb Callback function to call for each line event.
+ * @param data User data passed to the callback.
+ * @param flags The flags for the line.
+ * @return 0 if no errors were encountered, -1 if an error occurred.
+ * @note The way the ctxless event loop works is described in detail in
+ *       ::gpiod_ctxless_event_monitor_multiple - this is just a wrapper aound
+ *       this routine which calls it for a single GPIO line.
+ */
+int gpiod_ctxless_event_monitor_ext(const char *device, int event_type,
+				    unsigned int offset, bool active_low,
+				    const char *consumer,
+				    const struct timespec *timeout,
+				    gpiod_ctxless_event_poll_cb poll_cb,
+				    gpiod_ctxless_event_handle_cb event_cb,
+				    void *data, int flags) GPIOD_API;
+
+/**
+ * @brief Wait for events on multiple GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param event_type Type of events to listen for.
+ * @param offsets Array of GPIO line offsets to monitor.
+ * @param num_lines Number of lines to monitor.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param timeout Maximum wait time for each iteration.
+ * @param poll_cb Callback function to call when waiting for events. Can
+ *                be NULL.
+ * @param event_cb Callback function to call on event occurrence.
+ * @param data User data passed to the callback.
+ * @return 0 no errors were encountered, -1 if an error occurred.
+ * @note The poll callback can be NULL in which case the routine will fall
+ *       back to a basic, ppoll() based callback.
+ *
+ * Internally this routine opens the GPIO chip, requests the set of lines for
+ * the type of events specified in the event_type parameter and calls the
+ * polling callback in a loop. The role of the polling callback is to detect
+ * input events on a set of file descriptors and notify the caller about the
+ * fds ready for reading.
+ *
+ * The ctxless event loop then reads each queued event from marked descriptors
+ * and calls the event callback. Both callbacks can stop the loop at any
+ * point.
+ *
+ * The poll_cb argument can be NULL in which case the function falls back to
+ * a default, ppoll() based callback.
+ */
+int gpiod_ctxless_event_monitor_multiple(
+			const char *device, int event_type,
+			const unsigned int *offsets,
+			unsigned int num_lines, bool active_low,
+			const char *consumer, const struct timespec *timeout,
+			gpiod_ctxless_event_poll_cb poll_cb,
+			gpiod_ctxless_event_handle_cb event_cb,
+			void *data) GPIOD_API;
+
+/**
+ * @brief Wait for events on multiple GPIO lines.
+ * @param device Name, path, number or label of the gpiochip.
+ * @param event_type Type of events to listen for.
+ * @param offsets Array of GPIO line offsets to monitor.
+ * @param num_lines Number of lines to monitor.
+ * @param active_low The active state of this line - true if low.
+ * @param consumer Name of the consumer.
+ * @param timeout Maximum wait time for each iteration.
+ * @param poll_cb Callback function to call when waiting for events. Can
+ *                be NULL.
+ * @param event_cb Callback function to call on event occurrence.
+ * @param data User data passed to the callback.
+ * @param flags The flags for the lines.
+ * @return 0 no errors were encountered, -1 if an error occurred.
+ * @note The poll callback can be NULL in which case the routine will fall
+ *       back to a basic, ppoll() based callback.
+ *
+ * Internally this routine opens the GPIO chip, requests the set of lines for
+ * the type of events specified in the event_type parameter and calls the
+ * polling callback in a loop. The role of the polling callback is to detect
+ * input events on a set of file descriptors and notify the caller about the
+ * fds ready for reading.
+ *
+ * The ctxless event loop then reads each queued event from marked descriptors
+ * and calls the event callback. Both callbacks can stop the loop at any
+ * point.
+ *
+ * The poll_cb argument can be NULL in which case the function falls back to
+ * a default, ppoll() based callback.
+ */
+int gpiod_ctxless_event_monitor_multiple_ext(
+			const char *device, int event_type,
+			const unsigned int *offsets,
+			unsigned int num_lines, bool active_low,
+			const char *consumer, const struct timespec *timeout,
+			gpiod_ctxless_event_poll_cb poll_cb,
+			gpiod_ctxless_event_handle_cb event_cb,
+			void *data, int flags) GPIOD_API;
+
+
+/**
+ * @brief Determine the chip name and line offset of a line with given name.
+ * @param name The name of the GPIO line to lookup.
+ * @param chipname Buffer in which the name of the GPIO chip will be stored.
+ * @param chipname_size Size of the chip name buffer.
+ * @param offset Pointer to an integer in which the line offset will be stored.
+ * @return -1 on error, 0 if the line with given name doesn't exist and 1 if
+ *         the line was found. In the first two cases the contents of chipname
+ *         and offset remain unchanged.
+ * @note The chip name is truncated if the buffer can't hold its entire size.
+ * @attention GPIO line names are not unique in the linux kernel, neither
+ *            globally nor within a single chip. This function finds the first
+ *            line with given name.
+ */
+int gpiod_ctxless_find_line(const char *name, char *chipname,
+			    size_t chipname_size,
+			    unsigned int *offset) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @defgroup chips GPIO chip operations
+ * @{
+ *
+ * Functions and data structures dealing with GPIO chips.
+ */
+
+/**
+ * @brief Open a gpiochip by path.
+ * @param path Path to the gpiochip device file.
+ * @return GPIO chip handle or NULL if an error occurred.
+ */
+struct gpiod_chip *gpiod_chip_open(const char *path) GPIOD_API;
+
+/**
+ * @brief Open a gpiochip by name.
+ * @param name Name of the gpiochip to open.
+ * @return GPIO chip handle or NULL if an error occurred.
+ *
+ * This routine appends name to '/dev/' to create the path.
+ */
+struct gpiod_chip *gpiod_chip_open_by_name(const char *name) GPIOD_API;
+
+/**
+ * @brief Open a gpiochip by number.
+ * @param num Number of the gpiochip.
+ * @return GPIO chip handle or NULL if an error occurred.
+ *
+ * This routine appends num to '/dev/gpiochip' to create the path.
+ */
+struct gpiod_chip *gpiod_chip_open_by_number(unsigned int num) GPIOD_API;
+
+/**
+ * @brief Open a gpiochip by label.
+ * @param label Label of the gpiochip to open.
+ * @return GPIO chip handle or NULL if the chip with given label was not found
+ *         or an error occured.
+ * @note If the chip cannot be found but no other error occurred, errno is set
+ *       to ENOENT.
+ */
+struct gpiod_chip *gpiod_chip_open_by_label(const char *label) GPIOD_API;
+
+/**
+ * @brief Open a gpiochip based on the best guess what the path is.
+ * @param descr String describing the gpiochip.
+ * @return GPIO chip handle or NULL if an error occurred.
+ *
+ * This routine tries to figure out whether the user passed it the path to the
+ * GPIO chip, its name, label or number as a string. Then it tries to open it
+ * using one of the gpiod_chip_open** variants.
+ */
+struct gpiod_chip *gpiod_chip_open_lookup(const char *descr) GPIOD_API;
+
+/**
+ * @brief Close a GPIO chip handle and release all allocated resources.
+ * @param chip The GPIO chip object.
+ */
+void gpiod_chip_close(struct gpiod_chip *chip) GPIOD_API;
+
+/**
+ * @brief Get the GPIO chip name as represented in the kernel.
+ * @param chip The GPIO chip object.
+ * @return Pointer to a human-readable string containing the chip name.
+ */
+const char *gpiod_chip_name(struct gpiod_chip *chip) GPIOD_API;
+
+/**
+ * @brief Get the GPIO chip label as represented in the kernel.
+ * @param chip The GPIO chip object.
+ * @return Pointer to a human-readable string containing the chip label.
+ */
+const char *gpiod_chip_label(struct gpiod_chip *chip) GPIOD_API;
+
+/**
+ * @brief Get the number of GPIO lines exposed by this chip.
+ * @param chip The GPIO chip object.
+ * @return Number of GPIO lines.
+ */
+unsigned int gpiod_chip_num_lines(struct gpiod_chip *chip) GPIOD_API;
+
+/**
+ * @brief Get the handle to the GPIO line at given offset.
+ * @param chip The GPIO chip object.
+ * @param offset The offset of the GPIO line.
+ * @return Pointer to the GPIO line handle or NULL if an error occured.
+ */
+struct gpiod_line *
+gpiod_chip_get_line(struct gpiod_chip *chip, unsigned int offset) GPIOD_API;
+
+/**
+ * @brief Retrieve a set of lines and store them in a line bulk object.
+ * @param chip The GPIO chip object.
+ * @param offsets Array of offsets of lines to retrieve.
+ * @param num_offsets Number of lines to retrieve.
+ * @param bulk Line bulk object in which to store the line handles.
+ * @return 0 on success, -1 on error.
+ */
+int gpiod_chip_get_lines(struct gpiod_chip *chip,
+			 unsigned int *offsets, unsigned int num_offsets,
+			 struct gpiod_line_bulk *bulk) GPIOD_API;
+
+/**
+ * @brief Retrieve all lines exposed by a chip and store them in a bulk object.
+ * @param chip The GPIO chip object.
+ * @param bulk Line bulk object in which to store the line handles.
+ * @return 0 on success, -1 on error.
+ */
+int gpiod_chip_get_all_lines(struct gpiod_chip *chip,
+			     struct gpiod_line_bulk *bulk) GPIOD_API;
+
+/**
+ * @brief Find a GPIO line by name among lines associated with given GPIO chip.
+ * @param chip The GPIO chip object.
+ * @param name The name of the GPIO line.
+ * @return Pointer to the GPIO line handle or NULL if the line could not be
+ *         found or an error occurred.
+ * @note In case a line with given name is not associated with given chip, the
+ *       function sets errno to ENOENT.
+ * @attention GPIO line names are not unique in the linux kernel, neither
+ *            globally nor within a single chip. This function finds the first
+ *            line with given name.
+ */
+struct gpiod_line *
+gpiod_chip_find_line(struct gpiod_chip *chip, const char *name) GPIOD_API;
+
+/**
+ * @brief Find a set of GPIO lines by names among lines exposed by this chip.
+ * @param chip The GPIO chip object.
+ * @param names Array of pointers to C-strings containing the names of the
+ *              lines to lookup. Must end with a NULL-pointer.
+ * @param bulk Line bulk object in which the located lines will be stored.
+ * @return 0 if all lines were located, -1 on error.
+ * @note If at least one line from the list could not be found among the lines
+ *       exposed by this chip, the function sets errno to ENOENT.
+ * @attention GPIO line names are not unique in the linux kernel, neither
+ *            globally nor within a single chip. This function finds the first
+ *            line with given name.
+ */
+int gpiod_chip_find_lines(struct gpiod_chip *chip, const char **names,
+			  struct gpiod_line_bulk *bulk) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @defgroup lines GPIO line operations
+ * @{
+ *
+ * Functions and data structures dealing with GPIO lines.
+ *
+ * @defgroup line_bulk Operating on multiple lines
+ * @{
+ *
+ * Convenience data structures and helper functions for storing and operating
+ * on multiple lines at once.
+ */
+
+/**
+ * @brief Maximum number of GPIO lines that can be requested at once.
+ */
+#define GPIOD_LINE_BULK_MAX_LINES	64
+
+/**
+ * @brief Helper structure for storing a set of GPIO line objects.
+ *
+ * This structure is used in all operations involving sets of GPIO lines. If
+ * a bulk object is being passed to a function while containing zero lines,
+ * the result is undefined.
+ */
+struct gpiod_line_bulk {
+	struct gpiod_line *lines[GPIOD_LINE_BULK_MAX_LINES];
+	/**< Buffer for line pointers. */
+	unsigned int num_lines;
+	/**< Number of lines currently held in this structure. */
+};
+
+/**
+ * @brief Static initializer for GPIO bulk objects.
+ *
+ * This macro simply sets the internally held number of lines to 0.
+ */
+#define GPIOD_LINE_BULK_INITIALIZER	{ { NULL }, 0 }
+
+/**
+ * @brief Initialize a GPIO bulk object.
+ * @param bulk Line bulk object.
+ *
+ * This routine simply sets the internally held number of lines to 0.
+ */
+static inline void gpiod_line_bulk_init(struct gpiod_line_bulk *bulk)
+{
+	bulk->num_lines = 0;
+}
+
+/**
+ * @brief Add a single line to a GPIO bulk object.
+ * @param bulk Line bulk object.
+ * @param line Line to add.
+ */
+static inline void gpiod_line_bulk_add(struct gpiod_line_bulk *bulk,
+				       struct gpiod_line *line)
+{
+	bulk->lines[bulk->num_lines++] = line;
+}
+
+/**
+ * @brief Retrieve the line handle from a line bulk object at given offset.
+ * @param bulk Line bulk object.
+ * @param offset Line offset.
+ * @return Line handle at given offset.
+ */
+static inline struct gpiod_line *
+gpiod_line_bulk_get_line(struct gpiod_line_bulk *bulk, unsigned int offset)
+{
+	return bulk->lines[offset];
+}
+
+/**
+ * @brief Retrieve the number of GPIO lines held by this line bulk object.
+ * @param bulk Line bulk object.
+ * @return Number of lines held by this line bulk.
+ */
+static inline unsigned int
+gpiod_line_bulk_num_lines(struct gpiod_line_bulk *bulk)
+{
+	return bulk->num_lines;
+}
+
+/**
+ * @brief Iterate over all line handles held by a line bulk object.
+ * @param bulk Line bulk object.
+ * @param line GPIO line handle. On each iteration, the subsequent line handle
+ *             is assigned to this pointer.
+ * @param lineptr Pointer to a GPIO line handle used to store the loop state.
+ */
+#define gpiod_line_bulk_foreach_line(bulk, line, lineptr)		\
+	for ((lineptr) = (bulk)->lines, (line) = *(lineptr);		\
+	     (lineptr) <= (bulk)->lines + ((bulk)->num_lines - 1);	\
+	     (lineptr)++, (line) = *(lineptr))
+
+/**
+ * @brief Iterate over all line handles held by a line bulk object (integer
+ *        counter variant).
+ * @param bulk Line bulk object.
+ * @param line GPIO line handle. On each iteration, the subsequent line handle
+ *             is assigned to this pointer.
+ * @param offset An integer variable used to store the loop state.
+ *
+ * This is a variant of ::gpiod_line_bulk_foreach_line which uses an integer
+ * variable (either signed or unsigned) to store the loop state. This offset
+ * variable is guaranteed to correspond to the offset of the current line in
+ * the bulk->lines array.
+ */
+#define gpiod_line_bulk_foreach_line_off(bulk, line, offset)		\
+	for ((offset) = 0, (line) = (bulk)->lines[0];			\
+	     (offset) < (bulk)->num_lines;				\
+	     (offset)++, (line) = (bulk)->lines[(offset)])
+
+/**
+ * @}
+ *
+ * @defgroup line_info Line info
+ * @{
+ *
+ * Definitions and functions for retrieving kernel information about both
+ * requested and free lines.
+ */
+
+/**
+ * @brief Possible direction settings.
+ */
+enum {
+	GPIOD_LINE_DIRECTION_INPUT = 1,
+	/**< Direction is input - we're reading the state of a GPIO line. */
+	GPIOD_LINE_DIRECTION_OUTPUT,
+	/**< Direction is output - we're driving the GPIO line. */
+};
+
+/**
+ * @brief Possible active state settings.
+ */
+enum {
+	GPIOD_LINE_ACTIVE_STATE_HIGH = 1,
+	/**< The active state of a GPIO is active-high. */
+	GPIOD_LINE_ACTIVE_STATE_LOW,
+	/**< The active state of a GPIO is active-low. */
+};
+
+/**
+ * @brief Possible internal bias settings.
+ */
+enum {
+	GPIOD_LINE_BIAS_AS_IS = 1,
+	/**< The internal bias state is unknown. */
+	GPIOD_LINE_BIAS_DISABLE,
+	/**< The internal bias is disabled. */
+	GPIOD_LINE_BIAS_PULL_UP,
+	/**< The internal pull-up bias is enabled. */
+	GPIOD_LINE_BIAS_PULL_DOWN,
+	/**< The internal pull-down bias is enabled. */
+};
+
+/**
+ * @brief Read the GPIO line offset.
+ * @param line GPIO line object.
+ * @return Line offset.
+ */
+unsigned int gpiod_line_offset(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read the GPIO line name.
+ * @param line GPIO line object.
+ * @return Name of the GPIO line as it is represented in the kernel. This
+ *         routine returns a pointer to a null-terminated string or NULL if
+ *         the line is unnamed.
+ */
+const char *gpiod_line_name(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read the GPIO line consumer name.
+ * @param line GPIO line object.
+ * @return Name of the GPIO consumer name as it is represented in the
+ *         kernel. This routine returns a pointer to a null-terminated string
+ *         or NULL if the line is not used.
+ */
+const char *gpiod_line_consumer(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read the GPIO line direction setting.
+ * @param line GPIO line object.
+ * @return Returns GPIOD_LINE_DIRECTION_INPUT or GPIOD_LINE_DIRECTION_OUTPUT.
+ */
+int gpiod_line_direction(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read the GPIO line active state setting.
+ * @param line GPIO line object.
+ * @return Returns GPIOD_LINE_ACTIVE_STATE_HIGH or GPIOD_LINE_ACTIVE_STATE_LOW.
+ */
+int gpiod_line_active_state(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read the GPIO line bias setting.
+ * @param line GPIO line object.
+ * @return Returns GPIOD_LINE_BIAS_PULL_UP, GPIOD_LINE_BIAS_PULL_DOWN,
+ *         GPIOD_LINE_BIAS_DISABLE or GPIOD_LINE_BIAS_AS_IS.
+ */
+int gpiod_line_bias(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Check if the line is currently in use.
+ * @param line GPIO line object.
+ * @return True if the line is in use, false otherwise.
+ *
+ * The user space can't know exactly why a line is busy. It may have been
+ * requested by another process or hogged by the kernel. It only matters that
+ * the line is used and we can't request it.
+ */
+bool gpiod_line_is_used(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Check if the line is an open-drain GPIO.
+ * @param line GPIO line object.
+ * @return True if the line is an open-drain GPIO, false otherwise.
+ */
+bool gpiod_line_is_open_drain(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Check if the line is an open-source GPIO.
+ * @param line GPIO line object.
+ * @return True if the line is an open-source GPIO, false otherwise.
+ */
+bool gpiod_line_is_open_source(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Re-read the line info.
+ * @param line GPIO line object.
+ * @return 0 if the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * The line info is initially retrieved from the kernel by
+ * gpiod_chip_get_line() and is later re-read after every successful request.
+ * Users can use this function to manually re-read the line info when needed.
+ *
+ * We currently have no mechanism provided by the kernel for keeping the line
+ * info synchronized and for the sake of speed and simplicity of this low-level
+ * library we don't want to re-read the line info automatically everytime
+ * a property is retrieved. Any daemon using this library must track the state
+ * of lines on its own and call this routine if needed.
+ *
+ * The state of requested lines is kept synchronized (or rather cannot be
+ * changed by external agents while the ownership of the line is taken) so
+ * there's no need to call this function in that case.
+ */
+int gpiod_line_update(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Check if the line info needs to be updated.
+ * @param line GPIO line object.
+ * @return Always returns false.
+ * @deprecated This mechanism no longer exists in the library and this function
+ *             does nothing.
+ */
+bool
+gpiod_line_needs_update(struct gpiod_line *line) GPIOD_API GPIOD_DEPRECATED;
+
+/**
+ * @}
+ *
+ * @defgroup line_request Line requests
+ * @{
+ *
+ * Interface for requesting GPIO lines from userspace for both values and
+ * events.
+ */
+
+/**
+ * @brief Available types of requests.
+ */
+enum {
+	GPIOD_LINE_REQUEST_DIRECTION_AS_IS = 1,
+	/**< Request the line(s), but don't change current direction. */
+	GPIOD_LINE_REQUEST_DIRECTION_INPUT,
+	/**< Request the line(s) for reading the GPIO line state. */
+	GPIOD_LINE_REQUEST_DIRECTION_OUTPUT,
+	/**< Request the line(s) for setting the GPIO line state. */
+	GPIOD_LINE_REQUEST_EVENT_FALLING_EDGE,
+	/**< Only watch falling edge events. */
+	GPIOD_LINE_REQUEST_EVENT_RISING_EDGE,
+	/**< Only watch rising edge events. */
+	GPIOD_LINE_REQUEST_EVENT_BOTH_EDGES,
+	/**< Monitor both types of events. */
+};
+
+/**
+ * @brief Miscellaneous GPIO request flags.
+ */
+enum {
+	GPIOD_LINE_REQUEST_FLAG_OPEN_DRAIN	= GPIOD_BIT(0),
+	/**< The line is an open-drain port. */
+	GPIOD_LINE_REQUEST_FLAG_OPEN_SOURCE	= GPIOD_BIT(1),
+	/**< The line is an open-source port. */
+	GPIOD_LINE_REQUEST_FLAG_ACTIVE_LOW	= GPIOD_BIT(2),
+	/**< The active state of the line is low (high is the default). */
+	GPIOD_LINE_REQUEST_FLAG_BIAS_DISABLE	= GPIOD_BIT(3),
+	/**< The line has neither either pull-up nor pull-down resistor. */
+	GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_DOWN	= GPIOD_BIT(4),
+	/**< The line has pull-down resistor enabled. */
+	GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP	= GPIOD_BIT(5),
+	/**< The line has pull-up resistor enabled. */
+};
+
+/**
+ * @brief Structure holding configuration of a line request.
+ */
+struct gpiod_line_request_config {
+	const char *consumer;
+	/**< Name of the consumer. */
+	int request_type;
+	/**< Request type. */
+	int flags;
+	/**< Other configuration flags. */
+};
+
+/**
+ * @brief Reserve a single line.
+ * @param line GPIO line object.
+ * @param config Request options.
+ * @param default_val Initial line value - only relevant if we're setting
+ *                    the direction to output.
+ * @return 0 if the line was properly reserved. In case of an error this
+ *         routine returns -1 and sets the last error number.
+ *
+ * If this routine succeeds, the caller takes ownership of the GPIO line until
+ * it's released.
+ */
+int gpiod_line_request(struct gpiod_line *line,
+		       const struct gpiod_line_request_config *config,
+		       int default_val) GPIOD_API;
+
+/**
+ * @brief Reserve a single line, set the direction to input.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @return 0 if the line was properly reserved, -1 on failure.
+ */
+int gpiod_line_request_input(struct gpiod_line *line,
+			     const char *consumer) GPIOD_API;
+
+/**
+ * @brief Reserve a single line, set the direction to output.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @param default_val Initial line value.
+ * @return 0 if the line was properly reserved, -1 on failure.
+ */
+int gpiod_line_request_output(struct gpiod_line *line,
+			      const char *consumer, int default_val) GPIOD_API;
+
+/**
+ * @brief Request rising edge event notifications on a single line.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_rising_edge_events(struct gpiod_line *line,
+					  const char *consumer) GPIOD_API;
+
+/**
+ * @brief Request falling edge event notifications on a single line.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_falling_edge_events(struct gpiod_line *line,
+					   const char *consumer) GPIOD_API;
+
+/**
+ * @brief Request all event type notifications on a single line.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_both_edges_events(struct gpiod_line *line,
+					 const char *consumer) GPIOD_API;
+
+/**
+ * @brief Reserve a single line, set the direction to input.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the line was properly reserved, -1 on failure.
+ */
+int gpiod_line_request_input_flags(struct gpiod_line *line,
+				   const char *consumer, int flags) GPIOD_API;
+
+/**
+ * @brief Reserve a single line, set the direction to output.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @param default_val Initial line value.
+ * @return 0 if the line was properly reserved, -1 on failure.
+ */
+int gpiod_line_request_output_flags(struct gpiod_line *line,
+				    const char *consumer, int flags,
+				    int default_val) GPIOD_API;
+
+/**
+ * @brief Request rising edge event notifications on a single line.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_rising_edge_events_flags(struct gpiod_line *line,
+						const char *consumer,
+						int flags) GPIOD_API;
+
+/**
+ * @brief Request falling edge event notifications on a single line.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_falling_edge_events_flags(struct gpiod_line *line,
+						 const char *consumer,
+						 int flags) GPIOD_API;
+
+/**
+ * @brief Request all event type notifications on a single line.
+ * @param line GPIO line object.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_both_edges_events_flags(struct gpiod_line *line,
+					       const char *consumer,
+					       int flags) GPIOD_API;
+
+/**
+ * @brief Reserve a set of GPIO lines.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param config Request options.
+ * @param default_vals Initial line values - only relevant if we're setting
+ *                     the direction to output.
+ * @return 0 if the all lines were properly requested. In case of an error
+ *         this routine returns -1 and sets the last error number.
+ *
+ * If this routine succeeds, the caller takes ownership of the GPIO lines
+ * until they're released. All the requested lines must be prodivided by the
+ * same gpiochip.
+ */
+int gpiod_line_request_bulk(struct gpiod_line_bulk *bulk,
+			    const struct gpiod_line_request_config *config,
+			    const int *default_vals) GPIOD_API;
+
+/**
+ * @brief Reserve a set of GPIO lines, set the direction to input.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param consumer Name of the consumer.
+ * @return 0 if the lines were properly reserved, -1 on failure.
+ */
+int gpiod_line_request_bulk_input(struct gpiod_line_bulk *bulk,
+				  const char *consumer) GPIOD_API;
+
+/**
+ * @brief Reserve a set of GPIO lines, set the direction to output.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param consumer Name of the consumer.
+ * @param default_vals Initial line values.
+ * @return 0 if the lines were properly reserved, -1 on failure.
+ */
+int gpiod_line_request_bulk_output(struct gpiod_line_bulk *bulk,
+				   const char *consumer,
+				   const int *default_vals) GPIOD_API;
+
+/**
+ * @brief Request rising edge event notifications on a set of lines.
+ * @param bulk Set of GPIO lines to request.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_bulk_rising_edge_events(struct gpiod_line_bulk *bulk,
+					       const char *consumer) GPIOD_API;
+
+/**
+ * @brief Request falling edge event notifications on a set of lines.
+ * @param bulk Set of GPIO lines to request.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_bulk_falling_edge_events(struct gpiod_line_bulk *bulk,
+						const char *consumer) GPIOD_API;
+
+/**
+ * @brief Request all event type notifications on a set of lines.
+ * @param bulk Set of GPIO lines to request.
+ * @param consumer Name of the consumer.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_bulk_both_edges_events(struct gpiod_line_bulk *bulk,
+					      const char *consumer) GPIOD_API;
+
+/**
+ * @brief Reserve a set of GPIO lines, set the direction to input.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the lines were properly reserved, -1 on failure.
+ */
+int gpiod_line_request_bulk_input_flags(struct gpiod_line_bulk *bulk,
+					const char *consumer,
+					int flags) GPIOD_API;
+
+/**
+ * @brief Reserve a set of GPIO lines, set the direction to output.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @param default_vals Initial line values.
+ * @return 0 if the lines were properly reserved, -1 on failure.
+ */
+int gpiod_line_request_bulk_output_flags(struct gpiod_line_bulk *bulk,
+					 const char *consumer, int flags,
+					 const int *default_vals) GPIOD_API;
+
+/**
+ * @brief Request rising edge event notifications on a set of lines.
+ * @param bulk Set of GPIO lines to request.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_bulk_rising_edge_events_flags(
+					struct gpiod_line_bulk *bulk,
+					const char *consumer,
+					int flags) GPIOD_API;
+
+/**
+ * @brief Request falling edge event notifications on a set of lines.
+ * @param bulk Set of GPIO lines to request.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_bulk_falling_edge_events_flags(
+					struct gpiod_line_bulk *bulk,
+					const char *consumer,
+					int flags) GPIOD_API;
+
+/**
+ * @brief Request all event type notifications on a set of lines.
+ * @param bulk Set of GPIO lines to request.
+ * @param consumer Name of the consumer.
+ * @param flags Additional request flags.
+ * @return 0 if the operation succeeds, -1 on failure.
+ */
+int gpiod_line_request_bulk_both_edges_events_flags(
+					struct gpiod_line_bulk *bulk,
+					const char *consumer,
+					int flags) GPIOD_API;
+
+/**
+ * @brief Release a previously reserved line.
+ * @param line GPIO line object.
+ */
+void gpiod_line_release(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Release a set of previously reserved lines.
+ * @param bulk Set of GPIO lines to release.
+ *
+ * If the lines were not previously requested together, the behavior is
+ * undefined.
+ */
+void gpiod_line_release_bulk(struct gpiod_line_bulk *bulk) GPIOD_API;
+
+/**
+ * @brief Check if the calling user has ownership of this line.
+ * @param line GPIO line object.
+ * @return True if given line was requested, false otherwise.
+ */
+bool gpiod_line_is_requested(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Check if the calling user has neither requested ownership of this
+ *        line nor configured any event notifications.
+ * @param line GPIO line object.
+ * @return True if given line is free, false otherwise.
+ */
+bool gpiod_line_is_free(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @defgroup line_value Reading & setting line values
+ * @{
+ *
+ * Functions allowing to read and set GPIO line values for single lines and
+ * in bulk.
+ */
+
+/**
+ * @brief Read current value of a single GPIO line.
+ * @param line GPIO line object.
+ * @return 0 or 1 if the operation succeeds. On error this routine returns -1
+ *         and sets the last error number.
+ */
+int gpiod_line_get_value(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read current values of a set of GPIO lines.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param values An array big enough to hold line_bulk->num_lines values.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * If succeeds, this routine fills the values array with a set of values in
+ * the same order, the lines are added to line_bulk. If the lines were not
+ * previously requested together, the behavior is undefined.
+ */
+int gpiod_line_get_value_bulk(struct gpiod_line_bulk *bulk,
+			      int *values) GPIOD_API;
+
+/**
+ * @brief Set the value of a single GPIO line.
+ * @param line GPIO line object.
+ * @param value New value.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ */
+int gpiod_line_set_value(struct gpiod_line *line, int value) GPIOD_API;
+
+/**
+ * @brief Set the values of a set of GPIO lines.
+ * @param bulk Set of GPIO lines to reserve.
+ * @param values An array holding line_bulk->num_lines new values for lines.
+ *               A NULL pointer is interpreted as a logical low for all lines.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * If the lines were not previously requested together, the behavior is
+ * undefined.
+ */
+int gpiod_line_set_value_bulk(struct gpiod_line_bulk *bulk,
+			      const int *values) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @defgroup line_config Setting line configuration
+ * @{
+ *
+ * Functions allowing modification of config options of GPIO lines requested
+ * from user-space.
+ */
+
+/**
+ * @brief Update the configuration of a single GPIO line.
+ * @param line GPIO line object.
+ * @param direction Updated direction which may be one of
+ *                  GPIOD_LINE_REQUEST_DIRECTION_AS_IS,
+ *                  GPIOD_LINE_REQUEST_DIRECTION_INPUT, or
+ *                  GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
+ * @param flags Replacement flags.
+ * @param value The new output value for the line when direction is
+ *              GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ */
+int gpiod_line_set_config(struct gpiod_line *line, int direction,
+			  int flags, int value) GPIOD_API;
+
+/**
+ * @brief Update the configuration of a set of GPIO lines.
+ * @param bulk Set of GPIO lines.
+ * @param direction Updated direction which may be one of
+ *                  GPIOD_LINE_REQUEST_DIRECTION_AS_IS,
+ *                  GPIOD_LINE_REQUEST_DIRECTION_INPUT, or
+ *                  GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
+ * @param flags Replacement flags.
+ * @param values An array holding line_bulk->num_lines new logical values
+ *               for lines when direction is
+ *               GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
+ *               A NULL pointer is interpreted as a logical low for all lines.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * If the lines were not previously requested together, the behavior is
+ * undefined.
+ */
+int gpiod_line_set_config_bulk(struct gpiod_line_bulk *bulk,
+			       int direction, int flags,
+			       const int *values) GPIOD_API;
+
+
+/**
+ * @brief Update the configuration flags of a single GPIO line.
+ * @param line GPIO line object.
+ * @param flags Replacement flags.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ */
+int gpiod_line_set_flags(struct gpiod_line *line, int flags) GPIOD_API;
+
+/**
+ * @brief Update the configuration flags of a set of GPIO lines.
+ * @param bulk Set of GPIO lines.
+ * @param flags Replacement flags.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * If the lines were not previously requested together, the behavior is
+ * undefined.
+ */
+int gpiod_line_set_flags_bulk(struct gpiod_line_bulk *bulk,
+			      int flags) GPIOD_API;
+
+/**
+ * @brief Set the direction of a single GPIO line to input.
+ * @param line GPIO line object.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ */
+int gpiod_line_set_direction_input(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Set the direction of a set of GPIO lines to input.
+ * @param bulk Set of GPIO lines.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * If the lines were not previously requested together, the behavior is
+ * undefined.
+ */
+int
+gpiod_line_set_direction_input_bulk(struct gpiod_line_bulk *bulk) GPIOD_API;
+
+/**
+ * @brief Set the direction of a single GPIO line to output.
+ * @param line GPIO line object.
+ * @param value The logical value output on the line.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ */
+int gpiod_line_set_direction_output(struct gpiod_line *line,
+				    int value) GPIOD_API;
+
+/**
+ * @brief Set the direction of a set of GPIO lines to output.
+ * @param bulk Set of GPIO lines.
+ * @param values An array holding line_bulk->num_lines new logical values
+ *               for lines.  A NULL pointer is interpreted as a logical low
+ *               for all lines.
+ * @return 0 is the operation succeeds. In case of an error this routine
+ *         returns -1 and sets the last error number.
+ *
+ * If the lines were not previously requested together, the behavior is
+ * undefined.
+ */
+int gpiod_line_set_direction_output_bulk(struct gpiod_line_bulk *bulk,
+					 const int *values) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @defgroup line_event Line events handling
+ * @{
+ *
+ * Structures and functions allowing to poll lines for events and read them,
+ * both for individual lines as well as in bulk. Also contains functions for
+ * retrieving the associated file descriptors and operate on them for easy
+ * integration with standard unix interfaces.
+ */
+
+/**
+ * @brief Event types.
+ */
+enum {
+	GPIOD_LINE_EVENT_RISING_EDGE = 1,
+	/**< Rising edge event. */
+	GPIOD_LINE_EVENT_FALLING_EDGE,
+	/**< Falling edge event. */
+};
+
+/**
+ * @brief Structure holding event info.
+ */
+struct gpiod_line_event {
+	struct timespec ts;
+	/**< Best estimate of time of event occurrence. */
+	int event_type;
+	/**< Type of the event that occurred. */
+};
+
+/**
+ * @brief Wait for an event on a single line.
+ * @param line GPIO line object.
+ * @param timeout Wait time limit.
+ * @return 0 if wait timed out, -1 if an error occurred, 1 if an event
+ *         occurred.
+ */
+int gpiod_line_event_wait(struct gpiod_line *line,
+			  const struct timespec *timeout) GPIOD_API;
+
+/**
+ * @brief Wait for events on a set of lines.
+ * @param bulk Set of GPIO lines to monitor.
+ * @param timeout Wait time limit.
+ * @param event_bulk Bulk object in which to store the line handles on which
+ *                   events occurred. Can be NULL.
+ * @return 0 if wait timed out, -1 if an error occurred, 1 if at least one
+ *         event occurred.
+ */
+int gpiod_line_event_wait_bulk(struct gpiod_line_bulk *bulk,
+			       const struct timespec *timeout,
+			       struct gpiod_line_bulk *event_bulk) GPIOD_API;
+
+/**
+ * @brief Read next pending event from the GPIO line.
+ * @param line GPIO line object.
+ * @param event Buffer to which the event data will be copied.
+ * @return 0 if the event was read correctly, -1 on error.
+ * @note This function will block if no event was queued for this line.
+ */
+int gpiod_line_event_read(struct gpiod_line *line,
+			  struct gpiod_line_event *event) GPIOD_API;
+
+/**
+ * @brief Read up to a certain number of events from the GPIO line.
+ * @param line GPIO line object.
+ * @param events Buffer to which the event data will be copied. Must hold at
+ *               least the amount of events specified in num_events.
+ * @param num_events Specifies how many events can be stored in the buffer.
+ * @return On success returns the number of events stored in the buffer, on
+ *         failure -1 is returned.
+ */
+int gpiod_line_event_read_multiple(struct gpiod_line *line,
+				   struct gpiod_line_event *events,
+				   unsigned int num_events) GPIOD_API;
+
+/**
+ * @brief Get the event file descriptor.
+ * @param line GPIO line object.
+ * @return Number of the event file descriptor or -1 if the user tries to
+ *         retrieve the descriptor from a line that wasn't configured for
+ *         event monitoring.
+ *
+ * Users may want to poll the event file descriptor on their own. This routine
+ * allows to access it.
+ */
+int gpiod_line_event_get_fd(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Read the last GPIO event directly from a file descriptor.
+ * @param fd File descriptor.
+ * @param event Buffer in which the event data will be stored.
+ * @return 0 if the event was read correctly, -1 on error.
+ *
+ * Users who directly poll the file descriptor for incoming events can also
+ * directly read the event data from it using this routine. This function
+ * translates the kernel representation of the event to the libgpiod format.
+ */
+int gpiod_line_event_read_fd(int fd, struct gpiod_line_event *event) GPIOD_API;
+
+/**
+ * @brief Read up to a certain number of events directly from a file descriptor.
+ * @param fd File descriptor.
+ * @param events Buffer to which the event data will be copied. Must hold at
+ *               least the amount of events specified in num_events.
+ * @param num_events Specifies how many events can be stored in the buffer.
+ * @return On success returns the number of events stored in the buffer, on
+ *         failure -1 is returned.
+ */
+int gpiod_line_event_read_fd_multiple(int fd, struct gpiod_line_event *events,
+				      unsigned int num_events) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @defgroup line_misc Misc line functions
+ * @{
+ *
+ * Functions that didn't fit anywhere else.
+ */
+
+/**
+ * @brief Get a GPIO line handle by GPIO chip description and offset.
+ * @param device String describing the gpiochip.
+ * @param offset The offset of the GPIO line.
+ * @return GPIO line handle or NULL if an error occurred.
+ *
+ * This routine provides a shorter alternative to calling
+ * ::gpiod_chip_open_lookup and ::gpiod_chip_get_line.
+ *
+ * If this function succeeds, the caller is responsible for closing the
+ * associated GPIO chip.
+ */
+struct gpiod_line *
+gpiod_line_get(const char *device, unsigned int offset) GPIOD_API;
+
+/**
+ * @brief Find a GPIO line by its name.
+ * @param name Name of the GPIO line.
+ * @return Returns the GPIO line handle if the line exists in the system or
+ *         NULL if it couldn't be located or an error occurred.
+ * @attention GPIO lines are not unique in the linux kernel, neither globally
+ *            nor within a single chip. This function finds the first line with
+ *            given name.
+ *
+ * If this routine succeeds, the user must manually close the GPIO chip owning
+ * this line to avoid memory leaks. If the line could not be found, this
+ * functions sets errno to ENOENT.
+ */
+struct gpiod_line *gpiod_line_find(const char *name) GPIOD_API;
+
+/**
+ * @brief Close a GPIO chip owning this line and release all resources.
+ * @param line GPIO line object
+ *
+ * After this function returns, the line must no longer be used.
+ */
+void gpiod_line_close_chip(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @brief Get the handle to the GPIO chip controlling this line.
+ * @param line The GPIO line object.
+ * @return Pointer to the GPIO chip handle controlling this line.
+ */
+struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line) GPIOD_API;
+
+/**
+ * @}
+ *
+ * @}
+ *
+ * @defgroup iterators Iterators for GPIO chips and lines
+ * @{
+ *
+ * These functions and data structures allow easy iterating over GPIO
+ * chips and lines.
+ */
+
+/**
+ * @brief Create a new gpiochip iterator.
+ * @return Pointer to a new chip iterator object or NULL if an error occurred.
+ *
+ * Internally this routine scans the /dev/ directory for GPIO chip device
+ * files, opens them and stores their the handles until ::gpiod_chip_iter_free
+ * or ::gpiod_chip_iter_free_noclose is called.
+ */
+struct gpiod_chip_iter *gpiod_chip_iter_new(void) GPIOD_API;
+
+/**
+ * @brief Release all resources allocated for the gpiochip iterator and close
+ *        the most recently opened gpiochip (if any).
+ * @param iter The gpiochip iterator object.
+ */
+void gpiod_chip_iter_free(struct gpiod_chip_iter *iter) GPIOD_API;
+
+/**
+ * @brief Release all resources allocated for the gpiochip iterator but
+ *        don't close the most recently opened gpiochip (if any).
+ * @param iter The gpiochip iterator object.
+ *
+ * Users may want to break the loop when iterating over gpiochips and keep
+ * the most recently opened chip active while freeing the iterator data.
+ * This routine enables that.
+ */
+void gpiod_chip_iter_free_noclose(struct gpiod_chip_iter *iter) GPIOD_API;
+
+/**
+ * @brief Get the next gpiochip handle.
+ * @param iter The gpiochip iterator object.
+ * @return Pointer to the next open gpiochip handle or NULL if no more chips
+ *         are present in the system.
+ * @note The previous chip handle will be closed using ::gpiod_chip_iter_free.
+ */
+struct gpiod_chip *
+gpiod_chip_iter_next(struct gpiod_chip_iter *iter) GPIOD_API;
+
+/**
+ * @brief Get the next gpiochip handle without closing the previous one.
+ * @param iter The gpiochip iterator object.
+ * @return Pointer to the next open gpiochip handle or NULL if no more chips
+ *         are present in the system.
+ * @note This function works just like ::gpiod_chip_iter_next but doesn't
+ *       close the most recently opened chip handle.
+ */
+struct gpiod_chip *
+gpiod_chip_iter_next_noclose(struct gpiod_chip_iter *iter) GPIOD_API;
+
+/**
+ * @brief Iterate over all GPIO chips present in the system.
+ * @param iter An initialized GPIO chip iterator.
+ * @param chip Pointer to a GPIO chip handle. On each iteration the newly
+ *             opened chip handle is assigned to this argument.
+ *
+ * The user must not close the GPIO chip manually - instead the previous chip
+ * handle is closed automatically on the next iteration. The last chip to be
+ * opened is closed internally by ::gpiod_chip_iter_free.
+ */
+#define gpiod_foreach_chip(iter, chip)					\
+	for ((chip) = gpiod_chip_iter_next(iter);			\
+	     (chip);							\
+	     (chip) = gpiod_chip_iter_next(iter))
+
+/**
+ * @brief Iterate over all chips present in the system without closing them.
+ * @param iter An initialized GPIO chip iterator.
+ * @param chip Pointer to a GPIO chip handle. On each iteration the newly
+ *             opened chip handle is assigned to this argument.
+ *
+ * The user must close all the GPIO chips manually after use, until then, the
+ * chips remain open. Free the iterator by calling
+ * ::gpiod_chip_iter_free_noclose to avoid closing the last chip automatically.
+ */
+#define gpiod_foreach_chip_noclose(iter, chip)				\
+	for ((chip) = gpiod_chip_iter_next_noclose(iter);		\
+	     (chip);							\
+	     (chip) = gpiod_chip_iter_next_noclose(iter))
+
+/**
+ * @brief Create a new line iterator.
+ * @param chip Active gpiochip handle over the lines of which we want
+ *             to iterate.
+ * @return New line iterator or NULL if an error occurred.
+ */
+struct gpiod_line_iter *
+gpiod_line_iter_new(struct gpiod_chip *chip) GPIOD_API;
+
+/**
+ * @brief Free all resources associated with a GPIO line iterator.
+ * @param iter Line iterator object.
+ */
+void gpiod_line_iter_free(struct gpiod_line_iter *iter) GPIOD_API;
+
+/**
+ * @brief Get the next GPIO line handle.
+ * @param iter The GPIO line iterator object.
+ * @return Pointer to the next GPIO line handle or NULL if there are no more
+ *         lines left.
+ */
+struct gpiod_line *
+gpiod_line_iter_next(struct gpiod_line_iter *iter) GPIOD_API;
+
+/**
+ * @brief Iterate over all GPIO lines of a single chip.
+ * @param iter An initialized GPIO line iterator.
+ * @param line Pointer to a GPIO line handle - on each iteration, the
+ *             next GPIO line will be assigned to this argument.
+ */
+#define gpiod_foreach_line(iter, line)					\
+	for ((line) = gpiod_line_iter_next(iter);			\
+	     (line);							\
+	     (line) = gpiod_line_iter_next(iter))
+
+/**
+ * @}
+ *
+ * @defgroup misc Stuff that didn't fit anywhere else
+ * @{
+ *
+ * Various libgpiod-related functions.
+ */
+
+/**
+ * @brief Get the API version of the library as a human-readable string.
+ * @return Human-readable string containing the library version.
+ */
+const char *gpiod_version_string(void) GPIOD_API;
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* __LIBGPIOD_GPIOD_H__ */

include/gpiod.hpp

@@ -0,0 +1,1066 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * This file is part of libgpiod.
+ *
+ * Copyright (C) 2017-2018 Bartosz Golaszewski <bartekgola@gmail.com>
+ */
+
+#ifndef __LIBGPIOD_GPIOD_CXX_HPP__
+#define __LIBGPIOD_GPIOD_CXX_HPP__
+
+#include <bitset>
+#include <chrono>
+#include <gpiod.h>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace gpiod {
+
+class line;
+class line_bulk;
+class line_iter;
+class chip_iter;
+struct line_event;
+
+/**
+ * @file gpiod.hpp
+ */
+
+/**
+ * @defgroup gpiod_cxx C++ bindings
+ * @{
+ */
+
+/**
+ * @brief Represents a GPIO chip.
+ *
+ * Internally this class holds a smart pointer to an open GPIO chip descriptor.
+ * Multiple objects of this class can reference the same chip. The chip is
+ * closed and all resources freed when the last reference is dropped.
+ */
+class chip
+{
+public:
+
+	/**
+	 * @brief Default constructor. Creates an empty GPIO chip object.
+	 */
+	GPIOD_API chip(void) = default;
+
+	/**
+	 * @brief Constructor. Opens the chip using chip::open.
+	 * @param device String describing the GPIO chip.
+	 * @param how Indicates how the chip should be opened.
+	 */
+	GPIOD_API chip(const ::std::string& device, int how = OPEN_LOOKUP);
+
+	/**
+	 * @brief Copy constructor. References the object held by other.
+	 * @param other Other chip object.
+	 */
+	GPIOD_API chip(const chip& other) = default;
+
+	/**
+	 * @brief Move constructor. References the object held by other.
+	 * @param other Other chip object.
+	 */
+	GPIOD_API chip(chip&& other) = default;
+
+	/**
+	 * @brief Assignment operator. References the object held by other.
+	 * @param other Other chip object.
+	 * @return Reference to this object.
+	 */
+	GPIOD_API chip& operator=(const chip& other) = default;
+
+	/**
+	 * @brief Move assignment operator. References the object held by other.
+	 * @param other Other chip object.
+	 * @return Reference to this object.
+	 */
+	GPIOD_API chip& operator=(chip&& other) = default;
+
+	/**
+	 * @brief Destructor. Unreferences the internal chip object.
+	 */
+	GPIOD_API ~chip(void) = default;
+
+	/**
+	 * @brief Open a GPIO chip.
+	 * @param device String describing the GPIO chip.
+	 * @param how Indicates how the chip should be opened.
+	 *
+	 * If the object already holds a reference to an open chip, it will be
+	 * closed and the reference reset.
+	 */
+	GPIOD_API void open(const ::std::string &device, int how = OPEN_LOOKUP);
+
+	/**
+	 * @brief Reset the internal smart pointer owned by this object.
+	 */
+	GPIOD_API void reset(void) noexcept;
+
+	/**
+	 * @brief Return the name of the chip held by this object.
+	 * @return Name of the GPIO chip.
+	 */
+	GPIOD_API ::std::string name(void) const;
+
+	/**
+	 * @brief Return the label of the chip held by this object.
+	 * @return Label of the GPIO chip.
+	 */
+	GPIOD_API ::std::string label(void) const;
+
+	/**
+	 * @brief Return the number of lines exposed by this chip.
+	 * @return Number of lines.
+	 */
+	GPIOD_API unsigned int num_lines(void) const;
+
+	/**
+	 * @brief Get the line exposed by this chip at given offset.
+	 * @param offset Offset of the line.
+	 * @return Line object.
+	 */
+	GPIOD_API line get_line(unsigned int offset) const;
+
+	/**
+	 * @brief Get the line exposed by this chip by name.
+	 * @param name Line name.
+	 * @return Line object.
+	 */
+	GPIOD_API line find_line(const ::std::string& name) const;
+
+	/**
+	 * @brief Get a set of lines exposed by this chip at given offsets.
+	 * @param offsets Vector of line offsets.
+	 * @return Set of lines held by a line_bulk object.
+	 */
+	GPIOD_API line_bulk get_lines(const ::std::vector<unsigned int>& offsets) const;
+
+	/**
+	 * @brief Get all lines exposed by this chip.
+	 * @return All lines exposed by this chip held by a line_bulk object.
+	 */
+	GPIOD_API line_bulk get_all_lines(void) const;
+
+	/**
+	 * @brief Get a set of lines exposed by this chip by their names.
+	 * @param names Vector of line names.
+	 * @return Set of lines held by a line_bulk object.
+	 */
+	GPIOD_API line_bulk find_lines(const ::std::vector<::std::string>& names) const;
+
+	/**
+	 * @brief Equality operator.
+	 * @param rhs Right-hand side of the equation.
+	 * @return True if rhs references the same chip. False otherwise.
+	 */
+	GPIOD_API bool operator==(const chip& rhs) const noexcept;
+
+	/**
+	 * @brief Inequality operator.
+	 * @param rhs Right-hand side of the equation.
+	 * @return False if rhs references the same chip. True otherwise.
+	 */
+	GPIOD_API bool operator!=(const chip& rhs) const noexcept;
+
+	/**
+	 * @brief Check if this object holds a reference to a GPIO chip.
+	 * @return True if this object references a GPIO chip, false otherwise.
+	 */
+	GPIOD_API explicit operator bool(void) const noexcept;
+
+	/**
+	 * @brief Check if this object doesn't hold a reference to a GPIO chip.
+	 * @return False if this object references a GPIO chip, true otherwise.
+	 */
+	GPIOD_API bool operator!(void) const noexcept;
+
+	/**
+	 * @brief Affect the way in which chip::chip and chip::open will try
+	 *        to open a GPIO chip character device.
+	 */
+	enum : int {
+		OPEN_LOOKUP = 1,
+		/**< Open based on the best guess what the supplied string is. */
+		OPEN_BY_PATH,
+		/**< Assume the string is a path to the GPIO chardev. */
+		OPEN_BY_NAME,
+		/**< Assume the string is the name of the chip */
+		OPEN_BY_LABEL,
+		/**< Assume the string is the label of the GPIO chip. */
+		OPEN_BY_NUMBER,
+		/**< Assume the string is the number of the GPIO chip. */
+	};
+
+private:
+
+	chip(::gpiod_chip* chip);
+
+	void throw_if_noref(void) const;
+
+	::std::shared_ptr<::gpiod_chip> _m_chip;
+
+	friend chip_iter;
+	friend line_iter;
+};
+
+/**
+ * @brief Stores the configuration for line requests.
+ */
+struct line_request
+{
+	/**
+	 * @brief Request types.
+	 */
+	enum : int {
+		DIRECTION_AS_IS = 1,
+		/**< Request for values, don't change the direction. */
+		DIRECTION_INPUT,
+		/**< Request for reading line values. */
+		DIRECTION_OUTPUT,
+		/**< Request for driving the GPIO lines. */
+		EVENT_FALLING_EDGE,
+		/**< Listen for falling edge events. */
+		EVENT_RISING_EDGE,
+		/**< Listen for rising edge events. */
+		EVENT_BOTH_EDGES,
+		/**< Listen for all types of events. */
+	};
+
+	GPIOD_API static const ::std::bitset<32> FLAG_ACTIVE_LOW;
+	/**< Set the active state to 'low' (high is the default). */
+	GPIOD_API static const ::std::bitset<32> FLAG_OPEN_SOURCE;
+	/**< The line is an open-source port. */
+	GPIOD_API static const ::std::bitset<32> FLAG_OPEN_DRAIN;
+	/**< The line is an open-drain port. */
+	GPIOD_API static const ::std::bitset<32> FLAG_BIAS_DISABLE;
+	/**< The line has neither pull-up nor pull-down resistor enabled. */
+	GPIOD_API static const ::std::bitset<32> FLAG_BIAS_PULL_DOWN;
+	/**< The line has a configurable pull-down resistor enabled. */
+	GPIOD_API static const ::std::bitset<32> FLAG_BIAS_PULL_UP;
+	/**< The line has a configurable pull-up resistor enabled. */
+
+	::std::string consumer;
+	/**< Consumer name to pass to the request. */
+	int request_type;
+	/**< Type of the request. */
+	::std::bitset<32> flags;
+	/**< Additional request flags. */
+};
+
+/**
+ * @brief Represents a single GPIO line.
+ *
+ * Internally this class holds a raw pointer to a GPIO line descriptor and a
+ * reference to the parent chip. All line resources are freed when the last
+ * reference to the parent chip is dropped.
+ */
+class line
+{
+public:
+
+	/**
+	 * @brief Default constructor. Creates an empty line object.
+	 */
+	GPIOD_API line(void);
+
+	/**
+	 * @brief Copy constructor.
+	 * @param other Other line object.
+	 */
+	GPIOD_API line(const line& other) = default;
+
+	/**
+	 * @brief Move constructor.
+	 * @param other Other line object.
+	 */
+	GPIOD_API line(line&& other) = default;
+
+	/**
+	 * @brief Assignment operator.
+	 * @param other Other line object.
+	 * @return Reference to this object.
+	 */
+	GPIOD_API line& operator=(const line& other) = default;
+
+	/**
+	 * @brief Move assignment operator.
+	 * @param other Other line object.
+	 * @return Reference to this object.
+	 */
+	GPIOD_API line& operator=(line&& other) = default;
+
+	/**
+	 * @brief Destructor.
+	 */
+	GPIOD_API ~line(void) = default;
+
+	/**
+	 * @brief Get the offset of this line.
+	 * @return Offet of this line.
+	 */
+	GPIOD_API unsigned int offset(void) const;
+
+	/**
+	 * @brief Get the name of this line (if any).
+	 * @return Name of this line or an empty string if it is unnamed.
+	 */
+	GPIOD_API ::std::string name(void) const;
+
+	/**
+	 * @brief Get the consumer of this line (if any).
+	 * @return Name of the consumer of this line or an empty string if it
+	 *         is unused.
+	 */
+	GPIOD_API ::std::string consumer(void) const;
+
+	/**
+	 * @brief Get current direction of this line.
+	 * @return Current direction setting.
+	 */
+	GPIOD_API int direction(void) const;
+
+	/**
+	 * @brief Get current active state of this line.
+	 * @return Current active state setting.
+	 */
+	GPIOD_API int active_state(void) const;
+
+	/**
+	 * @brief Get current bias of this line.
+	 * @return Current bias setting.
+	 */
+	GPIOD_API int bias(void) const;
+
+	/**
+	 * @brief Check if this line is used by the kernel or other user space
+	 *        process.
+	 * @return True if this line is in use, false otherwise.
+	 */
+	GPIOD_API bool is_used(void) const;
+
+	/**
+	 * @brief Check if this line represents an open-drain GPIO.
+	 * @return True if the line is an open-drain GPIO, false otherwise.
+	 */
+	GPIOD_API bool is_open_drain(void) const;
+
+	/**
+	 * @brief Check if this line represents an open-source GPIO.
+	 * @return True if the line is an open-source GPIO, false otherwise.
+	 */
+	GPIOD_API bool is_open_source(void) const;
+
+	/**
+	 * @brief Request this line.
+	 * @param config Request config (see gpiod::line_request).
+	 * @param default_val Default value - only matters for OUTPUT direction.
+	 */
+	GPIOD_API void request(const line_request& config, int default_val = 0) const;
+
+	/**
+	 * @brief Release the line if it was previously requested.
+	 */
+	GPIOD_API void release(void) const;
+
+	/**
+	 * @brief Check if this user has ownership of this line.
+	 * @return True if the user has ownership of this line, false otherwise.
+	 */
+	GPIOD_API bool is_requested(void) const;
+
+	/**
+	 * @brief Read the line value.
+	 * @return Current value (0 or 1).
+	 */
+	GPIOD_API int get_value(void) const;
+
+	/**
+	 * @brief Set the value of this line.
+	 * @param val New value (0 or 1).
+	 */
+	GPIOD_API void set_value(int val) const;
+
+	/**
+	 * @brief Set configuration of this line.
+	 * @param direction New direction.
+	 * @param flags Replacement flags.
+	 * @param value New value (0 or 1) - only matters for OUTPUT direction.
+	 */
+	GPIOD_API void set_config(int direction, ::std::bitset<32> flags,
+				  int value = 0) const;
+
+	/**
+	 * @brief Set configuration flags of this line.
+	 * @param flags Replacement flags.
+	 */
+	GPIOD_API void set_flags(::std::bitset<32> flags) const;
+
+	/**
+	 * @brief Change the direction this line to input.
+	 */
+	GPIOD_API void set_direction_input() const;
+
+	/**
+	 * @brief Change the direction this lines to output.
+	 * @param value New value (0 or 1).
+	 */
+	GPIOD_API void set_direction_output(int value = 0) const;
+
+	/**
+	 * @brief Wait for an event on this line.
+	 * @param timeout Time to wait before returning if no event occurred.
+	 * @return True if an event occurred and can be read, false if the wait
+	 *         timed out.
+	 */
+	GPIOD_API bool event_wait(const ::std::chrono::nanoseconds& timeout) const;
+
+	/**
+	 * @brief Read a line event.
+	 * @return Line event object.
+	 */
+	GPIOD_API line_event event_read(void) const;
+
+	/**
+	 * @brief Read multiple line events.
+	 * @return Vector of line event objects.
+	 */
+	GPIOD_API ::std::vector<line_event> event_read_multiple(void) const;
+
+	/**
+	 * @brief Get the event file descriptor associated with this line.
+	 * @return File descriptor number.
+	 */
+	GPIOD_API int event_get_fd(void) const;
+
+	/**
+	 * @brief Get the reference to the parent chip.
+	 * @return Reference to the parent chip object.
+	 */
+	GPIOD_API const chip& get_chip(void) const;
+
+	/**
+	 * @brief Re-read the line info from the kernel.
+	 */
+	GPIOD_API void update(void) const;
+
+	/**
+	 * @brief Reset the state of this object.
+	 *
+	 * This is useful when the user needs to e.g. keep the line_event object
+	 * but wants to drop the reference to the GPIO chip indirectly held by
+	 * the line being the source of the event.
+	 */
+	GPIOD_API void reset(void);
+
+	/**
+	 * @brief Check if two line objects reference the same GPIO line.
+	 * @param rhs Right-hand side of the equation.
+	 * @return True if both objects reference the same line, fale otherwise.
+	 */
+	GPIOD_API bool operator==(const line& rhs) const noexcept;
+
+	/**
+	 * @brief Check if two line objects reference different GPIO lines.
+	 * @param rhs Right-hand side of the equation.
+	 * @return False if both objects reference the same line, true otherwise.
+	 */
+	GPIOD_API bool operator!=(const line& rhs) const noexcept;
+
+	/**
+	 * @brief Check if this object holds a reference to any GPIO line.
+	 * @return True if this object references a GPIO line, false otherwise.
+	 */
+	GPIOD_API explicit operator bool(void) const noexcept;
+
+	/**
+	 * @brief Check if this object doesn't reference any GPIO line.
+	 * @return True if this object doesn't reference any GPIO line, true
+	 *         otherwise.
+	 */
+	GPIOD_API bool operator!(void) const noexcept;
+
+	/**
+	 * @brief Possible direction settings.
+	 */
+	enum : int {
+		DIRECTION_INPUT = 1,
+		/**< Line's direction setting is input. */
+		DIRECTION_OUTPUT,
+		/**< Line's direction setting is output. */
+	};
+
+	/**
+	 * @brief Possible active state settings.
+	 */
+	enum : int {
+		ACTIVE_LOW = 1,
+		/**< Line's active state is low. */
+		ACTIVE_HIGH,
+		/**< Line's active state is high. */
+	};
+
+	/**
+	 * @brief Possible bias settings.
+	 */
+	enum : int {
+		BIAS_AS_IS = 1,
+		/**< Line's bias state is unknown. */
+		BIAS_DISABLE,
+		/**< Line's internal bias is disabled. */
+		BIAS_PULL_UP,
+		/**< Line's internal pull-up bias is enabled. */
+		BIAS_PULL_DOWN,
+		/**< Line's internal pull-down bias is enabled. */
+	};
+
+private:
+
+	line(::gpiod_line* line, const chip& owner);
+
+	void throw_if_null(void) const;
+	line_event make_line_event(const ::gpiod_line_event& event) const noexcept;
+
+	::gpiod_line* _m_line;
+	chip _m_chip;
+
+	friend chip;
+	friend line_bulk;
+	friend line_iter;
+};
+
+/**
+ * @brief Find a GPIO line by name. Search all GPIO chips present on the system.
+ * @param name Name of the line.
+ * @return Returns a line object - empty if the line was not found.
+ */
+GPIOD_API line find_line(const ::std::string& name);
+
+/**
+ * @brief Describes a single GPIO line event.
+ */
+struct line_event
+{
+	/**
+	 * @brief Possible event types.
+	 */
+	enum : int {
+		RISING_EDGE = 1,
+		/**< Rising edge event. */
+		FALLING_EDGE,
+		/**< Falling edge event. */
+	};
+
+	::std::chrono::nanoseconds timestamp;
+	/**< Best estimate of time of event occurrence in nanoseconds. */
+	int event_type;
+	/**< Type of the event that occurred. */
+	line source;
+	/**< Line object referencing the GPIO line on which the event occurred. */
+};
+
+/**
+ * @brief Represents a set of GPIO lines.
+ *
+ * Internally an object of this class stores an array of line objects
+ * owned by a single chip.
+ */
+class line_bulk
+{
+public:
+
+	/**
+	 * @brief Default constructor. Creates an empty line_bulk object.
+	 */
+	GPIOD_API line_bulk(void) = default;
+
+	/**
+	 * @brief Construct a line_bulk from a vector of lines.
+	 * @param lines Vector of gpiod::line objects.
+	 * @note All lines must be owned by the same GPIO chip.
+	 */
+	GPIOD_API line_bulk(const ::std::vector<line>& lines);
+
+	/**
+	 * @brief Copy constructor.
+	 * @param other Other line_bulk object.
+	 */
+	GPIOD_API line_bulk(const line_bulk& other) = default;
+
+	/**
+	 * @brief Move constructor.
+	 * @param other Other line_bulk object.
+	 */
+	GPIOD_API line_bulk(line_bulk&& other) = default;
+
+	/**
+	 * @brief Assignment operator.
+	 * @param other Other line_bulk object.
+	 * @return Reference to this object.
+	 */
+	GPIOD_API line_bulk& operator=(const line_bulk& other) = default;
+
+	/**
+	 * @brief Move assignment operator.
+	 * @param other Other line_bulk object.
+	 * @return Reference to this object.
+	 */
+	GPIOD_API line_bulk& operator=(line_bulk&& other) = default;
+
+	/**
+	 * @brief Destructor.
+	 */
+	GPIOD_API ~line_bulk(void) = default;
+
+	/**
+	 * @brief Add a line to this line_bulk object.
+	 * @param new_line Line to add.
+	 * @note The new line must be owned by the same chip as all the other
+	 *       lines already held by this line_bulk object.
+	 */
+	GPIOD_API void append(const line& new_line);
+
+	/**
+	 * @brief Get the line at given offset.
+	 * @param offset Offset of the line to get.
+	 * @return Reference to the line object.
+	 */
+	GPIOD_API line& get(unsigned int offset);
+
+	/**
+	 * @brief Get the line at given offset without bounds checking.
+	 * @param offset Offset of the line to get.
+	 * @return Reference to the line object.
+	 * @note No bounds checking is performed.
+	 */
+	GPIOD_API line& operator[](unsigned int offset);
+
+	/**
+	 * @brief Get the number of lines currently held by this object.
+	 * @return Number of elements in this line_bulk.
+	 */
+	GPIOD_API unsigned int size(void) const noexcept;
+
+	/**
+	 * @brief Check if this line_bulk doesn't hold any lines.
+	 * @return True if this object is empty, false otherwise.
+	 */
+	GPIOD_API bool empty(void) const noexcept;
+
+	/**
+	 * @brief Remove all lines from this object.
+	 */
+	GPIOD_API void clear(void);
+
+	/**
+	 * @brief Request all lines held by this object.
+	 * @param config Request config (see gpiod::line_request).
+	 * @param default_vals Vector of default values. Only relevant for
+	 *                     output direction requests.
+	 */
+	GPIOD_API void request(const line_request& config,
+			       const ::std::vector<int> default_vals = ::std::vector<int>()) const;
+
+	/**
+	 * @brief Release all lines held by this object.
+	 */
+	GPIOD_API void release(void) const;
+
+	/**
+	 * @brief Read values from all lines held by this object.
+	 * @return Vector containing line values the order of which corresponds
+	 *         with the order of lines in the internal array.
+	 */
+	GPIOD_API ::std::vector<int> get_values(void) const;
+
+	/**
+	 * @brief Set values of all lines held by this object.
+	 * @param values Vector of values to set. Must be the same size as the
+	 *               number of lines held by this line_bulk.
+	 */
+	GPIOD_API void set_values(const ::std::vector<int>& values) const;
+
+	/**
+	 * @brief Set configuration of all lines held by this object.
+	 * @param direction New direction.
+	 * @param flags Replacement flags.
+	 * @param values Vector of values to set. Must be the same size as the
+	 *               number of lines held by this line_bulk.
+	 *               Only relevant for output direction requests.
+	 */
+	GPIOD_API void set_config(int direction, ::std::bitset<32> flags,
+				  const ::std::vector<int> values = ::std::vector<int>()) const;
+
+	/**
+	 * @brief Set configuration flags of all lines held by this object.
+	 * @param flags Replacement flags.
+	 */
+	GPIOD_API void set_flags(::std::bitset<32> flags) const;
+
+	/**
+	 * @brief Change the direction all lines held by this object to input.
+	 */
+	GPIOD_API void set_direction_input() const;
+
+	/**
+	 * @brief Change the direction all lines held by this object to output.
+	 * @param values Vector of values to set. Must be the same size as the
+	 *               number of lines held by this line_bulk.
+	 */
+	GPIOD_API void set_direction_output(const ::std::vector<int>& values) const;
+
+	/**
+	 * @brief Poll the set of lines for line events.
+	 * @param timeout Number of nanoseconds to wait before returning an
+	 *                empty line_bulk.
+	 * @return Returns a line_bulk object containing lines on which events
+	 *         occurred.
+	 */
+	GPIOD_API line_bulk event_wait(const ::std::chrono::nanoseconds& timeout) const;
+
+	/**
+	 * @brief Check if this object holds any lines.
+	 * @return True if this line_bulk holds at least one line, false otherwise.
+	 */
+	GPIOD_API explicit operator bool(void) const noexcept;
+
+	/**
+	 * @brief Check if this object doesn't hold any lines.
+	 * @return True if this line_bulk is empty, false otherwise.
+	 */
+	GPIOD_API bool operator!(void) const noexcept;
+
+	/**
+	 * @brief Max number of lines that this object can hold.
+	 */
+	GPIOD_API static const unsigned int MAX_LINES;
+
+	/**
+	 * @brief Iterator for iterating over lines held by line_bulk.
+	 */
+	class iterator
+	{
+	public:
+
+		/**
+		 * @brief Default constructor. Builds an empty iterator object.
+		 */
+		GPIOD_API iterator(void) = default;
+
+		/**
+		 * @brief Copy constructor.
+		 * @param other Other line_bulk iterator.
+		 */
+		GPIOD_API iterator(const iterator& other) = default;
+
+		/**
+		 * @brief Move constructor.
+		 * @param other Other line_bulk iterator.
+		 */
+		GPIOD_API iterator(iterator&& other) = default;
+
+		/**
+		 * @brief Assignment operator.
+		 * @param other Other line_bulk iterator.
+		 * @return Reference to this iterator.
+		 */
+		GPIOD_API iterator& operator=(const iterator& other) = default;
+
+		/**
+		 * @brief Move assignment operator.
+		 * @param other Other line_bulk iterator.
+		 * @return Reference to this iterator.
+		 */
+		GPIOD_API iterator& operator=(iterator&& other) = default;
+
+		/**
+		 * @brief Destructor.
+		 */
+		GPIOD_API ~iterator(void) = default;
+
+		/**
+		 * @brief Advance the iterator by one element.
+		 * @return Reference to this iterator.
+		 */
+		GPIOD_API iterator& operator++(void);
+
+		/**
+		 * @brief Dereference current element.
+		 * @return Current GPIO line by reference.
+		 */
+		GPIOD_API const line& operator*(void) const;
+
+		/**
+		 * @brief Member access operator.
+		 * @return Current GPIO line by pointer.
+		 */
+		GPIOD_API const line* operator->(void) const;
+
+		/**
+		 * @brief Check if this operator points to the same element.
+		 * @param rhs Right-hand side of the equation.
+		 * @return True if this iterator points to the same GPIO line,
+		 *         false otherwise.
+		 */
+		GPIOD_API bool operator==(const iterator& rhs) const noexcept;
+
+		/**
+		 * @brief Check if this operator doesn't point to the same element.
+		 * @param rhs Right-hand side of the equation.
+		 * @return True if this iterator doesn't point to the same GPIO
+		 *         line, false otherwise.
+		 */
+		GPIOD_API bool operator!=(const iterator& rhs) const noexcept;
+
+	private:
+
+		iterator(const ::std::vector<line>::iterator& it);
+
+		::std::vector<line>::iterator _m_iter;
+
+		friend line_bulk;
+	};
+
+	/**
+	 * @brief Returns an iterator to the first line.
+	 * @return A line_bulk iterator.
+	 */
+	GPIOD_API iterator begin(void) noexcept;
+
+	/**
+	 * @brief Returns an iterator to the element following the last line.
+	 * @return A line_bulk iterator.
+	 */
+	GPIOD_API iterator end(void) noexcept;
+
+private:
+
+	void throw_if_empty(void) const;
+	void to_line_bulk(::gpiod_line_bulk* bulk) const;
+
+	::std::vector<line> _m_bulk;
+};
+
+/**
+ * @brief Create a new chip_iter.
+ * @return New chip iterator object pointing to the first GPIO chip on the system.
+ * @note This function is needed as we already use the default constructor of
+ *       gpiod::chip_iter as the return value of gpiod::end.
+ */
+GPIOD_API chip_iter make_chip_iter(void);
+
+/**
+ * @brief Support for range-based loops for chip iterators.
+ * @param iter A chip iterator.
+ * @return Iterator unchanged.
+ */
+GPIOD_API chip_iter begin(chip_iter iter) noexcept;
+
+/**
+ * @brief Support for range-based loops for chip iterators.
+ * @param iter A chip iterator.
+ * @return New end iterator.
+ */
+GPIOD_API chip_iter end(const chip_iter& iter) noexcept;
+
+/**
+ * @brief Allows to iterate over all GPIO chips present on the system.
+ */
+class chip_iter
+{
+public:
+
+	/**
+	 * @brief Default constructor. Creates the end iterator.
+	 */
+	GPIOD_API chip_iter(void) = default;
+
+	/**
+	 * @brief Copy constructor.
+	 * @param other Other chip_iter.
+	 */
+	GPIOD_API chip_iter(const chip_iter& other) = default;
+
+	/**
+	 * @brief Move constructor.
+	 * @param other Other chip_iter.
+	 */
+	GPIOD_API chip_iter(chip_iter&& other) = default;
+
+	/**
+	 * @brief Assignment operator.
+	 * @param other Other chip_iter.
+	 * @return Reference to this iterator.
+	 */
+	GPIOD_API chip_iter& operator=(const chip_iter& other) = default;
+
+	/**
+	 * @brief Move assignment operator.
+	 * @param other Other chip_iter.
+	 * @return Reference to this iterator.
+	 */
+	GPIOD_API chip_iter& operator=(chip_iter&& other) = default;
+
+	/**
+	 * @brief Destructor.
+	 */
+	GPIOD_API ~chip_iter(void) = default;
+
+	/**
+	 * @brief Advance the iterator by one element.
+	 * @return Reference to this iterator.
+	 */
+	GPIOD_API chip_iter& operator++(void);
+
+	/**
+	 * @brief Dereference current element.
+	 * @return Current GPIO chip by reference.
+	 */
+	GPIOD_API const chip& operator*(void) const;
+
+	/**
+	 * @brief Member access operator.
+	 * @return Current GPIO chip by pointer.
+	 */
+	GPIOD_API const chip* operator->(void) const;
+
+	/**
+	 * @brief Check if this operator points to the same element.
+	 * @param rhs Right-hand side of the equation.
+	 * @return True if this iterator points to the same chip_iter,
+	 *         false otherwise.
+	 */
+	GPIOD_API bool operator==(const chip_iter& rhs) const noexcept;
+
+	/**
+	 * @brief Check if this operator doesn't point to the same element.
+	 * @param rhs Right-hand side of the equation.
+	 * @return True if this iterator doesn't point to the same chip_iter,
+	 *         false otherwise.
+	 */
+	GPIOD_API bool operator!=(const chip_iter& rhs) const noexcept;
+
+private:
+
+	chip_iter(::gpiod_chip_iter* iter);
+
+	::std::shared_ptr<::gpiod_chip_iter> _m_iter;
+	chip _m_current;
+
+	friend chip_iter make_chip_iter(void);
+};
+
+/**
+ * @brief Support for range-based loops for line iterators.
+ * @param iter A line iterator.
+ * @return Iterator unchanged.
+ */
+GPIOD_API line_iter begin(line_iter iter) noexcept;
+
+/**
+ * @brief Support for range-based loops for line iterators.
+ * @param iter A line iterator.
+ * @return New end iterator.
+ */
+GPIOD_API line_iter end(const line_iter& iter) noexcept;
+
+/**
+ * @brief Allows to iterate over all lines owned by a GPIO chip.
+ */
+class line_iter
+{
+public:
+
+	/**
+	 * @brief Default constructor. Creates the end iterator.
+	 */
+	GPIOD_API line_iter(void) = default;
+
+	/**
+	 * @brief Constructor. Creates the begin iterator.
+	 * @param owner Chip owning the GPIO lines over which we want to iterate.
+	 */
+	GPIOD_API line_iter(const chip& owner);
+
+	/**
+	 * @brief Copy constructor.
+	 * @param other Other line iterator.
+	 */
+	GPIOD_API line_iter(const line_iter& other) = default;
+
+	/**
+	 * @brief Move constructor.
+	 * @param other Other line iterator.
+	 */
+	GPIOD_API line_iter(line_iter&& other) = default;
+
+	/**
+	 * @brief Assignment operator.
+	 * @param other Other line iterator.
+	 * @return Reference to this line_iter.
+	 */
+	GPIOD_API line_iter& operator=(const line_iter& other) = default;
+
+	/**
+	 * @brief Move assignment operator.
+	 * @param other Other line iterator.
+	 * @return Reference to this line_iter.
+	 */
+	GPIOD_API line_iter& operator=(line_iter&& other) = default;
+
+	/**
+	 * @brief Destructor.
+	 */
+	GPIOD_API ~line_iter(void) = default;
+
+	/**
+	 * @brief Advance the iterator by one element.
+	 * @return Reference to this iterator.
+	 */
+	GPIOD_API line_iter& operator++(void);
+
+	/**
+	 * @brief Dereference current element.
+	 * @return Current GPIO line by reference.
+	 */
+	GPIOD_API const line& operator*(void) const;
+
+	/**
+	 * @brief Member access operator.
+	 * @return Current GPIO line by pointer.
+	 */
+	GPIOD_API const line* operator->(void) const;
+
+	/**
+	 * @brief Check if this operator points to the same element.
+	 * @param rhs Right-hand side of the equation.
+	 * @return True if this iterator points to the same line_iter,
+	 *         false otherwise.
+	 */
+	GPIOD_API bool operator==(const line_iter& rhs) const noexcept;
+
+	/**
+	 * @brief Check if this operator doesn't point to the same element.
+	 * @param rhs Right-hand side of the equation.
+	 * @return True if this iterator doesn't point to the same line_iter,
+	 *         false otherwise.
+	 */
+	GPIOD_API bool operator!=(const line_iter& rhs) const noexcept;
+
+private:
+
+	::std::shared_ptr<::gpiod_line_iter> _m_iter;
+	line _m_current;
+};
+
+/**
+ * @}
+ */
+
+} /* namespace gpiod */
+
+#endif /* __LIBGPIOD_GPIOD_CXX_HPP__ */

include/libwebsockets.h

@@ -0,0 +1,699 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** @file */
+
+#ifndef LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
+#define LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
+
+#ifdef __cplusplus
+#include <cstddef>
+#include <cstdarg>
+
+extern "C" {
+#else
+#include <stdarg.h>
+#endif
+
+#include <string.h>
+#include <stdlib.h>
+
+#include "lws_config.h"
+
+#if defined(LWS_SUPPRESS_DEPRECATED_API_WARNINGS)
+#define OPENSSL_USE_DEPRECATED
+#endif
+
+/* place for one-shot opaque forward references */
+
+typedef struct lws_context * lws_ctx_t;
+struct lws_sequencer;
+struct lws_dsh;
+
+/*
+ * CARE: everything using cmake defines needs to be below here
+ */
+
+#define LWS_US_PER_SEC ((lws_usec_t)1000000)
+#define LWS_MS_PER_SEC ((lws_usec_t)1000)
+#define LWS_US_PER_MS ((lws_usec_t)1000)
+#define LWS_NS_PER_US ((lws_usec_t)1000)
+
+#define LWS_KI (1024)
+#define LWS_MI (LWS_KI * 1024)
+#define LWS_GI (LWS_MI * 1024)
+#define LWS_TI ((uint64_t)LWS_GI * 1024)
+#define LWS_PI ((uint64_t)LWS_TI * 1024)
+
+#define LWS_US_TO_MS(x) ((x + (LWS_US_PER_MS / 2)) / LWS_US_PER_MS)
+
+#if defined(LWS_HAS_INTPTR_T)
+#include <stdint.h>
+#define lws_intptr_t intptr_t
+#else
+typedef unsigned long long lws_intptr_t;
+#endif
+
+#if defined(WIN32) || defined(_WIN32)
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+
+#include <winsock2.h>
+#include <ws2tcpip.h>
+#include <stddef.h>
+#include <basetsd.h>
+#include <io.h>
+#ifndef _WIN32_WCE
+#include <fcntl.h>
+#else
+#define _O_RDONLY	0x0000
+#define O_RDONLY	_O_RDONLY
+#endif
+
+typedef int uid_t;
+typedef int gid_t;
+typedef unsigned short sa_family_t;
+#if !defined(LWS_HAVE_SUSECONDS_T)
+typedef unsigned int useconds_t;
+typedef int suseconds_t;
+#endif
+
+#define LWS_INLINE __inline
+#define LWS_VISIBLE
+#define LWS_WARN_UNUSED_RESULT
+#define LWS_WARN_DEPRECATED
+#define LWS_FORMAT(string_index)
+
+#if !defined(LWS_EXTERN) && defined(LWS_BUILDING_SHARED)
+#ifdef LWS_DLL
+#ifdef LWS_INTERNAL
+#define LWS_EXTERN extern __declspec(dllexport)
+#else
+#define LWS_EXTERN extern __declspec(dllimport)
+#endif
+#endif
+#endif
+
+#if !defined(LWS_INTERNAL) && !defined(LWS_EXTERN)
+#define LWS_EXTERN
+#define LWS_VISIBLE
+#endif
+
+#if !defined(LWS_EXTERN)
+#define LWS_EXTERN
+#endif
+
+#if defined(__MINGW32__)
+#define LWS_INVALID_FILE -1
+#else
+#define LWS_INVALID_FILE INVALID_HANDLE_VALUE
+#endif
+#define LWS_SOCK_INVALID (INVALID_SOCKET)
+#define LWS_O_RDONLY _O_RDONLY
+#define LWS_O_WRONLY _O_WRONLY
+#define LWS_O_CREAT _O_CREAT
+#define LWS_O_TRUNC _O_TRUNC
+
+#ifndef __func__
+#define __func__ __FUNCTION__
+#endif
+
+#else /* NOT WIN32 */
+#include <unistd.h>
+#if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP)
+#include <sys/capability.h>
+#endif
+
+#if defined(__NetBSD__) || defined(__FreeBSD__) || defined(__QNX__) || defined(__OpenBSD__)
+#include <sys/socket.h>
+#include <netinet/in.h>
+#endif
+
+#define LWS_INLINE inline
+#define LWS_O_RDONLY O_RDONLY
+#define LWS_O_WRONLY O_WRONLY
+#define LWS_O_CREAT O_CREAT
+#define LWS_O_TRUNC O_TRUNC
+
+#if !defined(LWS_PLAT_OPTEE) && !defined(OPTEE_TA) && !defined(LWS_PLAT_FREERTOS)
+#include <poll.h>
+#include <netdb.h>
+#define LWS_INVALID_FILE -1
+#define LWS_SOCK_INVALID (-1)
+#else
+#define getdtablesize() (30)
+#if defined(LWS_PLAT_FREERTOS)
+#define LWS_INVALID_FILE NULL
+#define LWS_SOCK_INVALID (-1)
+#else
+#define LWS_INVALID_FILE NULL
+#define LWS_SOCK_INVALID (-1)
+#endif
+#endif
+
+#if defined(__FreeBSD__)
+#include <sys/signal.h>
+#endif
+#if defined(__GNUC__)
+
+/* warn_unused_result attribute only supported by GCC 3.4 or later */
+#if __GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
+#define LWS_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
+#else
+#define LWS_WARN_UNUSED_RESULT
+#endif
+
+#if defined(LWS_BUILDING_SHARED)
+/* this is only set when we're building lws itself shared */
+#define LWS_VISIBLE __attribute__((visibility("default")))
+#define LWS_EXTERN extern
+
+#else /* not shared */
+#if defined(WIN32) || defined(_WIN32) || defined(__MINGW32__)
+#define LWS_VISIBLE
+#define LWS_EXTERN extern
+#else
+/*
+ * If we explicitly say hidden here, symbols exist as T but
+ * cannot be imported at link-time.
+ */
+#define LWS_VISIBLE
+#define LWS_EXTERN
+#endif
+
+#endif /* not shared */
+
+#define LWS_WARN_DEPRECATED __attribute__ ((deprecated))
+#define LWS_FORMAT(string_index) __attribute__ ((format(printf, string_index, string_index+1)))
+#else /* not GNUC */
+
+#define LWS_VISIBLE
+#define LWS_WARN_UNUSED_RESULT
+#define LWS_WARN_DEPRECATED
+#define LWS_FORMAT(string_index)
+#if !defined(LWS_EXTERN)
+#define LWS_EXTERN extern
+#endif
+#endif
+
+
+#if defined(__ANDROID__)
+#include <netinet/in.h>
+#include <unistd.h>
+#endif
+#endif
+
+#ifdef _WIN32
+#define random rand
+#else
+#if !defined(LWS_PLAT_OPTEE)
+#include <sys/time.h>
+#include <unistd.h>
+#endif
+#endif
+
+#if defined(LWS_WITH_LIBUV_INTERNAL)
+#include <uv.h>
+
+#ifdef LWS_HAVE_UV_VERSION_H
+#include <uv-version.h>
+#endif
+
+#ifdef LWS_HAVE_NEW_UV_VERSION_H
+#include <uv/version.h>
+#endif
+#endif
+
+#if defined(LWS_WITH_TLS)
+
+#ifdef USE_WOLFSSL
+#ifdef USE_OLD_CYASSL
+#ifdef _WIN32
+/*
+ * Include user-controlled settings for windows from
+ * <wolfssl-root>/IDE/WIN/user_settings.h
+ */
+#include <IDE/WIN/user_settings.h>
+#include <cyassl/ctaocrypt/settings.h>
+#else
+#include <cyassl/options.h>
+#endif
+#include <cyassl/openssl/ssl.h>
+#include <cyassl/error-ssl.h>
+
+#else
+#ifdef _WIN32
+/*
+ * Include user-controlled settings for windows from
+ * <wolfssl-root>/IDE/WIN/user_settings.h
+ */
+#include <IDE/WIN/user_settings.h>
+#include <wolfssl/wolfcrypt/settings.h>
+#else
+#include <wolfssl/options.h>
+#endif
+#include <wolfssl/openssl/ssl.h>
+#include <wolfssl/error-ssl.h>
+#endif /* not USE_OLD_CYASSL */
+#else
+#if defined(LWS_WITH_MBEDTLS)
+#if defined(LWS_PLAT_FREERTOS)
+/* this filepath is passed to us but without quotes or <> */
+#if !defined(LWS_AMAZON_RTOS)
+/* AMAZON RTOS has its own setting via MTK_MBEDTLS_CONFIG_FILE */
+#undef MBEDTLS_CONFIG_FILE
+#define MBEDTLS_CONFIG_FILE <mbedtls/esp_config.h>
+#endif
+#endif
+#if defined(LWS_WITH_TLS)
+#include <mbedtls/ssl.h>
+#include <mbedtls/entropy.h>
+#include <mbedtls/ctr_drbg.h>
+#include <mbedtls/version.h>
+
+#if !defined(MBEDTLS_PRIVATE)
+#define MBEDTLS_PRIVATE(_q) _q
+#endif
+
+#if (MBEDTLS_VERSION_MAJOR == 3) && (MBEDTLS_VERSION_MINOR == 0)
+#define MBEDTLS_PRIVATE_V30_ONLY(_q) MBEDTLS_PRIVATE(_q)
+#else
+#define MBEDTLS_PRIVATE_V30_ONLY(_q) _q
+#endif
+
+#endif
+#else
+#include <openssl/ssl.h>
+#if !defined(LWS_WITH_MBEDTLS)
+#include <openssl/err.h>
+#endif
+#endif
+#endif /* not USE_WOLFSSL */
+#endif
+
+/*
+ * Helpers for pthread mutex in user code... if lws is built for
+ * multiple service threads, these resolve to pthread mutex
+ * operations.  In the case LWS_MAX_SMP is 1 (the default), they
+ * are all NOPs and no pthread type or api is referenced.
+ */
+
+#if LWS_MAX_SMP > 1
+
+#include <pthread.h>
+
+#define lws_pthread_mutex(name) pthread_mutex_t name;
+
+static LWS_INLINE void
+lws_pthread_mutex_init(pthread_mutex_t *lock)
+{
+	pthread_mutex_init(lock, NULL);
+}
+
+static LWS_INLINE void
+lws_pthread_mutex_destroy(pthread_mutex_t *lock)
+{
+	pthread_mutex_destroy(lock);
+}
+
+static LWS_INLINE void
+lws_pthread_mutex_lock(pthread_mutex_t *lock)
+{
+	pthread_mutex_lock(lock);
+}
+
+static LWS_INLINE void
+lws_pthread_mutex_unlock(pthread_mutex_t *lock)
+{
+	pthread_mutex_unlock(lock);
+}
+
+#else
+#define lws_pthread_mutex(name)
+#define lws_pthread_mutex_init(_a)
+#define lws_pthread_mutex_destroy(_a)
+#define lws_pthread_mutex_lock(_a)
+#define lws_pthread_mutex_unlock(_a)
+#endif
+
+
+#define CONTEXT_PORT_NO_LISTEN -1
+#define CONTEXT_PORT_NO_LISTEN_SERVER -2
+
+#include <libwebsockets/lws-logs.h>
+
+
+#include <stddef.h>
+
+#ifndef lws_container_of
+#define lws_container_of(P,T,M)	((T *)((char *)(P) - offsetof(T, M)))
+#endif
+#define LWS_ALIGN_TO(x, bou) x += ((bou) - ((x) % (bou))) % (bou)
+
+struct lws;
+
+/* api change list for user code to test against */
+
+#define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_ARG
+
+/* the struct lws_protocols has the id field present */
+#define LWS_FEATURE_PROTOCOLS_HAS_ID_FIELD
+
+/* you can call lws_get_peer_write_allowance */
+#define LWS_FEATURE_PROTOCOLS_HAS_PEER_WRITE_ALLOWANCE
+
+/* extra parameter introduced in 917f43ab821 */
+#define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_LEN
+
+/* File operations stuff exists */
+#define LWS_FEATURE_FOPS
+
+
+#if defined(_WIN32)
+#if !defined(LWS_WIN32_HANDLE_TYPES)
+typedef SOCKET lws_sockfd_type;
+#if defined(__MINGW32__)
+typedef int lws_filefd_type;
+#else
+typedef HANDLE lws_filefd_type;
+#endif
+#endif
+
+
+#define lws_pollfd pollfd
+#define LWS_POLLHUP	(POLLHUP)
+#define LWS_POLLIN	(POLLRDNORM | POLLRDBAND)
+#define LWS_POLLOUT	(POLLWRNORM)
+
+#else
+
+
+#if defined(LWS_PLAT_FREERTOS)
+#include <libwebsockets/lws-freertos.h>
+#else
+typedef int lws_sockfd_type;
+typedef int lws_filefd_type;
+#endif
+
+#if defined(LWS_PLAT_OPTEE)
+#include <time.h>
+struct timeval {
+	time_t         	tv_sec;
+	unsigned int    tv_usec;
+};
+#if defined(LWS_WITH_NETWORK)
+// #include <poll.h>
+#define lws_pollfd pollfd
+
+struct timezone;
+
+int gettimeofday(struct timeval *tv, struct timezone *tz);
+
+    /* Internet address. */
+    struct in_addr {
+        uint32_t       s_addr;     /* address in network byte order */
+    };
+
+typedef unsigned short sa_family_t;
+typedef unsigned short in_port_t;
+typedef uint32_t socklen_t;
+
+#include <libwebsockets/lws-optee.h>
+
+#if !defined(TEE_SE_READER_NAME_MAX)
+           struct addrinfo {
+               int              ai_flags;
+               int              ai_family;
+               int              ai_socktype;
+               int              ai_protocol;
+               socklen_t        ai_addrlen;
+               struct sockaddr *ai_addr;
+               char            *ai_canonname;
+               struct addrinfo *ai_next;
+           };
+#endif
+
+ssize_t recv(int sockfd, void *buf, size_t len, int flags);
+ssize_t send(int sockfd, const void *buf, size_t len, int flags);
+ssize_t read(int fd, void *buf, size_t count);
+int getsockopt(int sockfd, int level, int optname,
+                      void *optval, socklen_t *optlen);
+       int setsockopt(int sockfd, int level, int optname,
+                      const void *optval, socklen_t optlen);
+int connect(int sockfd, const struct sockaddr *addr,
+                   socklen_t addrlen);
+
+extern int errno;
+
+uint16_t ntohs(uint16_t netshort);
+uint16_t htons(uint16_t hostshort);
+
+int bind(int sockfd, const struct sockaddr *addr,
+                socklen_t addrlen);
+
+
+#define  MSG_NOSIGNAL 0x4000
+#define	EAGAIN		11
+#define EINTR		4
+#define EWOULDBLOCK	EAGAIN
+#define	EADDRINUSE	98	
+#define INADDR_ANY	0
+#define AF_INET		2
+#define SHUT_WR 1
+#define AF_UNSPEC	0
+#define PF_UNSPEC	0
+#define SOCK_STREAM	1
+#define SOCK_DGRAM	2
+# define AI_PASSIVE	0x0001
+#define IPPROTO_UDP	17
+#define SOL_SOCKET	1
+#define SO_SNDBUF	7
+#define	EISCONN		106	
+#define	EALREADY	114
+#define	EINPROGRESS	115
+int shutdown(int sockfd, int how);
+int close(int fd);
+int atoi(const char *nptr);
+long long atoll(const char *nptr);
+
+int socket(int domain, int type, int protocol);
+       int getaddrinfo(const char *node, const char *service,
+                       const struct addrinfo *hints,
+                       struct addrinfo **res);
+
+       void freeaddrinfo(struct addrinfo *res);
+
+#if !defined(TEE_SE_READER_NAME_MAX)
+struct lws_pollfd
+{
+        int fd;                     /* File descriptor to poll.  */
+        short int events;           /* Types of events poller cares about.  */
+        short int revents;          /* Types of events that actually occurred.  */
+};
+#endif
+
+int poll(struct pollfd *fds, int nfds, int timeout);
+
+#define LWS_POLLHUP (0x18)
+#define LWS_POLLIN (1)
+#define LWS_POLLOUT (4)
+#else
+struct lws_pollfd;
+struct sockaddr_in;
+#endif
+#else
+#define lws_pollfd pollfd
+#define LWS_POLLHUP (POLLHUP | POLLERR)
+#define LWS_POLLIN (POLLIN)
+#define LWS_POLLOUT (POLLOUT)
+#endif
+#endif
+
+
+#if (defined(WIN32) || defined(_WIN32)) && !defined(__MINGW32__)
+/* ... */
+#define ssize_t SSIZE_T
+#endif
+
+#if defined(WIN32) && defined(LWS_HAVE__STAT32I64)
+#include <sys/types.h>
+#include <sys/stat.h>
+#endif
+
+#if defined(LWS_HAVE_STDINT_H)
+#include <stdint.h>
+#else
+#if defined(WIN32) || defined(_WIN32)
+/* !!! >:-[  */
+typedef __int64 int64_t;
+typedef unsigned __int64 uint64_t;
+typedef __int32 int32_t;
+typedef unsigned __int32 uint32_t;
+typedef __int16 int16_t;
+typedef unsigned __int16 uint16_t;
+typedef unsigned __int8 uint8_t;
+#else
+typedef unsigned int uint32_t;
+typedef unsigned short uint16_t;
+typedef unsigned char uint8_t;
+#endif
+#endif
+
+typedef int64_t lws_usec_t;
+typedef unsigned long long lws_filepos_t;
+typedef long long lws_fileofs_t;
+typedef uint32_t lws_fop_flags_t;
+
+#define lws_concat_temp(_t, _l) (_t + sizeof(_t) - _l)
+#define lws_concat_used(_t, _l) (sizeof(_t) - _l)
+
+/** struct lws_pollargs - argument structure for all external poll related calls
+ * passed in via 'in' */
+struct lws_pollargs {
+	lws_sockfd_type fd;	/**< applicable socket descriptor */
+	int events;		/**< the new event mask */
+	int prev_events;	/**< the previous event mask */
+};
+
+struct lws_extension; /* needed even with ws exts disabled for create context */
+struct lws_token_limits;
+struct lws_protocols;
+struct lws_context;
+struct lws_tokens;
+struct lws_vhost;
+struct lws;
+
+#include <libwebsockets/lws-dll2.h>
+#include <libwebsockets/lws-map.h>
+
+#include <libwebsockets/lws-fault-injection.h>
+#include <libwebsockets/lws-timeout-timer.h>
+#include <libwebsockets/lws-cache-ttl.h>
+#if defined(LWS_WITH_SYS_SMD)
+#include <libwebsockets/lws-smd.h>
+#endif
+#include <libwebsockets/lws-state.h>
+#include <libwebsockets/lws-retry.h>
+#include <libwebsockets/lws-adopt.h>
+#include <libwebsockets/lws-network-helper.h>
+#include <libwebsockets/lws-metrics.h>
+#include <libwebsockets/lws-system.h>
+#include <libwebsockets/lws-ws-close.h>
+#include <libwebsockets/lws-callbacks.h>
+#include <libwebsockets/lws-ws-state.h>
+#include <libwebsockets/lws-ws-ext.h>
+#include <libwebsockets/lws-protocols-plugins.h>
+
+#include <libwebsockets/lws-context-vhost.h>
+
+#if defined(LWS_WITH_CONMON)
+#include <libwebsockets/lws-conmon.h>
+#endif
+
+#if defined(LWS_ROLE_MQTT)
+#include <libwebsockets/lws-mqtt.h>
+#endif
+#include <libwebsockets/lws-client.h>
+#include <libwebsockets/lws-http.h>
+#include <libwebsockets/lws-spa.h>
+#include <libwebsockets/lws-purify.h>
+#include <libwebsockets/lws-misc.h>
+#include <libwebsockets/lws-dsh.h>
+#include <libwebsockets/lws-service.h>
+#include <libwebsockets/lws-write.h>
+#include <libwebsockets/lws-writeable.h>
+#include <libwebsockets/lws-ring.h>
+#include <libwebsockets/lws-sha1-base64.h>
+#include <libwebsockets/lws-x509.h>
+#include <libwebsockets/lws-cgi.h>
+#if defined(LWS_WITH_FILE_OPS)
+#include <libwebsockets/lws-vfs.h>
+#endif
+#include <libwebsockets/lws-gencrypto.h>
+
+#include <libwebsockets/lws-lejp.h>
+#include <libwebsockets/lws-lecp.h>
+#include <libwebsockets/lws-cose.h>
+#include <libwebsockets/lws-struct.h>
+#include <libwebsockets/lws-threadpool.h>
+#include <libwebsockets/lws-tokenize.h>
+#include <libwebsockets/lws-lwsac.h>
+#include <libwebsockets/lws-fts.h>
+#include <libwebsockets/lws-diskcache.h>
+#include <libwebsockets/lws-sequencer.h>
+#include <libwebsockets/lws-secure-streams.h>
+#include <libwebsockets/lws-secure-streams-policy.h>
+#include <libwebsockets/lws-secure-streams-client.h>
+
+#if !defined(LWS_PLAT_FREERTOS)
+#include <libwebsockets/abstract/abstract.h>
+
+#include <libwebsockets/lws-test-sequencer.h>
+#endif
+#include <libwebsockets/lws-async-dns.h>
+
+#if defined(LWS_WITH_TLS)
+
+#include <libwebsockets/lws-tls-sessions.h>
+
+#if defined(LWS_WITH_MBEDTLS)
+#include <mbedtls/md5.h>
+#include <mbedtls/sha1.h>
+#include <mbedtls/sha256.h>
+#include <mbedtls/sha512.h>
+#endif
+
+#include <libwebsockets/lws-genhash.h>
+#include <libwebsockets/lws-genrsa.h>
+#include <libwebsockets/lws-genaes.h>
+#include <libwebsockets/lws-genec.h>
+
+#include <libwebsockets/lws-jwk.h>
+#include <libwebsockets/lws-jose.h>
+#include <libwebsockets/lws-jws.h>
+#include <libwebsockets/lws-jwe.h>
+
+#endif
+
+#include <libwebsockets/lws-eventlib-exports.h>
+#include <libwebsockets/lws-i2c.h>
+#include <libwebsockets/lws-spi.h>
+#include <libwebsockets/lws-gpio.h>
+#include <libwebsockets/lws-bb-i2c.h>
+#include <libwebsockets/lws-bb-spi.h>
+#include <libwebsockets/lws-button.h>
+#include <libwebsockets/lws-led.h>
+#include <libwebsockets/lws-pwm.h>
+#include <libwebsockets/lws-display.h>
+#include <libwebsockets/lws-ssd1306-i2c.h>
+#include <libwebsockets/lws-ili9341-spi.h>
+#include <libwebsockets/lws-settings.h>
+#include <libwebsockets/lws-netdev.h>
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/libwebsockets/abstract/abstract.h

@@ -0,0 +1,138 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*
+ * These are used to optionally pass an array of index = C string, binary array,
+ * or ulong tokens to the abstract transport or protocol.  For example if it's
+ * raw socket transport, then the DNS address to connect to and the port are
+ * passed using these when the client created and bound to the transport.
+ */
+
+typedef struct lws_token_map {
+	union {
+		const char	*value;
+		uint8_t		*bvalue;
+		unsigned long	lvalue;
+	} u;
+	short			name_index;  /* 0 here indicates end of array */
+	short			length_or_zero;
+} lws_token_map_t;
+
+/*
+ * The indvidual protocols and transports define their own name_index-es which
+ * are meaningful to them.  Define index 0 globally as the end of an array of
+ * them, and provide bases so user protocol and transport ones don't overlap.
+ */
+
+enum {
+	LTMI_END_OF_ARRAY,
+
+	LTMI_PROTOCOL_BASE	= 2048,
+
+	LTMI_TRANSPORT_BASE	= 4096
+};
+
+struct lws_abs_transport;
+struct lws_abs_protocol;
+typedef struct lws_abs lws_abs_t;
+
+LWS_VISIBLE LWS_EXTERN const lws_token_map_t *
+lws_abs_get_token(const lws_token_map_t *token_map, short name_index);
+
+/*
+ * the combination of a protocol, transport, and token maps for each
+ */
+
+typedef void lws_abs_transport_inst_t;
+typedef void lws_abs_protocol_inst_t;
+
+/**
+ * lws_abstract_alloc() - allocate and configure an lws_abs_t
+ *
+ * \param vhost: the struct lws_vhost to bind to
+ * \param user: opaque user pointer
+ * \param abstract_path: "protocol.transport" names
+ * \param ap_tokens: tokens for protocol options
+ * \param at_tokens: tokens for transport
+ * \param seq: optional sequencer we should bind to, or NULL
+ * \param opaque_user_data: data given in sequencer callback, if any
+ *
+ * Returns an allocated lws_abs_t pointer set up with the other arguments.
+ *
+ * Doesn't create a connection instance, just allocates the lws_abs_t and
+ * sets it up with the arguments.
+ *
+ * Returns NULL is there's any problem.
+ */
+LWS_VISIBLE LWS_EXTERN lws_abs_t *
+lws_abstract_alloc(struct lws_vhost *vhost, void *user,
+		   const char *abstract_path, const lws_token_map_t *ap_tokens,
+		   const lws_token_map_t *at_tokens, struct lws_sequencer *seq,
+		   void *opaque_user_data);
+
+/**
+ * lws_abstract_free() - free an allocated lws_abs_t
+ *
+ * \param pabs: pointer to the lws_abs_t * to free
+ *
+ * Frees and sets the pointer to NULL.
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_abstract_free(lws_abs_t **pabs);
+
+/**
+ * lws_abs_bind_and_create_instance - use an abstract protocol and transport
+ *
+ * \param abs: the lws_abs_t describing the combination desired
+ *
+ * This instantiates an abstract protocol and abstract transport bound together.
+ * A single heap allocation is made for the combination and the protocol and
+ * transport creation ops are called on it.  The ap_tokens and at_tokens
+ * are consulted by the creation ops to decide the details of the protocol and
+ * transport for the instance.
+ */
+LWS_VISIBLE LWS_EXTERN lws_abs_t *
+lws_abs_bind_and_create_instance(const lws_abs_t *ai);
+
+/**
+ * lws_abs_destroy_instance() - destroys an instance
+ *
+ * \param ai: pointer to the ai pointer to destroy
+ *
+ * This is for destroying an instance created by
+ * lws_abs_bind_and_create_instance() above.
+ *
+ * Calls the protocol and transport destroy operations on the instance, then
+ * frees the combined allocation in one step.  The pointer ai is set to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_abs_destroy_instance(lws_abs_t **ai);
+
+/*
+ * bring in all the protocols and transports definitions
+ */
+
+#include <libwebsockets/abstract/protocols.h>
+#include <libwebsockets/abstract/transports.h>

include/libwebsockets/abstract/protocols.h

@@ -0,0 +1,88 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*
+ * Information about how this protocol handles multiple use of connections.
+ *
+ * .flags of 0 indicates each connection must start with a fresh transport.
+ *
+ * Flags can be used to indicate the protocol itself supports different
+ * kinds of multiple use.  However the actual use or not of these may depend on
+ * negotiation with the remote peer.
+ *
+ * LWS_AP_FLAG_PIPELINE_TRANSACTIONS:	other instances can be queued on one
+ *					with an existing connection and get a
+ *					chance to "hot take over" the existing
+ *					transport in turn, like h1 keepalive
+ *					pipelining
+ *
+ * LWS_AP_FLAG_MUXABLE_STREAM:	an existing connection can absorb more child
+ *				connections and mux them as separate child
+ *				streams ongoing, like h2
+ */
+
+enum {
+	LWS_AP_FLAG_PIPELINE_TRANSACTIONS			= (1 << 0),
+	LWS_AP_FLAG_MUXABLE_STREAM				= (1 << 1),
+};
+
+typedef struct lws_abs_protocol {
+	const char	*name;
+	int		alloc;
+	int		flags;
+
+	int		(*create)(const struct lws_abs *ai);
+	void		(*destroy)(lws_abs_protocol_inst_t **d);
+	int		(*compare)(lws_abs_t *abs1, lws_abs_t *abs2);
+
+	/* events the transport invokes (handled by abstract protocol) */
+
+	int		(*accept)(lws_abs_protocol_inst_t *d);
+	int		(*rx)(lws_abs_protocol_inst_t *d, const uint8_t *b, size_t l);
+	int		(*writeable)(lws_abs_protocol_inst_t *d, size_t budget);
+	int		(*closed)(lws_abs_protocol_inst_t *d);
+	int		(*heartbeat)(lws_abs_protocol_inst_t *d);
+
+	/* as parent, we get a notification a new child / queue entry
+	 * bound to us... this is the parent lws_abs_t as arg */
+	int		(*child_bind)(lws_abs_t *abs);
+} lws_abs_protocol_t;
+
+/**
+ * lws_abs_protocol_get_by_name() - returns a pointer to the named protocol ops
+ *
+ * \param name: the name of the abstract protocol
+ *
+ * Returns a pointer to the named protocol ops struct if available, otherwise
+ * NULL.
+ */
+LWS_VISIBLE LWS_EXTERN const lws_abs_protocol_t *
+lws_abs_protocol_get_by_name(const char *name);
+
+/*
+ * bring in public api pieces from protocols
+ */
+
+#include <libwebsockets/abstract/protocols/smtp.h>
+

include/libwebsockets/abstract/protocols/smtp.h

@@ -0,0 +1,115 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup smtp SMTP related functions
+ * ##SMTP related functions
+ * \ingroup lwsapi
+ *
+ * These apis let you communicate with a local SMTP server to send email from
+ * lws.  It handles all the SMTP sequencing and protocol actions.
+ *
+ * Your system should have postfix, sendmail or another MTA listening on port
+ * 25 and able to send email using the "mail" commandline app.  Usually distro
+ * MTAs are configured for this by default.
+ *
+ * You can either use the abstract protocol layer directly, or instead use the
+ * provided smtp sequencer... this takes care of creating the protocol
+ * connections, and provides and email queue and retry management.
+ */
+//@{
+
+#if defined(LWS_WITH_SMTP)
+
+enum {
+	LTMI_PSMTP_V_HELO = LTMI_PROTOCOL_BASE,		/* u.value */
+
+	LTMI_PSMTP_V_LWS_SMTP_EMAIL_T,			/* u.value */
+};
+
+enum {
+	LWS_SMTP_DISPOSITION_SENT,
+	LWS_SMTP_DISPOSITION_FAILED,
+	LWS_SMTP_DISPOSITION_FAILED_DESTROY
+};
+
+typedef struct lws_smtp_sequencer_args {
+	const char		helo[32];
+	struct lws_vhost	*vhost;
+	time_t			retry_interval;
+	time_t			delivery_timeout;
+	size_t			email_queue_max;
+	size_t			max_content_size;
+} lws_smtp_sequencer_args_t;
+
+typedef struct lws_smtp_sequencer lws_smtp_sequencer_t;
+typedef struct lws_smtp_email lws_smtp_email_t;
+
+LWS_VISIBLE LWS_EXTERN lws_smtp_sequencer_t *
+lws_smtp_sequencer_create(const lws_smtp_sequencer_args_t *args);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_smtp_sequencer_destroy(lws_smtp_sequencer_t *s);
+
+typedef int (*lws_smtp_cb_t)(void *e, void *d, int disp, const void *b, size_t l);
+typedef struct lws_smtp_email lws_smtp_email_t;
+
+/**
+ * lws_smtpc_add_email() - Allocates and queues an email object
+ *
+ * \param s: smtp sequencer to queue on
+ * \param payload: the email payload string, with headers and terminating .
+ * \param payload_len: size in bytes of the payload string
+ * \param sender: the sender name and email
+ * \param recipient: the recipient name and email
+ * \param data: opaque user data returned in the done callback
+ * \param done: callback called when the email send succeeded or failed
+ *
+ * Allocates an email object and copies the payload, sender and recipient into
+ * it and initializes it.  Returns NULL if OOM, otherwise the allocated email
+ * object.
+ *
+ * Because it copies the arguments into an allocated buffer, the original
+ * arguments can be safely destroyed after calling this.
+ *
+ * The done() callback must free the email object.  It doesn't have to free any
+ * individual members.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_smtpc_add_email(lws_smtp_sequencer_t *s, const char *payload,
+		    size_t payload_len, const char *sender,
+		    const char *recipient, void *data, lws_smtp_cb_t done);
+
+/**
+ * lws_smtpc_free_email() - Add email to the list of ones being sent
+ *
+ * \param e: email to queue for sending on \p c
+ *
+ * Adds an email to the linked-list of emails to send
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_smtpc_free_email(lws_smtp_email_t *e);
+
+
+#endif
+//@}

include/libwebsockets/abstract/transports.h

@@ -0,0 +1,65 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*
+ * Abstract transport ops
+ */
+
+typedef struct lws_abs_transport {
+	const char *name;
+	int alloc;
+
+	int (*create)(lws_abs_t *abs);
+	void (*destroy)(lws_abs_transport_inst_t **d);
+
+	/* check if the transport settings for these connections are the same */
+	int (*compare)(lws_abs_t *abs1, lws_abs_t *abs2);
+
+	/* events the abstract protocol invokes (handled by transport) */
+
+	int (*tx)(lws_abs_transport_inst_t *d, uint8_t *buf, size_t len);
+	int (*client_conn)(const lws_abs_t *abs);
+	int (*close)(lws_abs_transport_inst_t *d);
+	int (*ask_for_writeable)(lws_abs_transport_inst_t *d);
+	int (*set_timeout)(lws_abs_transport_inst_t *d, int reason, int secs);
+	int (*state)(lws_abs_transport_inst_t *d);
+} lws_abs_transport_t;
+
+/**
+ * lws_abs_protocol_get_by_name() - returns a pointer to the named protocol ops
+ *
+ * \param name: the name of the abstract protocol
+ *
+ * Returns a pointer to the named protocol ops struct if available, otherwise
+ * NULL.
+ */
+LWS_VISIBLE LWS_EXTERN const lws_abs_transport_t *
+lws_abs_transport_get_by_name(const char *name);
+
+/*
+ * bring in public api pieces from transports
+ */
+
+#include <libwebsockets/abstract/transports/raw-skt.h>
+#include <libwebsockets/abstract/transports/unit-test.h>

include/libwebsockets/abstract/transports/raw-skt.h

@@ -0,0 +1,29 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+enum {
+	LTMI_PEER_V_DNS_ADDRESS = LTMI_TRANSPORT_BASE,	/* u.value */
+	LTMI_PEER_LV_PORT,				/* u.lvalue */
+	LTMI_PEER_LV_TLS_FLAGS,				/* u.lvalue */
+};

include/libwebsockets/abstract/transports/unit-test.h

@@ -0,0 +1,81 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is an abstract transport useful for unit testing abstract protocols.
+ *
+ * Instead of passing data anywhere, you give the transport a list of packets
+ * to deliver and packets you expect back from the abstract protocol it's
+ * bound to.
+ */
+
+enum {
+	LWS_AUT_EXPECT_TEST_END					= (1 << 0),
+	LWS_AUT_EXPECT_LOCAL_CLOSE				= (1 << 1),
+	LWS_AUT_EXPECT_DO_REMOTE_CLOSE				= (1 << 2),
+	LWS_AUT_EXPECT_TX /* expect this as tx from protocol */	= (1 << 3),
+	LWS_AUT_EXPECT_RX /* present this as rx to protocol */	= (1 << 4),
+	LWS_AUT_EXPECT_SHOULD_FAIL				= (1 << 5),
+	LWS_AUT_EXPECT_SHOULD_TIMEOUT				= (1 << 6),
+};
+
+typedef enum {
+	LPE_CONTINUE,
+	LPE_SUCCEEDED,
+	LPE_FAILED,
+	LPE_FAILED_UNEXPECTED_TIMEOUT,
+	LPE_FAILED_UNEXPECTED_PASS,
+	LPE_FAILED_UNEXPECTED_CLOSE,
+	LPE_SKIPPED,
+	LPE_CLOSING
+} lws_unit_test_packet_disposition;
+
+typedef int (*lws_unit_test_packet_test_cb)(const void *cb_user, int disposition);
+typedef int (*lws_unit_test_packet_cb)(lws_abs_t *instance);
+
+/* each step in the unit test */
+
+typedef struct lws_unit_test_packet {
+	void				*buffer;
+	lws_unit_test_packet_cb		pre;
+	size_t				len;
+
+	uint32_t			flags;
+} lws_unit_test_packet_t;
+
+/* each unit test */
+
+typedef struct lws_unit_test {
+	const char *		name; /* NULL indicates end of test array */
+	lws_unit_test_packet_t *		expect_array;
+	int			max_secs;
+} lws_unit_test_t;
+
+enum {
+	LTMI_PEER_V_EXPECT_TEST = LTMI_TRANSPORT_BASE,	/* u.value */
+	LTMI_PEER_V_EXPECT_RESULT_CB,			/* u.value */
+	LTMI_PEER_V_EXPECT_RESULT_CB_ARG,		/* u.value */
+};
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_unit_test_result_name(int in);
+

include/libwebsockets/lws-adopt.h

@@ -0,0 +1,271 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup sock-adopt Socket adoption helpers
+ * ##Socket adoption helpers
+ *
+ * When integrating with an external app with its own event loop, these can
+ * be used to accept connections from someone else's listening socket.
+ *
+ * When using lws own event loop, these are not needed.
+ */
+///@{
+
+/**
+ * lws_adopt_socket() - adopt foreign socket as if listen socket accepted it
+ * for the default vhost of context.
+ *
+ * \param context: lws context
+ * \param accept_fd: fd of already-accepted socket to adopt
+ *
+ * Either returns new wsi bound to accept_fd, or closes accept_fd and
+ * returns NULL, having cleaned up any new wsi pieces.
+ *
+ * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
+ * to ws or just serve http.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd);
+/**
+ * lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted
+ * it for vhost
+ *
+ * \param vh: lws vhost
+ * \param accept_fd: fd of already-accepted socket to adopt
+ *
+ * Either returns new wsi bound to accept_fd, or closes accept_fd and
+ * returns NULL, having cleaned up any new wsi pieces.
+ *
+ * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
+ * to ws or just serve http.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_socket_vhost(struct lws_vhost *vh, lws_sockfd_type accept_fd);
+
+typedef enum {
+	LWS_ADOPT_RAW_FILE_DESC		=  0,	/* convenience constant */
+	LWS_ADOPT_HTTP			=  1,	/* flag: absent implies RAW */
+	LWS_ADOPT_SOCKET		=  2,	/* flag: absent implies file */
+	LWS_ADOPT_ALLOW_SSL		=  4,	/* flag: use tls */
+	LWS_ADOPT_FLAG_UDP		= 16,	/* flag: socket is UDP */
+	LWS_ADOPT_FLAG_RAW_PROXY	= 32,	/* flag: raw proxy */
+
+	LWS_ADOPT_RAW_SOCKET_UDP = LWS_ADOPT_SOCKET | LWS_ADOPT_FLAG_UDP,
+} lws_adoption_type;
+
+typedef union {
+	lws_sockfd_type sockfd;
+	lws_filefd_type filefd;
+} lws_sock_file_fd_type;
+
+#if defined(LWS_ESP_PLATFORM)
+#include <lwip/sockets.h>
+#endif
+
+typedef union {
+#if defined(LWS_WITH_IPV6)
+	struct sockaddr_in6 sa6;
+#else
+#if defined(LWS_ESP_PLATFORM)
+	uint8_t _pad_sa6[28];
+#endif
+#endif
+	struct sockaddr_in sa4;
+} lws_sockaddr46;
+
+#define sa46_sockaddr(_sa46) ((struct sockaddr *)(_sa46))
+
+#if defined(LWS_WITH_IPV6)
+#define sa46_socklen(_sa46) (socklen_t)((_sa46)->sa4.sin_family == AF_INET ? \
+				sizeof(struct sockaddr_in) : \
+				sizeof(struct sockaddr_in6))
+#define sa46_sockport(_sa46, _sp)  { if ((_sa46)->sa4.sin_family == AF_INET) \
+					(_sa46)->sa4.sin_port = (_sp); else \
+					(_sa46)->sa6.sin6_port = (_sp); }
+#define sa46_address(_sa46) ((uint8_t *)((_sa46)->sa4.sin_family == AF_INET ? \
+		     &_sa46->sa4.sin_addr : &_sa46->sa6.sin6_addr ))
+#else
+#define sa46_socklen(_sa46) (socklen_t)sizeof(struct sockaddr_in)
+#define sa46_sockport(_sa46, _sp)  (_sa46)->sa4.sin_port = (_sp)
+#define sa46_address(_sa46) (uint8_t *)&_sa46->sa4.sin_addr
+#endif
+
+#define sa46_address_len(_sa46) ((_sa46)->sa4.sin_family == AF_INET ? 4 : 16)
+
+#if defined(LWS_WITH_UDP)
+struct lws_udp {
+	lws_sockaddr46		sa46;
+	lws_sockaddr46		sa46_pending;
+	uint8_t			connected:1;
+};
+#endif
+
+/**
+* lws_adopt_descriptor_vhost() - adopt foreign socket or file descriptor
+* if socket descriptor, should already have been accepted from listen socket
+*
+* \param vh: lws vhost
+* \param type: OR-ed combinations of lws_adoption_type flags
+* \param fd: union with either .sockfd or .filefd set
+* \param vh_prot_name: NULL or vh protocol name to bind raw connection to
+* \param parent: NULL or struct lws to attach new_wsi to as a child
+*
+* Either returns new wsi bound to accept_fd, or closes accept_fd and
+* returns NULL, having cleaned up any new wsi pieces.
+*
+* If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
+* ready to accept an upgrade to ws or just serve http.
+*
+* parent may be NULL, if given it should be an existing wsi that will become the
+* parent of the new wsi created by this call.
+*/
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_descriptor_vhost(struct lws_vhost *vh, lws_adoption_type type,
+			   lws_sock_file_fd_type fd, const char *vh_prot_name,
+			   struct lws *parent);
+
+typedef struct lws_adopt_desc {
+	struct lws_vhost *vh;		/**< vhost the wsi should belong to */
+	lws_adoption_type type;		/**< OR-ed combinations of lws_adoption_type flags */
+	lws_sock_file_fd_type fd;	/**< union with either .sockfd or .filefd set */
+	const char *vh_prot_name;	/**< NULL or vh protocol name to bind raw connection to */
+	struct lws *parent;		/**< NULL or struct lws to attach new_wsi to as a child */
+	void *opaque;			/**< opaque pointer to set on created wsi */
+	const char *fi_wsi_name;	/**< NULL, or Fault Injection inheritence filter for wsi=string/ context faults */
+} lws_adopt_desc_t;
+
+/**
+* lws_adopt_descriptor_vhost_via_info() - adopt foreign socket or file descriptor
+* if socket descriptor, should already have been accepted from listen socket
+*
+* \param info: the struct containing the parameters
+*
+*  - vh: lws vhost
+*  - type: OR-ed combinations of lws_adoption_type flags
+*  - fd: union with either .sockfd or .filefd set
+*  - vh_prot_name: NULL or vh protocol name to bind raw connection to
+*  - parent: NULL or struct lws to attach new_wsi to as a child
+*  - opaque: opaque pointer to set on created wsi
+*
+* Either returns new wsi bound to accept_fd, or closes accept_fd and
+* returns NULL, having cleaned up any new wsi pieces.
+*
+* If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
+* ready to accept an upgrade to ws or just serve http.
+*
+* parent may be NULL, if given it should be an existing wsi that will become the
+* parent of the new wsi created by this call.
+*/
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_descriptor_vhost_via_info(const lws_adopt_desc_t *info);
+
+/**
+ * lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it
+ * for the default vhost of context.
+ * \param context:	lws context
+ * \param accept_fd:	fd of already-accepted socket to adopt
+ * \param readbuf:	NULL or pointer to data that must be drained before reading from
+ *		accept_fd
+ * \param len:	The length of the data held at \p readbuf
+ *
+ * Either returns new wsi bound to accept_fd, or closes accept_fd and
+ * returns NULL, having cleaned up any new wsi pieces.
+ *
+ * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
+ * to ws or just serve http.
+ *
+ * If your external code did not already read from the socket, you can use
+ * lws_adopt_socket() instead.
+ *
+ * This api is guaranteed to use the data at \p readbuf first, before reading from
+ * the socket.
+ *
+ * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
+                         const char *readbuf, size_t len);
+/**
+ * lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket
+ * accepted it for vhost.
+ * \param vhost:	lws vhost
+ * \param accept_fd:	fd of already-accepted socket to adopt
+ * \param readbuf:	NULL or pointer to data that must be drained before reading from accept_fd
+ * \param len:		The length of the data held at \p readbuf
+ *
+ * Either returns new wsi bound to accept_fd, or closes accept_fd and
+ * returns NULL, having cleaned up any new wsi pieces.
+ *
+ * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
+ * to ws or just serve http.
+ *
+ * If your external code did not already read from the socket, you can use
+ * lws_adopt_socket() instead.
+ *
+ * This api is guaranteed to use the data at \p readbuf first, before reading from
+ * the socket.
+ *
+ * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_socket_vhost_readbuf(struct lws_vhost *vhost,
+			       lws_sockfd_type accept_fd, const char *readbuf,
+			       size_t len);
+
+#define LWS_CAUDP_BIND (1 << 0)
+#define LWS_CAUDP_BROADCAST (1 << 1)
+#define LWS_CAUDP_PF_PACKET (1 << 2)
+
+#if defined(LWS_WITH_UDP)
+/**
+ * lws_create_adopt_udp() - create, bind and adopt a UDP socket
+ *
+ * \param vhost:	 lws vhost
+ * \param ads:		 NULL or address to do dns lookup on
+ * \param port:		 UDP port to bind to, -1 means unbound
+ * \param flags:	 0 or LWS_CAUDP_NO_BIND
+ * \param protocol_name: Name of protocol on vhost to bind wsi to
+ * \param ifname:	 NULL, for network interface name to bind socket to
+ * \param parent_wsi:	 NULL or parent wsi new wsi will be a child of
+ * \param opaque:	 set created wsi opaque ptr to this
+ * \param retry_policy:	 NULL for vhost default policy else wsi specific policy
+ * \param fi_wsi_name:	 NULL, or string to inherit Fault Injection rules in
+ *			 form "wsi=string/rule".  "wsi/rule" faults will be
+ *			 automatically applied as well.  It's done at creation
+ *			 time so the rules can, eg, inject faults related to
+ *			 creation.
+ *
+ * Either returns new wsi bound to accept_fd, or closes accept_fd and
+ * returns NULL, having cleaned up any new wsi pieces.
+ * */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_create_adopt_udp(struct lws_vhost *vhost, const char *ads, int port,
+		     int flags, const char *protocol_name, const char *ifname,
+		     struct lws *parent_wsi, void *opaque,
+		     const lws_retry_bo_t *retry_policy, const char *fi_wsi_name);
+#endif
+
+
+
+///@}

include/libwebsockets/lws-async-dns.h

@@ -0,0 +1,86 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#if defined(LWS_WITH_UDP)
+
+typedef enum dns_query_type {
+	LWS_ADNS_RECORD_A					= 0x01,
+	LWS_ADNS_RECORD_CNAME					= 0x05,
+	LWS_ADNS_RECORD_MX					= 0x0f,
+	LWS_ADNS_RECORD_AAAA					= 0x1c,
+} adns_query_type_t;
+
+typedef enum {
+	LADNS_RET_FAILED_WSI_CLOSED				= -4,
+	LADNS_RET_NXDOMAIN					= -3,
+	LADNS_RET_TIMEDOUT					= -2,
+	LADNS_RET_FAILED					= -1,
+	LADNS_RET_FOUND,
+	LADNS_RET_CONTINUING
+} lws_async_dns_retcode_t;
+
+struct addrinfo;
+
+typedef struct lws * (*lws_async_dns_cb_t)(struct lws *wsi, const char *ads,
+		const struct addrinfo *result, int n, void *opaque);
+
+/**
+ * lws_async_dns_query() - perform a dns lookup using async dns
+ *
+ * \param context: the lws_context
+ * \param tsi: thread service index (usually 0)
+ * \param name: DNS name to look up
+ * \param qtype: type of query (A, AAAA etc)
+ * \param cb: query completion callback
+ * \param wsi: wsi if the query is related to one
+ *
+ * Starts an asynchronous DNS lookup, on completion the \p cb callback will
+ * be called.
+ *
+ * The reference count on the cached object is incremented for every callback
+ * that was called with the cached addrinfo results.
+ *
+ * The cached object can't be evicted until the reference count reaches zero...
+ * use lws_async_dns_freeaddrinfo() to indicate you're finsihed with the
+ * results for each callback that happened with them.
+ */
+LWS_VISIBLE LWS_EXTERN lws_async_dns_retcode_t
+lws_async_dns_query(struct lws_context *context, int tsi, const char *name,
+		    adns_query_type_t qtype, lws_async_dns_cb_t cb,
+		    struct lws *wsi, void *opaque);
+
+/**
+ * lws_async_dns_freeaddrinfo() - decrement refcount on cached addrinfo results
+ *
+ * \param pai: a pointert to a pointer to first addrinfo returned as result in the callback
+ *
+ * Decrements the cache object's reference count.  When it reaches zero, the
+ * cached object may be reaped subject to LRU rules.
+ *
+ * The pointer to the first addrinfo give in the argument is set to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_async_dns_freeaddrinfo(const struct addrinfo **ai);
+
+#endif

include/libwebsockets/lws-bb-i2c.h

@@ -0,0 +1,66 @@
+/*
+ * I2C - bitbanged generic gpio implementation
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is like an abstract class for gpio, a real implementation provides
+ * functions for the ops that use the underlying OS gpio arrangements.
+ */
+
+typedef struct lws_bb_i2c {
+	lws_i2c_ops_t		bb_ops; /* init to lws_bb_i2c_ops */
+
+	/* implementation-specific members */
+
+	_lws_plat_gpio_t	scl;
+	_lws_plat_gpio_t	sda;
+
+	const lws_gpio_ops_t	*gpio;
+	void (*delay)(void);
+} lws_bb_i2c_t;
+
+#define lws_bb_i2c_ops \
+	{ \
+		.init = lws_bb_i2c_init, \
+		.start = lws_bb_i2c_start, \
+		.stop = lws_bb_i2c_stop, \
+		.write = lws_bb_i2c_write, \
+		.read = lws_bb_i2c_read, \
+		.set_ack = lws_bb_i2c_set_ack, \
+	}
+
+int
+lws_bb_i2c_init(const lws_i2c_ops_t *octx);
+
+int
+lws_bb_i2c_start(const lws_i2c_ops_t *octx);
+
+void
+lws_bb_i2c_stop(const lws_i2c_ops_t *octx);
+
+int
+lws_bb_i2c_write(const lws_i2c_ops_t *octx, uint8_t data);
+
+int
+lws_bb_i2c_read(const lws_i2c_ops_t *octx);
+
+void
+lws_bb_i2c_set_ack(const lws_i2c_ops_t *octx, int ack);

include/libwebsockets/lws-bb-spi.h

@@ -0,0 +1,62 @@
+/*
+ * I2C - bitbanged generic gpio implementation
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is like an abstract class for gpio, a real implementation provides
+ * functions for the ops that use the underlying OS gpio arrangements.
+ */
+
+#define LWSBBSPI_FLAG_USE_NCMD3		(1 << 7)
+#define LWSBBSPI_FLAG_USE_NCMD2		(1 << 6)
+#define LWSBBSPI_FLAG_USE_NCMD1		(1 << 5)
+#define LWSBBSPI_FLAG_USE_NCMD0		(1 << 4)
+#define LWSBBSPI_FLAG_USE_NCS3		(1 << 3)
+#define LWSBBSPI_FLAG_USE_NCS2		(1 << 2)
+#define LWSBBSPI_FLAG_USE_NCS1		(1 << 1)
+#define LWSBBSPI_FLAG_USE_NCS0		(1 << 0)
+
+#define LWS_SPI_BB_MAX_CH		4
+
+typedef struct lws_bb_spi {
+	lws_spi_ops_t		bb_ops; /* init to lws_bb_spi_ops */
+
+	/* implementation-specific members */
+	const lws_gpio_ops_t	*gpio;
+
+	_lws_plat_gpio_t	clk;
+	_lws_plat_gpio_t	ncs[LWS_SPI_BB_MAX_CH];
+	_lws_plat_gpio_t	ncmd[LWS_SPI_BB_MAX_CH];
+	_lws_plat_gpio_t	mosi;
+	_lws_plat_gpio_t	miso;
+
+	uint8_t			flags;
+} lws_bb_spi_t;
+
+#define lws_bb_spi_ops \
+		.init		= lws_bb_spi_init, \
+		.queue		= lws_bb_spi_queue
+
+int
+lws_bb_spi_init(const lws_spi_ops_t *octx);
+
+int
+lws_bb_spi_queue(const lws_spi_ops_t *octx, const lws_spi_desc_t *desc);

include/libwebsockets/lws-button.h

@@ -0,0 +1,120 @@
+/*
+ * Generic button ops
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * Leverages the lws generic gpio pieces to bind gpio buttons to smd events
+ */
+
+#if !defined(__LWS_BUTTON_H__)
+#define __LWS_BUTTON_H__
+
+typedef uint16_t lws_button_idx_t;
+
+/* actual minimum may be 1 x RTOS tick depending on platform */
+#define LWS_BUTTON_MON_TIMER_MS 5
+
+typedef void (*lws_button_cb_t)(void *opaque, lws_button_idx_t idx, int state);
+
+/* These are specified in ms but the granularity is LWS_BUTTON_MON_TIMER_MS,
+ * which may have been rounded up to an RTOS tick depending on platform */
+
+enum {
+	LWSBTNRGMFLAG_CLASSIFY_DOUBLECLICK = (1 << 0)
+};
+
+typedef struct lws_button_regime {
+	uint16_t			ms_min_down;
+	uint16_t			ms_min_down_longpress;
+	uint16_t			ms_up_settle;
+	uint16_t			ms_doubleclick_grace;
+	uint16_t			ms_repeat_down;
+	uint8_t				flags;
+	/**< when double-click classification is enabled, clicks are delayed
+	 * by ms_min_down + ms_doubleclick_grace to wait and see if it will
+	 * become a double-click.  Set LWSBTNRGMFLAG_CLASSIFY_DOUBLECLICK to
+	 * enable it or leave that bit at 0 to get faster single-click
+	 * classification.
+	 */
+} lws_button_regime_t;
+
+/*
+ * This is the const part of the button controller, describing the static
+ * bindings to gpio, and lws_smd event name information
+ */
+
+typedef struct lws_button_map {
+	_lws_plat_gpio_t		gpio;
+	const char			*smd_interaction_name;
+	const lws_button_regime_t	*regime;
+	/**< a default regime is applied if this is left NULL */
+} lws_button_map_t;
+
+typedef struct lws_button_controller {
+	const char			*smd_bc_name;
+	const lws_gpio_ops_t		*gpio_ops;
+	const lws_button_map_t		*button_map;
+	lws_button_idx_t		active_state_bitmap;
+	uint8_t				count_buttons;
+} lws_button_controller_t;
+
+struct lws_button_state; /* opaque */
+
+/**
+ * lws_button_controller_create() - instantiate a button controller
+ *
+ * \param ctx: the lws_context
+ * \param controller: the static controller definition
+ *
+ * Instantiates a button controller from a static definition of the buttons
+ * and their smd names, and active levels, and binds it to a gpio implementation
+ */
+
+LWS_VISIBLE LWS_EXTERN struct lws_button_state *
+lws_button_controller_create(struct lws_context *ctx,
+			     const lws_button_controller_t *controller);
+
+/**
+ * lws_button_controller_destroy() - destroys a button controller
+ *
+ * \param bcs: button controller state previously created
+ *
+ * Disables all buttons and then destroys and frees a previously created
+ * button controller.
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_button_controller_destroy(struct lws_button_state *bcs);
+
+
+LWS_VISIBLE LWS_EXTERN lws_button_idx_t
+lws_button_get_bit(struct lws_button_state *bcs, const char *name);
+
+/*
+ * lws_button_enable() - enable and disable buttons
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_button_enable(struct lws_button_state *bcs,
+		  lws_button_idx_t _reset, lws_button_idx_t _set);
+
+#endif
+

include/libwebsockets/lws-cache-ttl.h

@@ -0,0 +1,348 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup lws_cache_ttl Cache supporting expiry
+ * ##Cache supporting expiry
+ *
+ * These apis let you quickly and reliably implement caches of named objects,
+ * that have a "destroy-by date" and cache limits that will be observed.
+ *
+ * You can instantiate as many caches as you need.  The first one must be an
+ * L1 / heap cache type, it can have parents and grandparents of other types
+ * which are accessible why writing / looking up and getting from the L1 cache.
+ * The outer "cache" layer may persistently store items to a backing store.
+ *
+ * Allocated object memory is entirely for the use of user code, up to the
+ * requested size.
+ *
+ * The key name for the listed objects may be any string chosen by the user,
+ * there is no special length limit as it is also allocated.
+ *
+ * Both expiry and LRU orderings are kept so it is easy to find out usage
+ * ordering and when the next object that will expire.
+ *
+ * Cached objects may be destroyed any time you go around the event loop, when
+ * you allocate new objects (to keep the whole cache under the specified limit),
+ * or when their expiry time arrives.  So you shouldn't keep copies of pointers
+ * to cached objects after returning to the event loop.
+ */
+///@{
+
+
+struct lws_cache_ttl_lru;
+
+/**
+ * lws_cache_write_through() - add a new cache item object in all layers
+ *
+ * \param cache: the existing cache to allocate the object in
+ * \param specific_key: a key string that identifies the item in the cache
+ * \param source: optional payload for the cached item, NULL means caller will
+ *		  write the payload
+ * \param size: the size of the object to allocate
+ * \param expiry: the usec time that the object will autodestroy
+ * \param ppay: NULL, or a pointer to a void * to be set to the L1 payload
+ *
+ * If an item with the key already exists, it is destroyed before allocating a
+ * new one.
+ *
+ * Returns 0 if successful.  The written entry will be scheduled to be auto-
+ * destroyed when \p expiry occurs.
+ *
+ * Adding or removing cache items may cause invalidation of cached queries.
+ */
+LWS_VISIBLE LWS_EXTERN int /* only valid until return to event loop */
+lws_cache_write_through(struct lws_cache_ttl_lru *cache,
+			const char *specific_key, const uint8_t *source,
+			size_t size, lws_usec_t expiry, void **ppay);
+
+typedef struct lws_cache_match {
+	lws_dll2_t			list;
+	lws_usec_t			expiry;
+	/* earliest expiry amongst results */
+	size_t				payload_size;
+	/**< the payload is not attached here.  This is a hint about what
+	 * (*get)() will return for this tag name.
+	 */
+	size_t				tag_size;
+
+	/* tag name + NUL is overcommitted */
+} lws_cache_match_t;
+
+/**
+ * lws_cache_heap_lookup() - get a list of matching items
+ *
+ * \param cache: the cache to search for the key
+ * \param wildcard_key: the item key string, may contain wildcards
+ * \param pdata: pointer to pointer to be set to the serialized result list
+ * \param psize: pointer to size_t to receive length of serialized result list
+ *
+ * This finds all unique items in the final cache that match search_key, which
+ * may contain wildcards.  It does not return the payloads for matching items,
+ * just a list of specific tags in the that match.
+ *
+ * If successful, results are provided in a serialized list format, in no
+ * particular order, each result has the following fields
+ *
+ * - BE32: payload size in bytes (payload itself is not included)
+ * - BE32: specific tag name length in bytes
+ * - chars: tag name with terminating NUL
+ *
+ * These serialized results are themselves cached in L1 cache (only) and the
+ * result pointers are set pointing into that.  If the results are still in L1
+ * cache next time this api is called, the results will be returned directly
+ * from that without repeating the expensive lookup on the backup store.  That
+ * is why the results are provided in serialized form.
+ *
+ * The cached results list expiry is set to the earliest expiry of any listed
+ * item.  Additionally any cached results are invalidated on addition or
+ * deletion (update is done as addition + deletion) of any item that would
+ * match the results' original wildcard_key.  For the typical case new items
+ * are rare compared to lookups, this is efficient.
+ *
+ * Lookup matching does not itself affect LRU or cache status of the result
+ * itsems.  Typically user code will get the lookup results, and then perform
+ * get operations on each item in its desired order, that will bring the items
+ * to the head of the LRU list and occupy L1 cache.
+ *
+ * Returns 0 if proceeded alright, or nonzero if error.  If there was an error,
+ * any partial results set has been deallocated cleanly before returning.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cache_lookup(struct lws_cache_ttl_lru *cache, const char *wildcard_key,
+		 const void **pdata, size_t *psize);
+
+/**
+ * lws_cache_item_get() - bring a specific item into L1 and get payload info
+ *
+ * \param cache: the cache to search for the key
+ * \param specific_key: the key string of the item to get
+ * \param pdata: pointer to a void * to be set to the payload in L1 cache
+ * \param psize: pointer to a size_t to be set to the payload size
+ *
+ * If the cache still has an item matching the key string, it will be destroyed.
+ *
+ * Adding or removing cache items may cause invalidation of cached queries.
+ *
+ * Notice the cache payload is a blob of the given size.  If you are storing
+ * strings, there is no NUL termination unless you stored them with it.
+ *
+ * Returns 0 if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cache_item_get(struct lws_cache_ttl_lru *cache, const char *specific_key,
+		   const void **pdata, size_t *psize);
+
+/**
+ * lws_cache_item_remove() - remove item from all cache levels
+ *
+ * \param cache: the cache to search for the key
+ * \param wildcard_key: the item key string
+ *
+ * Removes any copy of any item matching the \p wildcard_key from any cache
+ * level in one step.
+ *
+ * Adding or removing cache items may cause invalidation of cached queries
+ * that could refer to the removed item.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cache_item_remove(struct lws_cache_ttl_lru *cache, const char *wildcard_key);
+
+/**
+ * lws_cache_footprint() - query the amount of storage used by the cache layer
+ *
+ * \param cache: cache to query
+ *
+ * Returns number of payload bytes stored in cache currently
+ */
+LWS_VISIBLE LWS_EXTERN uint64_t
+lws_cache_footprint(struct lws_cache_ttl_lru *cache);
+
+/**
+ * lws_cache_debug_dump() - if built in debug mode dump cache contents to log
+ *
+ * \param cache: cache to dump
+ *
+ * If lws was built in debug mode, dump cache to log, otherwise a NOP.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_cache_debug_dump(struct lws_cache_ttl_lru *cache);
+
+typedef struct lws_cache_results {
+	const uint8_t		*ptr; /* set before using walk api */
+	size_t			size; /* set before using walk api */
+
+	size_t			payload_len;
+	size_t			tag_len;
+	const uint8_t		*tag;
+} lws_cache_results_t;
+
+/**
+ * lws_cache_results_walk() - parse next result
+ *
+ * \param walk_ctx: the context of the results blob to walk
+ *
+ * Caller must initialize \p walk_ctx.ptr and \p walk_ctx.size before calling.
+ * These are set to the results returned from a _lookup api call.
+ *
+ * The call returns 0 if the struct elements have been set to a result, or 1
+ * if there where no more results in the blob to walk.
+ *
+ * If successful, after the call \p payload_len is set to the length of the
+ * payload related to this result key (the payload itself is not present),
+ * \p tag_len is set to the length of the result key name, and \p tag is set
+ * to the result tag name, with a terminating NUL.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cache_results_walk(lws_cache_results_t *walk_ctx);
+
+typedef void (*lws_cache_item_destroy_cb)(void *item, size_t size);
+struct lws_cache_creation_info {
+	struct lws_context		*cx;
+	/**< Mandatory: the lws_context */
+	const char			*name;
+	/**< Mandatory: short cache name */
+	lws_cache_item_destroy_cb	cb;
+	/**< NULL, or a callback that can hook cache item destory */
+	struct lws_cache_ttl_lru	*parent;
+	/**< NULL, or next cache level */
+	const struct lws_cache_ops	*ops;
+	/**< NULL for default, heap-based ops, else custom cache storage and
+	 * query implementation */
+
+	union {
+		struct {
+			const char 	*filepath;
+			/**< the filepath to store items in */
+		} nscookiejar;
+	} u;
+	/**< these are extra configuration for specific cache types */
+
+	size_t				max_footprint;
+	/**< 0, or the max heap allocation allowed before destroying
+	 *   lru items to keep it under the limit */
+	size_t				max_items;
+	/**< 0, or the max number of items allowed in the cache before
+	 *   destroying lru items to keep it under the limit */
+	size_t				max_payload;
+	/**< 0, or the max allowed payload size for one item */
+	int				tsi;
+	/**< 0 unless using SMP, then tsi to bind sul to */
+};
+
+struct lws_cache_ops {
+	struct lws_cache_ttl_lru *
+	(*create)(const struct lws_cache_creation_info *info);
+	/**< create an instance of the cache type specified in info */
+
+	void
+	(*destroy)(struct lws_cache_ttl_lru **_cache);
+	/**< destroy the logical cache instance pointed to by *_cache, doesn't
+	 * affect any NV backing storage */
+
+	int
+	(*expunge)(struct lws_cache_ttl_lru *cache);
+	/**< completely delete any backing storage related to the cache
+	 * instance, eg, delete the backing file */
+
+	int
+	(*write)(struct lws_cache_ttl_lru *cache, const char *specific_key,
+		 const uint8_t *source, size_t size, lws_usec_t expiry,
+		 void **ppvoid);
+	/**< create an entry in the cache level according to the given info */
+	int
+	(*tag_match)(struct lws_cache_ttl_lru *cache, const char *wc,
+		     const char *tag, char lookup_rules);
+	/**< Just tell us if tag would match wildcard, using whatever special
+	 * rules the backing store might use for tag matching.  0 indicates
+	 * it is a match on wildcard, nonzero means does not match.
+	 */
+	int
+	(*lookup)(struct lws_cache_ttl_lru *cache, const char *wildcard_key,
+		      lws_dll2_owner_t *results_owner);
+	/**+ add keys for search_key matches not already listed in the results
+	 * owner */
+	int
+	(*invalidate)(struct lws_cache_ttl_lru *cache, const char *wildcard_key);
+	/**< remove matching item(s) from cache level */
+
+	int
+	(*get)(struct lws_cache_ttl_lru *cache, const char *specific_key,
+	       const void **pdata, size_t *psize);
+	/**< if it has the item, fills L1 with item. updates LRU, and returns
+	 * pointer to payload in L1 */
+
+	void
+	(*debug_dump)(struct lws_cache_ttl_lru *cache);
+	/**< Helper to dump the whole cache contents to log, useful for debug */
+};
+
+/**
+ * lws_cache_create() - create an empty cache you can allocate items in
+ *
+ * \param info: a struct describing the cache to create
+ *
+ * Create an empty cache you can allocate items in.  The cache will be kept
+ * below the max_footprint and max_items limits if they are nonzero, by
+ * destroying least-recently-used items until it remains below the limits.
+ *
+ * Items will auto-destroy when their expiry time is reached.
+ *
+ * When items are destroyed from the cache, if \p cb is non-NULL, it will be
+ * called back with the item pointer after it has been removed from the cache,
+ * but before it is deallocated and destroyed.
+ *
+ * context and tsi are used when scheduling expiry callbacks
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_cache_ttl_lru *
+lws_cache_create(const struct lws_cache_creation_info *info);
+
+/**
+ * lws_cache_destroy() - destroy a previously created cache
+ *
+ * \param cache: pointer to the cache
+ *
+ * Everything in the cache is destroyed, then the cache itself is destroyed,
+ * and *cache set to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_cache_destroy(struct lws_cache_ttl_lru **cache);
+
+/**
+ * lws_cache_expunge() - destroy all items in cache and parents
+ *
+ * \param cache: pointer to the cache
+ *
+ * Everything in the cache and parents is destroyed, leaving it empty.
+ * If the cache has a backing store, it is deleted.
+ *
+ * Returns 0 if no problems reported at any cache layer, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cache_expunge(struct lws_cache_ttl_lru *cache);
+
+LWS_VISIBLE extern const struct lws_cache_ops lws_cache_ops_heap,
+					      lws_cache_ops_nscookiejar;
+
+///@}
+

include/libwebsockets/lws-callbacks.h

@@ -0,0 +1,927 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup usercb User Callback
+ *
+ * ##User protocol callback
+ *
+ * The protocol callback is the primary way lws interacts with
+ * user code.  For one of a list of a few dozen reasons the callback gets
+ * called at some event to be handled.
+ *
+ * All of the events can be ignored, returning 0 is taken as "OK" and returning
+ * nonzero in most cases indicates that the connection should be closed.
+ */
+///@{
+
+struct lws_ssl_info {
+	int where;
+	int ret;
+};
+
+enum lws_cert_update_state {
+	LWS_CUS_IDLE,
+	LWS_CUS_STARTING,
+	LWS_CUS_SUCCESS,
+	LWS_CUS_FAILED,
+
+	LWS_CUS_CREATE_KEYS,
+	LWS_CUS_REG,
+	LWS_CUS_AUTH,
+	LWS_CUS_CHALLENGE,
+	LWS_CUS_CREATE_REQ,
+	LWS_CUS_REQ,
+	LWS_CUS_CONFIRM,
+	LWS_CUS_ISSUE,
+};
+
+enum {
+	LWS_TLS_REQ_ELEMENT_COUNTRY,
+	LWS_TLS_REQ_ELEMENT_STATE,
+	LWS_TLS_REQ_ELEMENT_LOCALITY,
+	LWS_TLS_REQ_ELEMENT_ORGANIZATION,
+	LWS_TLS_REQ_ELEMENT_COMMON_NAME,
+	LWS_TLS_REQ_ELEMENT_SUBJECT_ALT_NAME,
+	LWS_TLS_REQ_ELEMENT_EMAIL,
+
+	LWS_TLS_REQ_ELEMENT_COUNT,
+
+	LWS_TLS_SET_DIR_URL = LWS_TLS_REQ_ELEMENT_COUNT,
+	LWS_TLS_SET_AUTH_PATH,
+	LWS_TLS_SET_CERT_PATH,
+	LWS_TLS_SET_KEY_PATH,
+
+	LWS_TLS_TOTAL_COUNT
+};
+
+struct lws_acme_cert_aging_args {
+	struct lws_vhost *vh;
+	const char *element_overrides[LWS_TLS_TOTAL_COUNT]; /* NULL = use pvo */
+};
+
+/*
+ * With LWS_CALLBACK_FILTER_NETWORK_CONNECTION callback, user_data pointer
+ * points to one of these
+ */
+
+struct lws_filter_network_conn_args {
+	struct sockaddr_storage		cli_addr;
+	socklen_t			clilen;
+	lws_sockfd_type			accept_fd;
+};
+
+/*
+ * NOTE: These public enums are part of the abi.  If you want to add one,
+ * add it at where specified so existing users are unaffected.
+ */
+/** enum lws_callback_reasons - reason you're getting a protocol callback */
+enum lws_callback_reasons {
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to wsi and protocol binding lifecycle -----
+	 */
+
+	LWS_CALLBACK_PROTOCOL_INIT				= 27,
+	/**< One-time call per protocol, per-vhost using it, so it can
+	 * do initial setup / allocations etc */
+
+	LWS_CALLBACK_PROTOCOL_DESTROY				= 28,
+	/**< One-time call per protocol, per-vhost using it, indicating
+	 * this protocol won't get used at all after this callback, the
+	 * vhost is getting destroyed.  Take the opportunity to
+	 * deallocate everything that was allocated by the protocol. */
+
+	LWS_CALLBACK_WSI_CREATE					= 29,
+	/**< outermost (earliest) wsi create notification to protocols[0] */
+
+	LWS_CALLBACK_WSI_DESTROY				= 30,
+	/**< outermost (latest) wsi destroy notification to protocols[0] */
+
+	LWS_CALLBACK_WSI_TX_CREDIT_GET				= 103,
+	/**< manually-managed connection received TX credit (len is int32) */
+
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to Server TLS -----
+	 */
+
+	LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS	= 21,
+	/**< if configured for
+	 * including OpenSSL support, this callback allows your user code
+	 * to perform extra SSL_CTX_load_verify_locations() or similar
+	 * calls to direct OpenSSL where to find certificates the client
+	 * can use to confirm the remote server identity.  user is the
+	 * OpenSSL SSL_CTX* */
+
+	LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS	= 22,
+	/**< if configured for
+	 * including OpenSSL support, this callback allows your user code
+	 * to load extra certificates into the server which allow it to
+	 * verify the validity of certificates returned by clients.  user
+	 * is the server's OpenSSL SSL_CTX* and in is the lws_vhost */
+
+	LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION	= 23,
+	/**< if the libwebsockets vhost was created with the option
+	 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
+	 * callback is generated during OpenSSL verification of the cert
+	 * sent from the client.  It is sent to protocol[0] callback as
+	 * no protocol has been negotiated on the connection yet.
+	 * Notice that the libwebsockets context and wsi are both NULL
+	 * during this callback.  See
+	 *  http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
+	 * to understand more detail about the OpenSSL callback that
+	 * generates this libwebsockets callback and the meanings of the
+	 * arguments passed.  In this callback, user is the x509_ctx,
+	 * in is the ssl pointer and len is preverify_ok
+	 * Notice that this callback maintains libwebsocket return
+	 * conventions, return 0 to mean the cert is OK or 1 to fail it.
+	 * This also means that if you don't handle this callback then
+	 * the default callback action of returning 0 allows the client
+	 * certificates. */
+
+	LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY	= 37,
+	/**< if configured for including OpenSSL support but no private key
+	 * file has been specified (ssl_private_key_filepath is NULL), this is
+	 * called to allow the user to set the private key directly via
+	 * libopenssl and perform further operations if required; this might be
+	 * useful in situations where the private key is not directly accessible
+	 * by the OS, for example if it is stored on a smartcard.
+	 * user is the server's OpenSSL SSL_CTX* */
+
+	LWS_CALLBACK_SSL_INFO					= 67,
+	/**< SSL connections only.  An event you registered an
+	 * interest in at the vhost has occurred on a connection
+	 * using the vhost.  in is a pointer to a
+	 * struct lws_ssl_info containing information about the
+	 * event*/
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to Client TLS -----
+	 */
+
+	LWS_CALLBACK_OPENSSL_PERFORM_SERVER_CERT_VERIFICATION = 58,
+	/**< Similar to LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION
+	 * this callback is called during OpenSSL verification of the cert
+	 * sent from the server to the client. It is sent to protocol[0]
+	 * callback as no protocol has been negotiated on the connection yet.
+	 * Notice that the wsi is set because lws_client_connect_via_info was
+	 * successful.
+	 *
+	 * See http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
+	 * to understand more detail about the OpenSSL callback that
+	 * generates this libwebsockets callback and the meanings of the
+	 * arguments passed. In this callback, user is the x509_ctx,
+	 * in is the ssl pointer and len is preverify_ok.
+	 *
+	 * THIS IS NOT RECOMMENDED BUT if a cert validation error shall be
+	 * overruled and cert shall be accepted as ok,
+	 * X509_STORE_CTX_set_error((X509_STORE_CTX*)user, X509_V_OK); must be
+	 * called and return value must be 0 to mean the cert is OK;
+	 * returning 1 will fail the cert in any case.
+	 *
+	 * This also means that if you don't handle this callback then
+	 * the default callback action of returning 0 will not accept the
+	 * certificate in case of a validation error decided by the SSL lib.
+	 *
+	 * This is expected and secure behaviour when validating certificates.
+	 *
+	 * Note: LCCSCF_ALLOW_SELFSIGNED and
+	 * LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK still work without this
+	 * callback being implemented.
+	 */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to HTTP Server  -----
+	 */
+
+	LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED		= 19,
+	/**< A new client has been accepted by the ws server.  This
+	 * callback allows setting any relevant property to it. Because this
+	 * happens immediately after the instantiation of a new client,
+	 * there's no websocket protocol selected yet so this callback is
+	 * issued only to protocol 0. Only wsi is defined, pointing to the
+	 * new client, and the return value is ignored. */
+
+	LWS_CALLBACK_HTTP					= 12,
+	/**< an http request has come from a client that is not
+	 * asking to upgrade the connection to a websocket
+	 * one.  This is a chance to serve http content,
+	 * for example, to send a script to the client
+	 * which will then open the websockets connection.
+	 * in points to the URI path requested and
+	 * lws_serve_http_file() makes it very
+	 * simple to send back a file to the client.
+	 * Normally after sending the file you are done
+	 * with the http connection, since the rest of the
+	 * activity will come by websockets from the script
+	 * that was delivered by http, so you will want to
+	 * return 1; to close and free up the connection. */
+
+	LWS_CALLBACK_HTTP_BODY					= 13,
+	/**< the next len bytes data from the http
+	 * request body HTTP connection is now available in in. */
+
+	LWS_CALLBACK_HTTP_BODY_COMPLETION			= 14,
+	/**< the expected amount of http request body has been delivered */
+
+	LWS_CALLBACK_HTTP_FILE_COMPLETION			= 15,
+	/**< a file requested to be sent down http link has completed. */
+
+	LWS_CALLBACK_HTTP_WRITEABLE				= 16,
+	/**< you can write more down the http protocol link now. */
+
+	LWS_CALLBACK_CLOSED_HTTP				=  5,
+	/**< when a HTTP (non-websocket) session ends */
+
+	LWS_CALLBACK_FILTER_HTTP_CONNECTION			= 18,
+	/**< called when the request has
+	 * been received and parsed from the client, but the response is
+	 * not sent yet.  Return non-zero to disallow the connection.
+	 * user is a pointer to the connection user space allocation,
+	 * in is the URI, eg, "/"
+	 * In your handler you can use the public APIs
+	 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
+	 * headers using the header enums lws_token_indexes from
+	 * libwebsockets.h to check for and read the supported header
+	 * presence and content before deciding to allow the http
+	 * connection to proceed or to kill the connection. */
+
+	LWS_CALLBACK_ADD_HEADERS				= 53,
+	/**< This gives your user code a chance to add headers to a server
+	 * transaction bound to your protocol.  `in` points to a
+	 * `struct lws_process_html_args` describing a buffer and length
+	 * you can add headers into using the normal lws apis.
+	 *
+	 * (see LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER to add headers to
+	 * a client transaction)
+	 *
+	 * Only `args->p` and `args->len` are valid, and `args->p` should
+	 * be moved on by the amount of bytes written, if any.  Eg
+	 *
+	 * 	case LWS_CALLBACK_ADD_HEADERS:
+	 *
+	 *          struct lws_process_html_args *args =
+	 *          		(struct lws_process_html_args *)in;
+	 *
+	 *	    if (lws_add_http_header_by_name(wsi,
+	 *			(unsigned char *)"set-cookie:",
+	 *			(unsigned char *)cookie, cookie_len,
+	 *			(unsigned char **)&args->p,
+	 *			(unsigned char *)args->p + args->max_len))
+	 *		return 1;
+	 *
+	 *          break;
+	 */
+
+	LWS_CALLBACK_VERIFY_BASIC_AUTHORIZATION = 102,
+	/**< This gives the user code a chance to accept or reject credentials
+	 * provided HTTP to basic authorization. It will only be called if the
+	 * http mount's authentication_mode is set to LWSAUTHM_BASIC_AUTH_CALLBACK
+	 * `in` points to a credential string of the form `username:password` If
+	 * the callback returns zero (the default if unhandled), then the
+	 * transaction ends with HTTP_STATUS_UNAUTHORIZED, otherwise the request
+	 * will be processed */
+
+	LWS_CALLBACK_CHECK_ACCESS_RIGHTS			= 51,
+	/**< This gives the user code a chance to forbid an http access.
+	 * `in` points to a `struct lws_process_html_args`, which
+	 * describes the URL, and a bit mask describing the type of
+	 * authentication required.  If the callback returns nonzero,
+	 * the transaction ends with HTTP_STATUS_UNAUTHORIZED. */
+
+	LWS_CALLBACK_PROCESS_HTML				= 52,
+	/**< This gives your user code a chance to mangle outgoing
+	 * HTML.  `in` points to a `struct lws_process_html_args`
+	 * which describes the buffer containing outgoing HTML.
+	 * The buffer may grow up to `.max_len` (currently +128
+	 * bytes per buffer).
+	 */
+
+	LWS_CALLBACK_HTTP_BIND_PROTOCOL				= 49,
+	/**< By default, all HTTP handling is done in protocols[0].
+	 * However you can bind different protocols (by name) to
+	 * different parts of the URL space using callback mounts.  This
+	 * callback occurs in the new protocol when a wsi is bound
+	 * to that protocol.  Any protocol allocation related to the
+	 * http transaction processing should be created then.
+	 * These specific callbacks are necessary because with HTTP/1.1,
+	 * a single connection may perform at series of different
+	 * transactions at different URLs, thus the lifetime of the
+	 * protocol bind is just for one transaction, not connection. */
+
+	LWS_CALLBACK_HTTP_DROP_PROTOCOL				= 50,
+	/**< This is called when a transaction is unbound from a protocol.
+	 * It indicates the connection completed its transaction and may
+	 * do something different now.  Any protocol allocation related
+	 * to the http transaction processing should be destroyed. */
+
+	LWS_CALLBACK_HTTP_CONFIRM_UPGRADE			= 86,
+	/**< This is your chance to reject an HTTP upgrade action.  The
+	 * name of the protocol being upgraded to is in 'in', and the ah
+	 * is still bound to the wsi, so you can look at the headers.
+	 *
+	 * The default of returning 0 (ie, also if not handled) means the
+	 * upgrade may proceed.  Return <0 to just hang up the connection,
+	 * or >0 if you have rejected the connection by returning http headers
+	 * and response code yourself.
+	 *
+	 * There is no need for you to call transaction_completed() as the
+	 * caller will take care of it when it sees you returned >0.
+	 */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to HTTP Client  -----
+	 */
+
+	LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP			= 44,
+	/**< The HTTP client connection has succeeded, and is now
+	 * connected to the server */
+
+	LWS_CALLBACK_CLOSED_CLIENT_HTTP				= 45,
+	/**< The HTTP client connection is closing */
+
+	LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ			= 48,
+	/**< This is generated by lws_http_client_read() used to drain
+	 * incoming data.  In the case the incoming data was chunked, it will
+	 * be split into multiple smaller callbacks for each chunk block,
+	 * removing the chunk headers. If not chunked, it will appear all in
+	 * one callback. */
+
+	LWS_CALLBACK_RECEIVE_CLIENT_HTTP			= 46,
+	/**< This indicates data was received on the HTTP client connection.  It
+	 * does NOT actually drain or provide the data, so if you are doing
+	 * http client, you MUST handle this and call lws_http_client_read().
+	 * Failure to deal with it as in the minimal examples may cause spinning
+	 * around the event loop as it's continuously signalled the same data
+	 * is available for read.  The related minimal examples show how to
+	 * handle it.
+	 *
+	 * It's possible to defer calling lws_http_client_read() if you use
+	 * rx flow control to stop further rx handling on the connection until
+	 * you did deal with it.  But normally you would call it in the handler.
+	 *
+	 * lws_http_client_read() strips any chunked framing and calls back
+	 * with only payload data to LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ.  The
+	 * chunking is the reason this is not just all done in one callback for
+	 * http.
+	 */
+	LWS_CALLBACK_COMPLETED_CLIENT_HTTP			= 47,
+	/**< The client transaction completed... at the moment this
+	 * is the same as closing since transaction pipelining on
+	 * client side is not yet supported.  */
+
+	LWS_CALLBACK_CLIENT_HTTP_WRITEABLE			= 57,
+	/**< when doing an HTTP type client connection, you can call
+	 * lws_client_http_body_pending(wsi, 1) from
+	 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER to get these callbacks
+	 * sending the HTTP headers.
+	 *
+	 * From this callback, when you have sent everything, you should let
+	 * lws know by calling lws_client_http_body_pending(wsi, 0)
+	 */
+
+	LWS_CALLBACK_CLIENT_HTTP_REDIRECT			= 104,
+	/**< we're handling a 3xx redirect... return nonzero to hang up */
+
+	LWS_CALLBACK_CLIENT_HTTP_BIND_PROTOCOL			= 85,
+	LWS_CALLBACK_CLIENT_HTTP_DROP_PROTOCOL			= 76,
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to Websocket Server -----
+	 */
+
+	LWS_CALLBACK_ESTABLISHED				=  0,
+	/**< (VH) after the server completes a handshake with an incoming
+	 * client.  If you built the library with ssl support, in is a
+	 * pointer to the ssl struct associated with the connection or NULL.
+	 *
+	 * b0 of len is set if the connection was made using ws-over-h2
+	 */
+
+	LWS_CALLBACK_CLOSED					=  4,
+	/**< when the websocket session ends */
+
+	LWS_CALLBACK_SERVER_WRITEABLE				= 11,
+	/**< See LWS_CALLBACK_CLIENT_WRITEABLE */
+
+	LWS_CALLBACK_RECEIVE					=  6,
+	/**< data has appeared for this server endpoint from a
+	 * remote client, it can be found at *in and is
+	 * len bytes long */
+
+	LWS_CALLBACK_RECEIVE_PONG				=  7,
+	/**< servers receive PONG packets with this callback reason */
+
+	LWS_CALLBACK_WS_PEER_INITIATED_CLOSE			= 38,
+	/**< The peer has sent an unsolicited Close WS packet.  in and
+	 * len are the optional close code (first 2 bytes, network
+	 * order) and the optional additional information which is not
+	 * defined in the standard, and may be a string or non human-readable
+	 * data.
+	 * If you return 0 lws will echo the close and then close the
+	 * connection.  If you return nonzero lws will just close the
+	 * connection. */
+
+	LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION			= 20,
+	/**< called when the handshake has
+	 * been received and parsed from the client, but the response is
+	 * not sent yet.  Return non-zero to disallow the connection.
+	 * user is a pointer to the connection user space allocation,
+	 * in is the requested protocol name
+	 * In your handler you can use the public APIs
+	 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
+	 * headers using the header enums lws_token_indexes from
+	 * libwebsockets.h to check for and read the supported header
+	 * presence and content before deciding to allow the handshake
+	 * to proceed or to kill the connection. */
+
+	LWS_CALLBACK_CONFIRM_EXTENSION_OKAY			= 25,
+	/**< When the server handshake code
+	 * sees that it does support a requested extension, before
+	 * accepting the extension by additing to the list sent back to
+	 * the client it gives this callback just to check that it's okay
+	 * to use that extension.  It calls back to the requested protocol
+	 * and with in being the extension name, len is 0 and user is
+	 * valid.  Note though at this time the ESTABLISHED callback hasn't
+	 * happened yet so if you initialize user content there, user
+	 * content during this callback might not be useful for anything. */
+
+	LWS_CALLBACK_WS_SERVER_BIND_PROTOCOL			= 77,
+	LWS_CALLBACK_WS_SERVER_DROP_PROTOCOL			= 78,
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to Websocket Client -----
+	 */
+
+	LWS_CALLBACK_CLIENT_CONNECTION_ERROR			=  1,
+	/**< the request client connection has been unable to complete a
+	 * handshake with the remote server.  If in is non-NULL, you can
+	 * find an error string of length len where it points to
+	 *
+	 * Diagnostic strings that may be returned include
+	 *
+	 *     	"getaddrinfo (ipv6) failed"
+	 *     	"unknown address family"
+	 *     	"getaddrinfo (ipv4) failed"
+	 *     	"set socket opts failed"
+	 *     	"insert wsi failed"
+	 *     	"lws_ssl_client_connect1 failed"
+	 *     	"lws_ssl_client_connect2 failed"
+	 *     	"Peer hung up"
+	 *     	"read failed"
+	 *     	"HS: URI missing"
+	 *     	"HS: Redirect code but no Location"
+	 *     	"HS: URI did not parse"
+	 *     	"HS: Redirect failed"
+	 *     	"HS: Server did not return 200"
+	 *     	"HS: OOM"
+	 *     	"HS: disallowed by client filter"
+	 *     	"HS: disallowed at ESTABLISHED"
+	 *     	"HS: ACCEPT missing"
+	 *     	"HS: ws upgrade response not 101"
+	 *     	"HS: UPGRADE missing"
+	 *     	"HS: Upgrade to something other than websocket"
+	 *     	"HS: CONNECTION missing"
+	 *     	"HS: UPGRADE malformed"
+	 *     	"HS: PROTOCOL malformed"
+	 *     	"HS: Cannot match protocol"
+	 *     	"HS: EXT: list too big"
+	 *     	"HS: EXT: failed setting defaults"
+	 *     	"HS: EXT: failed parsing defaults"
+	 *     	"HS: EXT: failed parsing options"
+	 *     	"HS: EXT: Rejects server options"
+	 *     	"HS: EXT: unknown ext"
+	 *     	"HS: Accept hash wrong"
+	 *     	"HS: Rejected by filter cb"
+	 *     	"HS: OOM"
+	 *     	"HS: SO_SNDBUF failed"
+	 *     	"HS: Rejected at CLIENT_ESTABLISHED"
+	 */
+
+	LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH		=  2,
+	/**< this is the last chance for the client user code to examine the
+	 * http headers and decide to reject the connection.  If the
+	 * content in the headers is interesting to the
+	 * client (url, etc) it needs to copy it out at
+	 * this point since it will be destroyed before
+	 * the CLIENT_ESTABLISHED call */
+
+	LWS_CALLBACK_CLIENT_ESTABLISHED				=  3,
+	/**< after your client connection completed the websocket upgrade
+	 * handshake with the remote server */
+
+	LWS_CALLBACK_CLIENT_CLOSED				= 75,
+	/**< when a client websocket session ends */
+
+	LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER		= 24,
+	/**< this callback happens
+	 * when a client handshake is being compiled.  user is NULL,
+	 * in is a char **, it's pointing to a char * which holds the
+	 * next location in the header buffer where you can add
+	 * headers, and len is the remaining space in the header buffer,
+	 * which is typically some hundreds of bytes.  So, to add a canned
+	 * cookie, your handler code might look similar to:
+	 *
+	 *	char **p = (char **)in, *end = (*p) + len;
+	 *
+	 *	if (lws_add_http_header_by_token(wsi, WSI_TOKEN_HTTP_COOKIE,
+	 *			(unsigned char)"a=b", 3, p, end))
+	 *		return -1;
+	 *
+	 * See LWS_CALLBACK_ADD_HEADERS for adding headers to server
+	 * transactions.
+	 */
+
+	LWS_CALLBACK_CLIENT_RECEIVE				=  8,
+	/**< data has appeared from the server for the client connection, it
+	 * can be found at *in and is len bytes long */
+
+	LWS_CALLBACK_CLIENT_RECEIVE_PONG			=  9,
+	/**< clients receive PONG packets with this callback reason */
+
+	LWS_CALLBACK_CLIENT_WRITEABLE				= 10,
+	/**<  If you call lws_callback_on_writable() on a connection, you will
+	 * get one of these callbacks coming when the connection socket
+	 * is able to accept another write packet without blocking.
+	 * If it already was able to take another packet without blocking,
+	 * you'll get this callback at the next call to the service loop
+	 * function.  Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
+	 * and servers get LWS_CALLBACK_SERVER_WRITEABLE. */
+
+	LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED		= 26,
+	/**< When a ws client
+	 * connection is being prepared to start a handshake to a server,
+	 * each supported extension is checked with protocols[0] callback
+	 * with this reason, giving the user code a chance to suppress the
+	 * claim to support that extension by returning non-zero.  If
+	 * unhandled, by default 0 will be returned and the extension
+	 * support included in the header to the server.  Notice this
+	 * callback comes to protocols[0]. */
+
+	LWS_CALLBACK_WS_EXT_DEFAULTS				= 39,
+	/**< Gives client connections an opportunity to adjust negotiated
+	 * extension defaults.  `user` is the extension name that was
+	 * negotiated (eg, "permessage-deflate").  `in` points to a
+	 * buffer and `len` is the buffer size.  The user callback can
+	 * set the buffer to a string describing options the extension
+	 * should parse.  Or just ignore for defaults. */
+
+
+	LWS_CALLBACK_FILTER_NETWORK_CONNECTION			= 17,
+	/**< called when a client connects to
+	 * the server at network level; the connection is accepted but then
+	 * passed to this callback to decide whether to hang up immediately
+	 * or not, based on the client IP.
+	 *
+	 * user_data in the callback points to a
+	 * struct lws_filter_network_conn_args that is prepared with the
+	 * sockfd, and the peer's address information.
+	 *
+	 * in contains the connection socket's descriptor.
+	 *
+	 * Since the client connection information is not available yet,
+	 * wsi still pointing to the main server socket.
+	 *
+	 * Return non-zero to terminate the connection before sending or
+	 * receiving anything. Because this happens immediately after the
+	 * network connection from the client, there's no websocket protocol
+	 * selected yet so this callback is issued only to protocol 0. */
+
+	LWS_CALLBACK_WS_CLIENT_BIND_PROTOCOL			= 79,
+	LWS_CALLBACK_WS_CLIENT_DROP_PROTOCOL			= 80,
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to external poll loop integration  -----
+	 */
+
+	LWS_CALLBACK_GET_THREAD_ID				= 31,
+	/**< lws can accept callback when writable requests from other
+	 * threads, if you implement this callback and return an opaque
+	 * current thread ID integer. */
+
+	/* external poll() management support */
+	LWS_CALLBACK_ADD_POLL_FD				= 32,
+	/**< lws normally deals with its poll() or other event loop
+	 * internally, but in the case you are integrating with another
+	 * server you will need to have lws sockets share a
+	 * polling array with the other server.  This and the other
+	 * POLL_FD related callbacks let you put your specialized
+	 * poll array interface code in the callback for protocol 0, the
+	 * first protocol you support, usually the HTTP protocol in the
+	 * serving case.
+	 * This callback happens when a socket needs to be
+	 * added to the polling loop: in points to a struct
+	 * lws_pollargs; the fd member of the struct is the file
+	 * descriptor, and events contains the active events
+	 *
+	 * If you are using the internal lws polling / event loop
+	 * you can just ignore these callbacks. */
+
+	LWS_CALLBACK_DEL_POLL_FD				= 33,
+	/**< This callback happens when a socket descriptor
+	 * needs to be removed from an external polling array.  in is
+	 * again the struct lws_pollargs containing the fd member
+	 * to be removed.  If you are using the internal polling
+	 * loop, you can just ignore it. */
+
+	LWS_CALLBACK_CHANGE_MODE_POLL_FD			= 34,
+	/**< This callback happens when lws wants to modify the events for
+	 * a connection.
+	 * in is the struct lws_pollargs with the fd to change.
+	 * The new event mask is in events member and the old mask is in
+	 * the prev_events member.
+	 * If you are using the internal polling loop, you can just ignore
+	 * it. */
+
+	LWS_CALLBACK_LOCK_POLL					= 35,
+	/**< These allow the external poll changes driven
+	 * by lws to participate in an external thread locking
+	 * scheme around the changes, so the whole thing is threadsafe.
+	 * These are called around three activities in the library,
+	 *	- inserting a new wsi in the wsi / fd table (len=1)
+	 *	- deleting a wsi from the wsi / fd table (len=1)
+	 *	- changing a wsi's POLLIN/OUT state (len=0)
+	 * Locking and unlocking external synchronization objects when
+	 * len == 1 allows external threads to be synchronized against
+	 * wsi lifecycle changes if it acquires the same lock for the
+	 * duration of wsi dereference from the other thread context. */
+
+	LWS_CALLBACK_UNLOCK_POLL				= 36,
+	/**< See LWS_CALLBACK_LOCK_POLL, ignore if using lws internal poll */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to CGI serving -----
+	 */
+
+	LWS_CALLBACK_CGI					= 40,
+	/**< CGI: CGI IO events on stdin / out / err are sent here on
+	 * protocols[0].  The provided `lws_callback_http_dummy()`
+	 * handles this and the callback should be directed there if
+	 * you use CGI. */
+
+	LWS_CALLBACK_CGI_TERMINATED				= 41,
+	/**< CGI: The related CGI process ended, this is called before
+	 * the wsi is closed.  Used to, eg, terminate chunking.
+	 * The provided `lws_callback_http_dummy()`
+	 * handles this and the callback should be directed there if
+	 * you use CGI.  The child PID that terminated is in len. */
+
+	LWS_CALLBACK_CGI_STDIN_DATA				= 42,
+	/**< CGI: Data is, to be sent to the CGI process stdin, eg from
+	 * a POST body.  The provided `lws_callback_http_dummy()`
+	 * handles this and the callback should be directed there if
+	 * you use CGI. */
+
+	LWS_CALLBACK_CGI_STDIN_COMPLETED			= 43,
+	/**< CGI: no more stdin is coming.  The provided
+	 * `lws_callback_http_dummy()` handles this and the callback
+	 * should be directed there if you use CGI. */
+
+	LWS_CALLBACK_CGI_PROCESS_ATTACH				= 70,
+	/**< CGI: Sent when the CGI process is spawned for the wsi.  The
+	 * len parameter is the PID of the child process */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to Generic Sessions -----
+	 */
+
+	LWS_CALLBACK_SESSION_INFO				= 54,
+	/**< This is only generated by user code using generic sessions.
+	 * It's used to get a `struct lws_session_info` filled in by
+	 * generic sessions with information about the logged-in user.
+	 * See the messageboard sample for an example of how to use. */
+
+	LWS_CALLBACK_GS_EVENT					= 55,
+	/**< Indicates an event happened to the Generic Sessions session.
+	 * `in` contains a `struct lws_gs_event_args` describing the event. */
+
+	LWS_CALLBACK_HTTP_PMO					= 56,
+	/**< per-mount options for this connection, called before
+	 * the normal LWS_CALLBACK_HTTP when the mount has per-mount
+	 * options.
+	 */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to RAW PROXY -----
+	 */
+
+	LWS_CALLBACK_RAW_PROXY_CLI_RX				= 89,
+	/**< RAW mode client (outgoing) RX */
+
+	LWS_CALLBACK_RAW_PROXY_SRV_RX				= 90,
+	/**< RAW mode server (listening) RX */
+
+	LWS_CALLBACK_RAW_PROXY_CLI_CLOSE			= 91,
+	/**< RAW mode client (outgoing) is closing */
+
+	LWS_CALLBACK_RAW_PROXY_SRV_CLOSE			= 92,
+	/**< RAW mode server (listening) is closing */
+
+	LWS_CALLBACK_RAW_PROXY_CLI_WRITEABLE			= 93,
+	/**< RAW mode client (outgoing) may be written */
+
+	LWS_CALLBACK_RAW_PROXY_SRV_WRITEABLE			= 94,
+	/**< RAW mode server (listening) may be written */
+
+	LWS_CALLBACK_RAW_PROXY_CLI_ADOPT			= 95,
+	/**< RAW mode client (onward) accepted socket was adopted
+	 *   (equivalent to 'wsi created') */
+
+	LWS_CALLBACK_RAW_PROXY_SRV_ADOPT			= 96,
+	/**< RAW mode server (listening) accepted socket was adopted
+	 *   (equivalent to 'wsi created') */
+
+	LWS_CALLBACK_RAW_PROXY_CLI_BIND_PROTOCOL		= 97,
+	LWS_CALLBACK_RAW_PROXY_SRV_BIND_PROTOCOL		= 98,
+	LWS_CALLBACK_RAW_PROXY_CLI_DROP_PROTOCOL		= 99,
+	LWS_CALLBACK_RAW_PROXY_SRV_DROP_PROTOCOL		= 100,
+
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to RAW sockets -----
+	 */
+
+	LWS_CALLBACK_RAW_RX					= 59,
+	/**< RAW mode connection RX */
+
+	LWS_CALLBACK_RAW_CLOSE					= 60,
+	/**< RAW mode connection is closing */
+
+	LWS_CALLBACK_RAW_WRITEABLE				= 61,
+	/**< RAW mode connection may be written */
+
+	LWS_CALLBACK_RAW_ADOPT					= 62,
+	/**< RAW mode connection was adopted (equivalent to 'wsi created') */
+
+	LWS_CALLBACK_RAW_CONNECTED				= 101,
+	/**< outgoing client RAW mode connection was connected */
+
+	LWS_CALLBACK_RAW_SKT_BIND_PROTOCOL			= 81,
+	LWS_CALLBACK_RAW_SKT_DROP_PROTOCOL			= 82,
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to RAW file handles -----
+	 */
+
+	LWS_CALLBACK_RAW_ADOPT_FILE				= 63,
+	/**< RAW mode file was adopted (equivalent to 'wsi created') */
+
+	LWS_CALLBACK_RAW_RX_FILE				= 64,
+	/**< This is the indication the RAW mode file has something to read.
+	 *   This doesn't actually do the read of the file and len is always
+	 *   0... your code should do the read having been informed there is
+	 *   something to read now. */
+
+	LWS_CALLBACK_RAW_WRITEABLE_FILE				= 65,
+	/**< RAW mode file is writeable */
+
+	LWS_CALLBACK_RAW_CLOSE_FILE				= 66,
+	/**< RAW mode wsi that adopted a file is closing */
+
+	LWS_CALLBACK_RAW_FILE_BIND_PROTOCOL			= 83,
+	LWS_CALLBACK_RAW_FILE_DROP_PROTOCOL			= 84,
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to generic wsi events -----
+	 */
+
+	LWS_CALLBACK_TIMER					= 73,
+	/**< When the time elapsed after a call to
+	 * lws_set_timer_usecs(wsi, usecs) is up, the wsi will get one of
+	 * these callbacks.  The deadline can be continuously extended into the
+	 * future by later calls to lws_set_timer_usecs() before the deadline
+	 * expires, or cancelled by lws_set_timer_usecs(wsi, -1);
+	 */
+
+	LWS_CALLBACK_EVENT_WAIT_CANCELLED			= 71,
+	/**< This is sent to every protocol of every vhost in response
+	 * to lws_cancel_service() or lws_cancel_service_pt().  This
+	 * callback is serialized in the lws event loop normally, even
+	 * if the lws_cancel_service[_pt]() call was from a different
+	 * thread. */
+
+	LWS_CALLBACK_CHILD_CLOSING				= 69,
+	/**< Sent to parent to notify them a child is closing / being
+	 * destroyed.  in is the child wsi.
+	 */
+
+	LWS_CALLBACK_CONNECTING					= 105,
+	/**< Called before a socketfd is about to connect().  In is the
+	 * socketfd, cast to a (void *), if on a platform where the socketfd
+	 * is an int, recover portably using (lws_sockfd_type)(intptr_t)in.
+	 *
+	 * It's also called in SOCKS5 or http_proxy cases where the socketfd is
+	 * going to try to connect to its proxy.
+	 */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to TLS certificate management -----
+	 */
+
+	LWS_CALLBACK_VHOST_CERT_AGING				= 72,
+	/**< When a vhost TLS cert has its expiry checked, this callback
+	 * is broadcast to every protocol of every vhost in case the
+	 * protocol wants to take some action with this information.
+	 * \p in is a pointer to a struct lws_acme_cert_aging_args,
+	 * and \p len is the number of days left before it expires, as
+	 * a (ssize_t).  In the struct lws_acme_cert_aging_args, vh
+	 * points to the vhost the cert aging information applies to,
+	 * and element_overrides[] is an optional way to update information
+	 * from the pvos... NULL in an index means use the information from
+	 * from the pvo for the cert renewal, non-NULL in the array index
+	 * means use that pointer instead for the index. */
+
+	LWS_CALLBACK_VHOST_CERT_UPDATE				= 74,
+	/**< When a vhost TLS cert is being updated, progress is
+	 * reported to the vhost in question here, including completion
+	 * and failure.  in points to optional JSON, and len represents the
+	 * connection state using enum lws_cert_update_state */
+
+	/* ---------------------------------------------------------------------
+	 * ----- Callbacks related to MQTT Client  -----
+	 */
+
+	LWS_CALLBACK_MQTT_NEW_CLIENT_INSTANTIATED		= 200,
+	LWS_CALLBACK_MQTT_IDLE					= 201,
+	LWS_CALLBACK_MQTT_CLIENT_ESTABLISHED			= 202,
+	LWS_CALLBACK_MQTT_SUBSCRIBED				= 203,
+	LWS_CALLBACK_MQTT_CLIENT_WRITEABLE			= 204,
+	LWS_CALLBACK_MQTT_CLIENT_RX				= 205,
+	LWS_CALLBACK_MQTT_UNSUBSCRIBED				= 206,
+	LWS_CALLBACK_MQTT_DROP_PROTOCOL				= 207,
+	LWS_CALLBACK_MQTT_CLIENT_CLOSED				= 208,
+	LWS_CALLBACK_MQTT_ACK					= 209,
+	/**< When a message is fully sent, if QoS0 this callback is generated
+	 * to locally "acknowledge" it.  For QoS1, this callback is only
+	 * generated when the matching PUBACK is received.  Return nonzero to
+	 * close the wsi.
+	 */
+	LWS_CALLBACK_MQTT_RESEND				= 210,
+	/**< In QoS1 or QoS2, this callback is generated instead of the _ACK one
+	 * if we timed out waiting for a PUBACK or a PUBREC, and we must resend
+	 * the message.  Return nonzero to close the wsi.
+	 */
+	LWS_CALLBACK_MQTT_UNSUBSCRIBE_TIMEOUT			= 211,
+	/**< When a UNSUBSCRIBE is sent, this callback is generated instead of
+	 * the _UNSUBSCRIBED one if we timed out waiting for a UNSUBACK.
+	 * Return nonzero to close the wsi.
+	 */
+	LWS_CALLBACK_MQTT_SHADOW_TIMEOUT			= 212,
+	/**< When a Device Shadow is sent, this callback is generated if we
+	 * timed out waiting for a response from AWS IoT.
+	 * Return nonzero to close the wsi.
+	 */
+
+	/****** add new things just above ---^ ******/
+
+	LWS_CALLBACK_USER = 1000,
+	/**<  user code can use any including above without fear of clashes */
+};
+
+
+
+/**
+ * typedef lws_callback_function() - User server actions
+ * \param wsi:	Opaque websocket instance pointer
+ * \param reason:	The reason for the call
+ * \param user:	Pointer to per-session user data allocated by library
+ * \param in:		Pointer used for some callback reasons
+ * \param len:	Length set for some callback reasons
+ *
+ *	This callback is the way the user controls what is served.  All the
+ *	protocol detail is hidden and handled by the library.
+ *
+ *	For each connection / session there is user data allocated that is
+ *	pointed to by "user".  You set the size of this user data area when
+ *	the library is initialized with lws_create_server.
+ */
+typedef int lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason, void *user, void *in, size_t len);
+
+#define LWS_CB_REASON_AUX_BF__CGI		1
+#define LWS_CB_REASON_AUX_BF__PROXY		2
+#define LWS_CB_REASON_AUX_BF__CGI_CHUNK_END	4
+#define LWS_CB_REASON_AUX_BF__CGI_HEADERS	8
+#define LWS_CB_REASON_AUX_BF__PROXY_TRANS_END	16
+#define LWS_CB_REASON_AUX_BF__PROXY_HEADERS	32
+///@}

include/libwebsockets/lws-cgi.h

@@ -0,0 +1,104 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup cgi cgi handling
+ *
+ * ##CGI handling
+ *
+ * These functions allow low-level control over stdin/out/err of the cgi.
+ *
+ * However for most cases, binding the cgi to http in and out, the default
+ * lws implementation already does the right thing.
+ */
+
+enum lws_enum_stdinouterr {
+	LWS_STDIN = 0,
+	LWS_STDOUT = 1,
+	LWS_STDERR = 2,
+};
+
+enum lws_cgi_hdr_state {
+	LCHS_HEADER,
+	LCHS_CR1,
+	LCHS_LF1,
+	LCHS_CR2,
+	LCHS_LF2,
+	LHCS_RESPONSE,
+	LHCS_DUMP_HEADERS,
+	LHCS_PAYLOAD,
+	LCHS_SINGLE_0A,
+};
+
+struct lws_cgi_args {
+	struct lws **stdwsi; /**< get fd with lws_get_socket_fd() */
+	enum lws_enum_stdinouterr ch; /**< channel index */
+	unsigned char *data; /**< for messages with payload */
+	enum lws_cgi_hdr_state hdr_state; /**< track where we are in cgi headers */
+	int len; /**< length */
+};
+
+#ifdef LWS_WITH_CGI
+/**
+ * lws_cgi: spawn network-connected cgi process
+ *
+ * \param wsi: connection to own the process
+ * \param exec_array: array of "exec-name" "arg1" ... "argn" NULL
+ * \param script_uri_path_len: how many chars on the left of the uri are the
+ *        path to the cgi, or -1 to spawn without URL-related env vars
+ * \param timeout_secs: seconds script should be allowed to run
+ * \param mp_cgienv: pvo list with per-vhost cgi options to put in env
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cgi(struct lws *wsi, const char * const *exec_array,
+	int script_uri_path_len, int timeout_secs,
+	const struct lws_protocol_vhost_options *mp_cgienv);
+
+/**
+ * lws_cgi_write_split_stdout_headers: write cgi output accounting for header part
+ *
+ * \param wsi: connection to own the process
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cgi_write_split_stdout_headers(struct lws *wsi);
+
+/**
+ * lws_cgi_kill: terminate cgi process associated with wsi
+ *
+ * \param wsi: connection to own the process
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cgi_kill(struct lws *wsi);
+
+/**
+ * lws_cgi_get_stdwsi: get wsi for stdin, stdout, or stderr
+ *
+ * \param wsi: parent wsi that has cgi
+ * \param ch: which of LWS_STDIN, LWS_STDOUT or LWS_STDERR
+ */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_cgi_get_stdwsi(struct lws *wsi, enum lws_enum_stdinouterr ch);
+
+#endif
+///@}
+

include/libwebsockets/lws-client.h

@@ -0,0 +1,413 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup client Client related functions
+ * ##Client releated functions
+ * \ingroup lwsapi
+ *
+ * */
+///@{
+
+/** enum lws_client_connect_ssl_connection_flags - flags that may be used
+ * with struct lws_client_connect_info ssl_connection member to control if
+ * and how SSL checks apply to the client connection being created
+ */
+
+enum lws_client_connect_ssl_connection_flags {
+	LCCSCF_USE_SSL 				= (1 << 0),
+	LCCSCF_ALLOW_SELFSIGNED			= (1 << 1),
+	LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK	= (1 << 2),
+	LCCSCF_ALLOW_EXPIRED			= (1 << 3),
+	LCCSCF_ALLOW_INSECURE			= (1 << 4),
+	LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM	= (1 << 5),
+	LCCSCF_H2_QUIRK_OVERFLOWS_TXCR		= (1 << 6),
+	LCCSCF_H2_AUTH_BEARER			= (1 << 7),
+	LCCSCF_H2_HEXIFY_AUTH_TOKEN		= (1 << 8),
+	LCCSCF_H2_MANUAL_RXFLOW			= (1 << 9),
+	LCCSCF_HTTP_MULTIPART_MIME		= (1 << 10),
+	LCCSCF_HTTP_X_WWW_FORM_URLENCODED	= (1 << 11),
+	LCCSCF_HTTP_NO_FOLLOW_REDIRECT		= (1 << 12),
+
+	LCCSCF_PIPELINE				= (1 << 16),
+		/**< Serialize / pipeline multiple client connections
+		 * on a single connection where possible.
+		 *
+		 * HTTP/1.0: possible if Keep-Alive: yes sent by server
+		 * HTTP/1.1: always possible... uses pipelining
+		 * HTTP/2:   always possible... uses parallel streams
+		 */
+	LCCSCF_MUXABLE_STREAM			= (1 << 17),
+	LCCSCF_H2_PRIOR_KNOWLEDGE		= (1 << 18),
+	LCCSCF_WAKE_SUSPEND__VALIDITY		= (1 << 19),
+	/* our validity checks are important enough to wake from suspend */
+	LCCSCF_PRIORITIZE_READS			= (1 << 20),
+	/**<
+	 * Normally lws balances reads and writes on all connections, so both
+	 * are possible even on busy connections, and we go around the event
+	 * loop more often to facilitate that, even if there is pending data.
+	 *
+	 * This flag indicates that you want to handle any pending reads on this
+	 * connection without yielding the service loop for anything else.  This
+	 * means you may block other connection processing in favour of incoming
+	 * data processing on this one if it receives back to back incoming rx.
+	 */
+	LCCSCF_SECSTREAM_CLIENT			= (1 << 21),
+	/**< used to mark client wsi as bound to secure stream */
+	LCCSCF_SECSTREAM_PROXY_LINK		= (1 << 22),
+	/**< client is a link between SS client and SS proxy */
+	LCCSCF_SECSTREAM_PROXY_ONWARD		= (1 << 23),
+	/**< client the SS proxy's onward connection */
+
+	LCCSCF_IP_LOW_LATENCY			= (1 << 24),
+	/**< set the "low delay" bit on the IP packets of this connection */
+	LCCSCF_IP_HIGH_THROUGHPUT		= (1 << 25),
+	/**< set the "high throughput" bit on the IP packets of this
+	 *   connection */
+	LCCSCF_IP_HIGH_RELIABILITY		= (1 << 26),
+	/**< set the "high reliability" bit on the IP packets of this
+	 *   connection */
+	LCCSCF_IP_LOW_COST			= (1 << 27),
+	/**< set the "minimize monetary cost" bit on the IP packets of this
+	 *   connection */
+	LCCSCF_CONMON				= (1 << 28),
+	/**< If LWS_WITH_CONMON enabled for build, keeps a copy of the
+	 * getaddrinfo results so they can be queried subsequently */
+	LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS	= (1 << 29),
+	/**< By default lws rejects https redirecting to http.  Set this
+	 * flag on the client connection to allow it. */
+	LCCSCF_CACHE_COOKIES			= (1 << 30),
+	/**< If built with -DLWS_WITH_CACHE_NSCOOKIEJAR, store and reapply
+	 * http cookies in a Netscape Cookie Jar on this connection */
+};
+
+/** struct lws_client_connect_info - parameters to connect with when using
+ *				    lws_client_connect_via_info() */
+
+struct lws_client_connect_info {
+	struct lws_context *context;
+	/**< lws context to create connection in */
+	const char *address;
+	/**< remote address to connect to */
+	int port;
+	/**< remote port to connect to */
+	int ssl_connection;
+	/**< 0, or a combination of LCCSCF_ flags */
+	const char *path;
+	/**< URI path. Prefix with + for a UNIX socket. (+@ for
+     * a Linux abstract-namespace socket) */
+	const char *host;
+	/**< content of host header */
+	const char *origin;
+	/**< content of origin header */
+	const char *protocol;
+	/**< list of ws protocols we could accept */
+	int ietf_version_or_minus_one;
+	/**< deprecated: currently leave at 0 or -1 */
+	void *userdata;
+	/**< if non-NULL, use this as wsi user_data instead of malloc it */
+	const void *client_exts;
+	/**< UNUSED... provide in info.extensions at context creation time */
+	const char *method;
+	/**< if non-NULL, do this http method instead of ws[s] upgrade.
+	 * use "GET" to be a simple http client connection.  "RAW" gets
+	 * you a connected socket that lws itself will leave alone once
+	 * connected. */
+	struct lws *parent_wsi;
+	/**< if another wsi is responsible for this connection, give it here.
+	 * this is used to make sure if the parent closes so do any
+	 * child connections first. */
+	const char *uri_replace_from;
+	/**< if non-NULL, when this string is found in URIs in
+	 * text/html content-encoding, it's replaced with uri_replace_to */
+	const char *uri_replace_to;
+	/**< see uri_replace_from */
+	struct lws_vhost *vhost;
+	/**< vhost to bind to (used to determine related SSL_CTX) */
+	struct lws **pwsi;
+	/**< if not NULL, store the new wsi here early in the connection
+	 * process.  Although we return the new wsi, the call to create the
+	 * client connection does progress the connection somewhat and may
+	 * meet an error that will result in the connection being scrubbed and
+	 * NULL returned.  While the wsi exists though, he may process a
+	 * callback like CLIENT_CONNECTION_ERROR with his wsi: this gives the
+	 * user callback a way to identify which wsi it is that faced the error
+	 * even before the new wsi is returned and even if ultimately no wsi
+	 * is returned.
+	 */
+	const char *iface;
+	/**< NULL to allow routing on any interface, or interface name or IP
+	 * to bind the socket to */
+	const char *local_protocol_name;
+	/**< NULL: .protocol is used both to select the local protocol handler
+	 *         to bind to and as the list of remote ws protocols we could
+	 *         accept.
+	 *   non-NULL: this protocol name is used to bind the connection to
+	 *             the local protocol handler.  .protocol is used for the
+	 *             list of remote ws protocols we could accept */
+	const char *alpn;
+	/**< NULL: allow lws default ALPN list, from vhost if present or from
+	 *       list of roles built into lws
+	 * non-NULL: require one from provided comma-separated list of alpn
+	 *           tokens
+	 */
+
+	struct lws_sequencer *seq;
+	/**< NULL, or an lws_seq_t that wants to be given messages about
+	 * this wsi's lifecycle as it connects, errors or closes.
+	 */
+
+	void *opaque_user_data;
+	/**< This data has no meaning to lws but is applied to the client wsi
+	 *   and can be retrieved by user code with lws_get_opaque_user_data().
+	 *   It's also provided with sequencer messages if the wsi is bound to
+	 *   an lws_seq_t.
+	 */
+
+	const lws_retry_bo_t *retry_and_idle_policy;
+	/**< optional retry and idle policy to apply to this connection.
+	 *   Currently only the idle parts are applied to the connection.
+	 */
+
+	int		manual_initial_tx_credit;
+	/**< if LCCSCF_H2_MANUAL_REFLOW is set, this becomes the initial tx
+	 * credit for the stream.
+	 */
+
+	uint8_t		sys_tls_client_cert;
+	/**< 0 means no client cert.  1+ means apply lws_system client cert 0+
+	 * to the client connection.
+	 */
+
+	uint8_t		priority;
+	/**< 0 means normal priority... otherwise sets the IP priority on
+	 * packets coming from this connection, from 1 - 7.  Setting 7
+	 * (network management priority) requires CAP_NET_ADMIN capability but
+	 * the others can be set by anyone.
+	 */
+
+#if defined(LWS_ROLE_MQTT)
+	const lws_mqtt_client_connect_param_t *mqtt_cp;
+#else
+	void		*mqtt_cp;
+#endif
+
+#if defined(LWS_WITH_SYS_FAULT_INJECTION)
+	lws_fi_ctx_t				fic;
+	/**< Attach external Fault Injection context to the client wsi,
+	 * hierarchy is wsi -> vhost -> context */
+#endif
+	/* for convenience, available when FI disabled in build */
+	const char				*fi_wsi_name;
+	/**< specific Fault Injection namespace name for wsi created for this
+	 * connection, allows targeting by "wsi=XXX/..." if you give XXX here.
+	 */
+
+	uint16_t				keep_warm_secs;
+	/**< 0 means 5s.  If the client connection to the endpoint becomes idle,
+	 * defer closing it for this many seconds in case another outgoing
+	 * connection to the same endpoint turns up.
+	 */
+
+	lws_log_cx_t				*log_cx;
+	/**< NULL to use lws_context log context, else a pointer to a log
+	 * context template to take a copy of for this wsi.  Used to isolate
+	 * wsi-specific logs into their own stream or file.
+	 */
+
+	/* Add new things just above here ---^
+	 * This is part of the ABI, don't needlessly break compatibility
+	 *
+	 * The below is to ensure later library versions with new
+	 * members added above will see 0 (default) even if the app
+	 * was not built against the newer headers.
+	 */
+
+	void *_unused[4]; /**< dummy */
+};
+
+/**
+ * lws_client_connect_via_info() - Connect to another websocket server
+ * \param ccinfo: pointer to lws_client_connect_info struct
+ *
+ *	This function creates a connection to a remote server using the
+ *	information provided in ccinfo.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_client_connect_via_info(const struct lws_client_connect_info *ccinfo);
+
+/**
+ * lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost
+ *
+ * \param info: client ssl related info
+ * \param vhost: which vhost to initialize client ssl operations on
+ *
+ * You only need to call this if you plan on using SSL client connections on
+ * the vhost.  For non-SSL client connections, it's not necessary to call this.
+ *
+ * The following members of info are used during the call
+ *
+ *	 - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,
+ *	     otherwise the call does nothing
+ *	 - provided_client_ssl_ctx must be NULL to get a generated client
+ *	     ssl context, otherwise you can pass a prepared one in by setting it
+ *	 - ssl_cipher_list may be NULL or set to the client valid cipher list
+ *	 - ssl_ca_filepath may be NULL or client cert filepath
+ *	 - ssl_cert_filepath may be NULL or client cert filepath
+ *	 - ssl_private_key_filepath may be NULL or client cert private key
+ *
+ * You must create your vhost explicitly if you want to use this, so you have
+ * a pointer to the vhost.  Create the context first with the option flag
+ * LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with
+ * the same info struct.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_init_vhost_client_ssl(const struct lws_context_creation_info *info,
+			  struct lws_vhost *vhost);
+/**
+ * lws_http_client_read() - consume waiting received http client data
+ *
+ * \param wsi: client connection
+ * \param buf: pointer to buffer pointer - fill with pointer to your buffer
+ * \param len: pointer to chunk length - fill with max length of buffer
+ *
+ * This is called when the user code is notified client http data has arrived.
+ * The user code may choose to delay calling it to consume the data, for example
+ * waiting until an onward connection is writeable.
+ *
+ * For non-chunked connections, up to len bytes of buf are filled with the
+ * received content.  len is set to the actual amount filled before return.
+ *
+ * For chunked connections, the linear buffer content contains the chunking
+ * headers and it cannot be passed in one lump.  Instead, this function will
+ * call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the
+ * chunk start and len set to the chunk length.  There will be as many calls
+ * as there are chunks or partial chunks in the buffer.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_client_read(struct lws *wsi, char **buf, int *len);
+
+/**
+ * lws_http_client_http_response() - get last HTTP response code
+ *
+ * \param wsi: client connection
+ *
+ * Returns the last server response code, eg, 200 for client http connections.
+ * If there is no valid response, it will return 0.
+ *
+ * You should capture this during the LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP
+ * callback, because after that the memory reserved for storing the related
+ * headers is freed and this value is lost.
+ */
+LWS_VISIBLE LWS_EXTERN unsigned int
+lws_http_client_http_response(struct lws *wsi);
+
+/**
+ * lws_tls_client_vhost_extra_cert_mem() - add more certs to vh client tls ctx
+ *
+ * \param vh: the vhost to give more client certs to
+ * \param der: pointer to der format additional cert
+ * \param der_len: size in bytes of der
+ *
+ * After the vhost is created with one cert for client verification, you
+ * can add additional, eg, intermediate, certs to the client tls context
+ * of the vhost, for use with validating the incoming server cert(s).
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_tls_client_vhost_extra_cert_mem(struct lws_vhost *vh,
+		const uint8_t *der, size_t der_len);
+
+/**
+ * lws_client_http_body_pending() - control if client connection needs to send body
+ *
+ * \param wsi: client connection
+ * \param something_left_to_send: nonzero if need to send more body, 0 (default)
+ * 				if nothing more to send
+ *
+ * If you will send payload data with your HTTP client connection, eg, for POST,
+ * when you set the related http headers in
+ * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call
+ * this API with something_left_to_send nonzero, and call
+ * lws_callback_on_writable(wsi);
+ *
+ * After sending the headers, lws will call your callback with
+ * LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable.  You can send the
+ * next part of the http body payload, calling lws_callback_on_writable(wsi);
+ * if there is more to come, or lws_client_http_body_pending(wsi, 0); to
+ * let lws know the last part is sent and the connection can move on.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_client_http_body_pending(struct lws *wsi, int something_left_to_send);
+
+/**
+ * lws_client_http_multipart() - issue appropriate multipart header or trailer
+ *
+ * \param wsi: client connection
+ * \param name: multipart header name field, or NULL if end of multipart
+ * \param filename: multipart header filename field, or NULL if none
+ * \param content_type: multipart header content-type part, or NULL if none
+ * \param p: pointer to position in buffer
+ * \param end: end of buffer
+ *
+ * This issues a multipart mime boundary, or terminator if name = NULL.
+ *
+ * Returns 0 if OK or nonzero if couldn't fit in buffer
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_client_http_multipart(struct lws *wsi, const char *name,
+			  const char *filename, const char *content_type,
+			  char **p, char *end);
+
+/**
+ * lws_http_basic_auth_gen() - helper to encode client basic auth string
+ *
+ * \param user: user name
+ * \param pw: password
+ * \param buf: where to store base64 result
+ * \param len: max usable size of buf
+ *
+ * Encodes a username and password in Basic Auth format for use with the
+ * Authorization header.  On return, buf is filled with something like
+ * "Basic QWxhZGRpbjpPcGVuU2VzYW1l".
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_basic_auth_gen(const char *user, const char *pw, char *buf, size_t len);
+
+/**
+ * lws_tls_session_is_reused() - returns nonzero if tls session was cached
+ *
+ * \param wsi: the wsi
+ *
+ * Returns zero if the tls session is fresh, else nonzero if the tls session was
+ * taken from the cache.  If lws is built with LWS_WITH_TLS_SESSIONS and the vhost
+ * was created with the option LWS_SERVER_OPTION_ENABLE_TLS_SESSION_CACHE, then
+ * on full tls session establishment of a client connection, the session is added
+ * to the tls cache.
+ *
+ * This lets you find out if your session was new (0) or from the cache (nonzero),
+ * it'a mainly useful for stats and testing.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_tls_session_is_reused(struct lws *wsi);
+
+///@}

include/libwebsockets/lws-conmon.h

@@ -0,0 +1,155 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup conmon Connection Latency information
+ * ## Connection Latency information
+ *
+ * When LWS_WITH_CONMON is enabled at build, collects detailed statistics
+ * about the client connection setup latency, available to the connection
+ * itself
+ */
+///@{
+
+/* enough for 4191s, or just over an hour */
+typedef uint32_t lws_conmon_interval_us_t;
+
+/*
+ * Connection latency information... note that not all wsi actually make
+ * connections, for example h2 streams after the initial one will have 0
+ * for everything except ciu_txn_resp.
+ *
+ * If represented in JSON, it should look like this
+ *
+ *     {
+ *        "peer": "46.105.127.147",
+ *        "dns_us": 1234,
+ *        "dns_disp": 1,
+ *        "sockconn_us": 1234,
+ *        "tls_us": 1234,
+ *        "txn_resp_us": 1234,
+ *        "dns":["46.105.127.147", "2001:41d0:2:ee93::1"],
+ *        "prot_specific": {
+ *        	"protocol": "http",
+ *        	"resp": 200
+ *        }
+ *      }
+ *
+ * The indexes in "dns_disp" are declared in lws_conmon_dns_disposition_t
+ * below.
+ *
+ * "prot_specific" may not be present if the protocol doesn't have anything
+ * to report or is not supported.
+ */
+
+typedef enum lws_conmon_pcol {
+	LWSCONMON_PCOL_NONE,
+	LWSCONMON_PCOL_HTTP, /* .protocol_specific.http is valid */
+} lws_conmon_pcol_t;
+
+typedef enum lws_conmon_dns_disposition {
+	LWSCONMON_DNS_NONE,
+	/**< did not attempt DNS */
+	LWSCONMON_DNS_OK				= 1,
+	/**< DNS lookup did give results */
+	LWSCONMON_DNS_SERVER_UNREACHABLE		= 2,
+	/**< DNS server was not reachable */
+	LWSCONMON_DNS_NO_RESULT				= 3
+	/**< DNS server replied but nothing usable */
+} lws_conmon_dns_disposition_t;
+
+struct lws_conmon {
+	lws_sockaddr46				peer46;
+	/**< The peer we actually connected to, if any.  .peer46.sa4.sa_family
+	 * is either 0 if invalid, or the AF_ */
+
+	union {
+		struct {
+			int	response;
+			/**< h1 http response code */
+		} http;
+	} protocol_specific;
+	/**< possibly-present protocol-specific additional information.  This
+	 * is only valid for the first transaction after connection and does
+	 * not capture results for persistent or muxed connections like ws
+	 * messages, mqtt messages, or h2 streams */
+
+	struct addrinfo				*dns_results_copy;
+	/**< NULL, or Allocated copy of dns results, owned by this object and
+	 * freed when object destroyed.
+	 * Only set if client flag LCCSCF_CONMON applied  */
+
+	lws_conmon_interval_us_t		ciu_dns;
+	/**< 0, or if a socket connection, us taken to acquire this DNS response
+	 *
+	 */
+	lws_conmon_interval_us_t		ciu_sockconn;
+	/**< 0, or if connection-based, the us interval between the socket
+	 * connect() attempt that succeeded, and the connection setup */
+	lws_conmon_interval_us_t		ciu_tls;
+	/**< 0 if no tls, or us taken to establish the tls tunnel */
+	lws_conmon_interval_us_t		ciu_txn_resp;
+	/**< 0, or if the protocol supports transactions, the interval between
+	 * sending the initial transaction request and starting to receive the
+	 * response */
+
+	lws_conmon_pcol_t			pcol;
+	/**< indicates which extra protocol_specific info member is valid,
+	 *   if any */
+
+	lws_conmon_dns_disposition_t		dns_disposition;
+	/**< indicates general disposition of DNS request */
+};
+
+/**
+ * lws_conmon_wsi_take() - create a connection latency object from client wsi
+ *
+ * \param context: lws wsi
+ * \param dest: conmon struct to fill
+ *
+ * Copies wsi conmon data into the caller's struct.  Passes ownership of
+ * any allocations in the addrinfo list to the caller, lws will not delete that
+ * any more on wsi close after this call.  The caller must call
+ * lws_conmon_release() on the struct to destroy any addrinfo in the struct
+ * that is prepared by this eventually but it can defer it as long as it wants.
+ *
+ * Other than the addrinfo list, the contents of the returned object are
+ * completely selfcontained and don't point outside of the object itself, ie,
+ * everything else in there remains in scope while the object itself does.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_conmon_wsi_take(struct lws *wsi, struct lws_conmon *dest);
+
+/**
+ * lws_conmon_release() - free any allocations in the conmon struct
+ *
+ * \param conmon: pointer to conmon struct
+ *
+ * Destroys any allocations in the conmon struct so it can go out of scope.
+ * It doesn't free \p dest itself, it's designed to clean out a struct that
+ * is on the stack or embedded in another object.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_conmon_release(struct lws_conmon *conmon);
+
+///@}

include/libwebsockets/lws-context-vhost.h

@@ -0,0 +1,1332 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup context-and-vhost context and vhost related functions
+ * ##Context and Vhost releated functions
+ * \ingroup lwsapi
+ *
+ *
+ *  LWS requires that there is one context, in which you may define multiple
+ *  vhosts.  Each vhost is a virtual host, with either its own listen port
+ *  or sharing an existing one.  Each vhost has its own SSL context that can
+ *  be set up individually or left disabled.
+ *
+ *  If you don't care about multiple "site" support, you can ignore it and
+ *  lws will create a single default vhost at context creation time.
+ */
+///@{
+
+/*
+ * NOTE: These public enums are part of the abi.  If you want to add one,
+ * add it at where specified so existing users are unaffected.
+ */
+
+
+#define LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT	 ((1ll << 1) | \
+								  (1ll << 12))
+	/**< (VH) Don't allow the connection unless the client has a
+	 * client cert that we recognize; provides
+	 * LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT */
+#define LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME		  (1ll << 2)
+	/**< (CTX) Don't try to get the server's hostname */
+#define LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT		 ((1ll << 3) | \
+								  (1ll << 12))
+	/**< (VH) Allow non-SSL (plaintext) connections on the same
+	 * port as SSL is listening.  If combined with
+	 * LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS it will try to
+	 * force http connections on an https listener (eg, http://x.com:443) to
+	 * redirect to an explicit https connection (eg, https://x.com)
+	 */
+#define LWS_SERVER_OPTION_LIBEV					 (1ll << 4)
+	/**< (CTX) Use libev event loop */
+#define LWS_SERVER_OPTION_DISABLE_IPV6				 (1ll << 5)
+	/**< (VH) Disable IPV6 support */
+#define LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS			 (1ll << 6)
+	/**< (VH) Don't load OS CA certs, you will need to load your
+	 * own CA cert(s) */
+#define LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED		 (1ll << 7)
+	/**< (VH) Accept connections with no valid Cert (eg, selfsigned) */
+#define LWS_SERVER_OPTION_VALIDATE_UTF8				 (1ll << 8)
+	/**< (VH) Check UT-8 correctness */
+#define LWS_SERVER_OPTION_SSL_ECDH				 ((1ll << 9) | \
+								  (1ll << 12))
+	/**< (VH)  initialize ECDH ciphers */
+#define LWS_SERVER_OPTION_LIBUV					(1ll << 10)
+	/**< (CTX)  Use libuv event loop */
+#define LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS		((1ll << 11) |\
+								 (1ll << 12))
+	/**< (VH) Use an http redirect to force the client to ask for https.
+	 * Notice if your http server issues the STS header and the client has
+	 * ever seen that, the client will fail the http connection before it
+	 * can actually do the redirect.
+	 *
+	 * Combine with LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS to handle, eg,
+	 * http://x.com:443 -> https://x.com
+	 *
+	 * (deprecated: use mount redirection) */
+#define LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT			 (1ll << 12)
+	/**< (CTX) Initialize the SSL library at all */
+#define LWS_SERVER_OPTION_EXPLICIT_VHOSTS			 (1ll << 13)
+	/**< (CTX) Only create the context when calling context
+	 * create api, implies user code will create its own vhosts */
+#define LWS_SERVER_OPTION_UNIX_SOCK				 (1ll << 14)
+	/**< (VH) Use Unix socket */
+#define LWS_SERVER_OPTION_STS					 (1ll << 15)
+	/**< (VH) Send Strict Transport Security header, making
+	 * clients subsequently go to https even if user asked for http */
+#define LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY			 (1ll << 16)
+	/**< (VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect */
+#define LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE			 (1ll << 17)
+	/**< (VH) if set, only ipv6 allowed on the vhost */
+#define LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN		 (1ll << 18)
+	/**< (CTX) Libuv only: Do not spin on SIGSEGV / SIGFPE.  A segfault
+	 * normally makes the lib spin so you can attach a debugger to it
+	 * even if it happened without a debugger in place.  You can disable
+	 * that by giving this option.
+	 */
+#define LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN			 (1ll << 19)
+	/**< For backwards-compatibility reasons, by default
+	 * lws prepends "http://" to the origin you give in the client
+	 * connection info struct.  If you give this flag when you create
+	 * the context, only the string you give in the client connect
+	 * info for .origin (if any) will be used directly.
+	 */
+#define LWS_SERVER_OPTION_FALLBACK_TO_RAW /* use below name */	 (1ll << 20)
+#define LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 20)
+	/**< (VH) if invalid http is coming in the first line, then abandon
+	 * trying to treat the connection as http, and belatedly apply the
+	 * .listen_accept_role / .listen_accept_protocol info struct members to
+	 * the connection.  If they are NULL, for backwards-compatibility the
+	 * connection is bound to "raw-skt" role, and in order of priority:
+	 * 1) the vh protocol with a pvo named "raw", 2) the vh protocol with a
+	 * pvo named "default", or 3) protocols[0].
+	 *
+	 * Must be combined with LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT
+	 * to work with a socket listening with tls.
+	 */
+
+#define LWS_SERVER_OPTION_LIBEVENT				(1ll << 21)
+	/**< (CTX) Use libevent event loop */
+
+#define LWS_SERVER_OPTION_ONLY_RAW /* Use below name instead */	(1ll << 22)
+#define LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG	(1ll << 22)
+	/**< (VH) All connections to this vhost / port are bound to the
+	 * role and protocol given in .listen_accept_role /
+	 * .listen_accept_protocol.
+	 *
+	 * If those explicit user-controlled names are NULL, for backwards-
+	 * compatibility the connection is bound to "raw-skt" role, and in order
+	 * of priority: 1) the vh protocol with a pvo named "raw", 2) the vh
+	 * protocol with a pvo named "default", or 3) protocols[0].
+	 *
+	 * It's much preferred to specify the role + protocol using the
+	 * .listen_accept_role and .listen_accept_protocol in the info struct.
+	 */
+#define LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE			(1ll << 23)
+	/**< (VH) Set to allow multiple listen sockets on one interface +
+	 * address + port.  The default is to strictly allow only one
+	 * listen socket at a time.  This is automatically selected if you
+	 * have multiple service threads.  Linux only.
+	 */
+#define LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX			(1ll << 24)
+	/**< (VH) Force setting up the vhost SSL_CTX, even though the user
+	 * code doesn't explicitly provide a cert in the info struct.  It
+	 * implies the user code is going to provide a cert at the
+	 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback, which
+	 * provides the vhost SSL_CTX * in the user parameter.
+	 */
+#define LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT			(1ll << 25)
+	/**< (VH) You probably don't want this.  It forces this vhost to not
+	 * call LWS_CALLBACK_PROTOCOL_INIT on its protocols.  It's used in the
+	 * special case of a temporary vhost bound to a single protocol.
+	 */
+#define LWS_SERVER_OPTION_IGNORE_MISSING_CERT			(1ll << 26)
+	/**< (VH) Don't fail if the vhost TLS cert or key are missing, just
+	 * continue.  The vhost won't be able to serve anything, but if for
+	 * example the ACME plugin was configured to fetch a cert, this lets
+	 * you bootstrap your vhost from having no cert to start with.
+	 */
+#define LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK		(1ll << 27)
+	/**< (VH) On this vhost, if the connection is being upgraded, insist
+	 * that there's a Host: header and that the contents match the vhost
+	 * name + port (443 / 80 are assumed if no :port given based on if the
+	 * connection is using TLS).
+	 *
+	 * By default, without this flag, on upgrade lws just checks that the
+	 * Host: header was given without checking the contents... this is to
+	 * allow lax hostname mappings like localhost / 127.0.0.1, and CNAME
+	 * mappings like www.mysite.com / mysite.com
+	 */
+#define LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE (1ll << 28)
+	/**< (VH) Send lws default HTTP headers recommended by Mozilla
+	 * Observatory for security.  This is a helper option that sends canned
+	 * headers on each http response enabling a VERY strict Content Security
+	 * Policy.  The policy is so strict, for example it won't let the page
+	 * run its own inline JS nor show images or take CSS from a different
+	 * server.  In many cases your JS only comes from your server as do the
+	 * image sources and CSS, so that is what you want... attackers hoping
+	 * to inject JS into your DOM are completely out of luck since even if
+	 * they succeed, it will be rejected for execution by the browser
+	 * according to the strict CSP.  In other cases you have to deviate from
+	 * the complete strictness, in which case don't use this flag: use the
+	 * .headers member in the vhost init described in struct
+	 * lws_context_creation_info instead to send the adapted headers
+	 * yourself.
+	 */
+
+#define LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER		 (1ll << 29)
+	/**< (VH) If you really want to allow HTTP connections on a tls
+	 * listener, you can do it with this combined with
+	 * LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT.  But this is allowing
+	 * accidental loss of the security assurances provided by tls depending
+	 * on the client using http when he meant https... it's not
+	 * recommended.
+	 */
+#define LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND		 (1ll << 30)
+	/**< (VH) When instantiating a new vhost and the specified port is
+	 * already in use, a null value shall be return to signal the error.
+	 */
+
+#define LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW	 (1ll << 31)
+	/**< (VH) Indicates the connections using this vhost should ignore
+	 * h2 WINDOW_UPDATE from broken peers and fix them up */
+
+#define LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL		 (1ll << 32)
+	/**< (VH) Tell the vhost to treat half-closed remote clients as
+	 * entered into an immortal (ie, not subject to normal timeouts) long
+	 * poll mode.
+	 */
+
+#define LWS_SERVER_OPTION_GLIB					 (1ll << 33)
+	/**< (CTX) Use glib event loop */
+
+#define LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE			 (1ll << 34)
+	/**< (VH) Tell the vhost to treat plain text http connections as
+	 * H2 with prior knowledge (no upgrade request involved)
+	 */
+
+#define LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES			 (1ll << 35)
+	/**< (CTX) Disable lws_system state, eg, because we are a secure streams
+	 * proxy client that is not trying to track system state by itself. */
+
+#define LWS_SERVER_OPTION_SS_PROXY				 (1ll << 36)
+	/**< (VH) We are being a SS Proxy listen socket for the vhost */
+
+#define LWS_SERVER_OPTION_SDEVENT			 	 (1ll << 37)
+	/**< (CTX) Use sd-event loop */
+
+#define LWS_SERVER_OPTION_ULOOP					 (1ll << 38)
+	/**< (CTX) Use libubox / uloop event loop */
+
+#define LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE		 (1ll << 39)
+	/**< (VHOST) Disallow use of client tls caching (on by default) */
+
+
+	/****** add new things just above ---^ ******/
+
+
+#define lws_check_opt(c, f) ((((uint64_t)c) & ((uint64_t)f)) == ((uint64_t)f))
+
+struct lws_plat_file_ops;
+struct lws_ss_policy;
+struct lws_ss_plugin;
+struct lws_metric_policy;
+
+typedef int (*lws_context_ready_cb_t)(struct lws_context *context);
+
+typedef int (*lws_peer_limits_notify_t)(struct lws_context *ctx,
+					lws_sockfd_type sockfd,
+					lws_sockaddr46 *sa46);
+
+/** struct lws_context_creation_info - parameters to create context and /or vhost with
+ *
+ * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
+ * is not given, then for backwards compatibility one vhost is created at
+ * context-creation time using the info from this struct.
+ *
+ * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
+ * at the same time as the context, they are expected to be created afterwards.
+ */
+struct lws_context_creation_info {
+#if defined(LWS_WITH_NETWORK)
+	const char *iface;
+	/**< VHOST: NULL to bind the listen socket to all interfaces, or the
+	 * interface name, eg, "eth2"
+	 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
+	 * the pathname of a UNIX domain socket. you can use the UNIX domain
+	 * sockets in abstract namespace, by prepending an at symbol to the
+	 * socket name. */
+	const struct lws_protocols *protocols;
+	/**< VHOST: Array of structures listing supported protocols and a
+	 * protocol-specific callback for each one.  The list is ended with an
+	 * entry that has a NULL callback pointer.  SEE ALSO .pprotocols below,
+	 * which gives an alternative way to provide an array of pointers to
+	 * protocol structs. */
+#if defined(LWS_ROLE_WS)
+	const struct lws_extension *extensions;
+	/**< VHOST: NULL or array of lws_extension structs listing the
+	 * extensions this context supports. */
+#endif
+#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2)
+	const struct lws_token_limits *token_limits;
+	/**< CONTEXT: NULL or struct lws_token_limits pointer which is
+	 * initialized with a token length limit for each possible WSI_TOKEN_ */
+	const char *http_proxy_address;
+	/**< VHOST: If non-NULL, attempts to proxy via the given address.
+	 * If proxy auth is required, use format
+	 * "username:password\@server:port" */
+	const struct lws_protocol_vhost_options *headers;
+		/**< VHOST: pointer to optional linked list of per-vhost
+		 * canned headers that are added to server responses */
+
+	const struct lws_protocol_vhost_options *reject_service_keywords;
+	/**< CONTEXT: Optional list of keywords and rejection codes + text.
+	 *
+	 * The keywords are checked for existing in the user agent string.
+	 *
+	 * Eg, "badrobot" "404 Not Found"
+	 */
+	const struct lws_protocol_vhost_options *pvo;
+	/**< VHOST: pointer to optional linked list of per-vhost
+	 * options made accessible to protocols */
+	const char *log_filepath;
+	/**< VHOST: filepath to append logs to... this is opened before
+	 *		any dropping of initial privileges */
+	const struct lws_http_mount *mounts;
+	/**< VHOST: optional linked list of mounts for this vhost */
+	const char *server_string;
+	/**< CONTEXT: string used in HTTP headers to identify server
+	 * software, if NULL, "libwebsockets". */
+
+	const char *error_document_404;
+	/**< VHOST: If non-NULL, when asked to serve a non-existent file,
+	 *          lws attempts to server this url path instead.  Eg,
+	 *          "/404.html" */
+	int port;
+	/**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress
+	 * listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are
+	 * writing a server but you are using \ref sock-adopt instead of the
+	 * built-in listener.
+	 *
+	 * You can also set port to 0, in which case the kernel will pick
+	 * a random port that is not already in use.  You can find out what
+	 * port the vhost is listening on using lws_get_vhost_listen_port() */
+
+	unsigned int http_proxy_port;
+	/**< VHOST: If http_proxy_address was non-NULL, uses this port */
+	unsigned int max_http_header_data2;
+	/**< CONTEXT: if max_http_header_data is 0 and this
+	 * is nonzero, this will be used in place of the default.  It's
+	 * like this for compatibility with the original short version,
+	 * this is unsigned int length. */
+	unsigned int max_http_header_pool2;
+	/**< CONTEXT: if max_http_header_pool is 0 and this
+	 * is nonzero, this will be used in place of the default.  It's
+	 * like this for compatibility with the original short version:
+	 * this is unsigned int length. */
+
+	int keepalive_timeout;
+	/**< VHOST: (default = 0 = 5s, 31s for http/2) seconds to allow remote
+	 * client to hold on to an idle HTTP/1.1 connection.  Timeout lifetime
+	 * applied to idle h2 network connections */
+	uint32_t	http2_settings[7];
+	/**< VHOST:  if http2_settings[0] is nonzero, the values given in
+	 *	      http2_settings[1]..[6] are used instead of the lws
+	 *	      platform default values.
+	 *	      Just leave all at 0 if you don't care.
+	 */
+
+	unsigned short max_http_header_data;
+	/**< CONTEXT: The max amount of header payload that can be handled
+	 * in an http request (unrecognized header payload is dropped) */
+	unsigned short max_http_header_pool;
+	/**< CONTEXT: The max number of connections with http headers that
+	 * can be processed simultaneously (the corresponding memory is
+	 * allocated and deallocated dynamically as needed).  If the pool is
+	 * fully busy new incoming connections must wait for accept until one
+	 * becomes free. 0 = allow as many ah as number of availble fds for
+	 * the process */
+
+#endif
+
+#if defined(LWS_WITH_TLS)
+	const char *ssl_private_key_password;
+	/**< VHOST: NULL or the passphrase needed for the private key. (For
+	 * backwards compatibility, this can also be used to pass the client
+	 * cert passphrase when setting up a vhost client SSL context, but it is
+	 * preferred to use .client_ssl_private_key_password for that.) */
+	const char *ssl_cert_filepath;
+	/**< VHOST: If libwebsockets was compiled to use ssl, and you want
+	 * to listen using SSL, set to the filepath to fetch the
+	 * server cert from, otherwise NULL for unencrypted.  (For backwards
+	 * compatibility, this can also be used to pass the client certificate
+	 * when setting up a vhost client SSL context, but it is preferred to
+	 * use .client_ssl_cert_filepath for that.)
+	 *
+	 * Notice you can alternatively set a single DER or PEM from a memory
+	 * buffer as the vhost tls cert using \p server_ssl_cert_mem and
+	 * \p server_ssl_cert_mem_len.
+	 */
+	const char *ssl_private_key_filepath;
+	/**<  VHOST: filepath to private key if wanting SSL mode;
+	 * if this is set to NULL but ssl_cert_filepath is set, the
+	 * OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
+	 * to allow setting of the private key directly via openSSL
+	 * library calls.   (For backwards compatibility, this can also be used
+	 * to pass the client cert private key filepath when setting up a
+	 * vhost client SSL context, but it is preferred to use
+	 * .client_ssl_private_key_filepath for that.)
+	 *
+	 * Notice you can alternatively set a DER or PEM private key from a
+	 * memory buffer as the vhost tls private key using
+	 * \p server_ssl_private_key_mem and \p server_ssl_private_key_mem_len.
+	 */
+	const char *ssl_ca_filepath;
+	/**< VHOST: CA certificate filepath or NULL.  (For backwards
+	 * compatibility, this can also be used to pass the client CA
+	 * filepath when setting up a vhost client SSL context,
+	 * but it is preferred to use .client_ssl_ca_filepath for that.)
+	 *
+	 * Notice you can alternatively set a DER or PEM CA cert from a memory
+	 * buffer using \p server_ssl_ca_mem and \p server_ssl_ca_mem_len.
+	 */
+	const char *ssl_cipher_list;
+	/**< VHOST: List of valid ciphers to use ON TLS1.2 AND LOWER ONLY (eg,
+	 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
+	 * or you can leave it as NULL to get "DEFAULT" (For backwards
+	 * compatibility, this can also be used to pass the client cipher
+	 * list when setting up a vhost client SSL context,
+	 * but it is preferred to use .client_ssl_cipher_list for that.)
+	 * SEE .tls1_3_plus_cipher_list and .client_tls_1_3_plus_cipher_list
+	 * for the equivalent for tls1.3.
+	 */
+	const char *ecdh_curve;
+	/**< VHOST: if NULL, defaults to initializing server with
+	 *   "prime256v1" */
+	const char *tls1_3_plus_cipher_list;
+	/**< VHOST: List of valid ciphers to use for incoming server connections
+	 * ON TLS1.3 AND ABOVE (eg, "TLS_CHACHA20_POLY1305_SHA256" on this vhost
+	 * or you can leave it as NULL to get "DEFAULT".
+	 * SEE .client_tls_1_3_plus_cipher_list to do the same on the vhost
+	 * client SSL_CTX.
+	 */
+
+	const void *server_ssl_cert_mem;
+	/**< VHOST: Alternative for \p ssl_cert_filepath that allows setting
+	 * from memory instead of from a file.  At most one of
+	 * \p ssl_cert_filepath or \p server_ssl_cert_mem should be non-NULL. */
+	const void *server_ssl_private_key_mem;
+	/**<  VHOST: Alternative for \p ssl_private_key_filepath allowing
+	 * init from a private key in memory instead of a file.  At most one
+	 * of \p ssl_private_key_filepath or \p server_ssl_private_key_mem
+	 * should be non-NULL. */
+	const void *server_ssl_ca_mem;
+	/**< VHOST: Alternative for \p ssl_ca_filepath allowing
+	 * init from a CA cert in memory instead of a file.  At most one
+	 * of \p ssl_ca_filepath or \p server_ssl_ca_mem should be non-NULL. */
+
+	long ssl_options_set;
+	/**< VHOST: Any bits set here will be set as server SSL options */
+	long ssl_options_clear;
+	/**< VHOST: Any bits set here will be cleared as server SSL options */
+	int simultaneous_ssl_restriction;
+	/**< CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions
+	 * possible.*/
+	int simultaneous_ssl_handshake_restriction;
+	/**< CONTEXT: 0 (no limit) or limit of simultaneous SSL handshakes ongoing */
+	int ssl_info_event_mask;
+	/**< VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO
+	 * callback for connections on this vhost.  The mask values are of
+	 * the form SSL_CB_ALERT, defined in openssl/ssl.h.  The default of
+	 * 0 means no info events will be reported.
+	 */
+	unsigned int server_ssl_cert_mem_len;
+	/**< VHOST: Server SSL context init: length of server_ssl_cert_mem in
+	 * bytes */
+	unsigned int server_ssl_private_key_mem_len;
+	/**< VHOST: length of \p server_ssl_private_key_mem in memory */
+	unsigned int server_ssl_ca_mem_len;
+	/**< VHOST: length of \p server_ssl_ca_mem in memory */
+
+	const char *alpn;
+	/**< CONTEXT: If non-NULL, default list of advertised alpn, comma-
+	 *	      separated
+	 *
+	 *     VHOST: If non-NULL, per-vhost list of advertised alpn, comma-
+	 *	      separated
+	 */
+
+
+#if defined(LWS_WITH_CLIENT)
+	const char *client_ssl_private_key_password;
+	/**< VHOST: Client SSL context init: NULL or the passphrase needed
+	 * for the private key */
+	const char *client_ssl_cert_filepath;
+	/**< VHOST: Client SSL context init: The certificate the client
+	 * should present to the peer on connection */
+	const void *client_ssl_cert_mem;
+	/**< VHOST: Client SSL context init: client certificate memory buffer or
+	 * NULL... use this to load client cert from memory instead of file */
+	unsigned int client_ssl_cert_mem_len;
+	/**< VHOST: Client SSL context init: length of client_ssl_cert_mem in
+	 * bytes */
+	const char *client_ssl_private_key_filepath;
+	/**<  VHOST: Client SSL context init: filepath to client private key
+	 * if this is set to NULL but client_ssl_cert_filepath is set, you
+	 * can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS
+	 * callback of protocols[0] to allow setting of the private key directly
+	 * via tls library calls */
+	const void *client_ssl_key_mem;
+	/**< VHOST: Client SSL context init: client key memory buffer or
+	 * NULL... use this to load client key from memory instead of file */
+	const char *client_ssl_ca_filepath;
+	/**< VHOST: Client SSL context init: CA certificate filepath or NULL */
+	const void *client_ssl_ca_mem;
+	/**< VHOST: Client SSL context init: CA certificate memory buffer or
+	 * NULL... use this to load CA cert from memory instead of file */
+
+	const char *client_ssl_cipher_list;
+	/**< VHOST: Client SSL context init: List of valid ciphers to use (eg,
+	* "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
+	* or you can leave it as NULL to get "DEFAULT" */
+	const char *client_tls_1_3_plus_cipher_list;
+	/**< VHOST: List of valid ciphers to use for outgoing client connections
+	 * ON TLS1.3 AND ABOVE on this vhost (eg,
+	 * "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get
+	 * "DEFAULT".
+	 */
+
+	long ssl_client_options_set;
+	/**< VHOST: Any bits set here will be set as CLIENT SSL options */
+	long ssl_client_options_clear;
+	/**< VHOST: Any bits set here will be cleared as CLIENT SSL options */
+
+
+	unsigned int client_ssl_ca_mem_len;
+	/**< VHOST: Client SSL context init: length of client_ssl_ca_mem in
+	 * bytes */
+	unsigned int client_ssl_key_mem_len;
+	/**< VHOST: Client SSL context init: length of client_ssl_key_mem in
+	 * bytes */
+
+#endif
+
+#if !defined(LWS_WITH_MBEDTLS)
+	SSL_CTX *provided_client_ssl_ctx;
+	/**< CONTEXT: If non-null, swap out libwebsockets ssl
+	  * implementation for the one provided by provided_ssl_ctx.
+	  * Libwebsockets no longer is responsible for freeing the context
+	  * if this option is selected. */
+#else /* WITH_MBEDTLS */
+	const char *mbedtls_client_preload_filepath;
+	/**< CONTEXT: If NULL, no effect.  Otherwise it should point to a
+	 * filepath where every created client SSL_CTX is preloaded from the
+	 * system trust bundle.
+	 *
+	 * This sets a processwide variable that affects all contexts.
+	 *
+	 * Requires that the mbedtls provides mbedtls_x509_crt_parse_file(),
+	 * else disabled.
+	 */
+#endif
+#endif
+
+	int ka_time;
+	/**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive
+	 * timeout to all libwebsocket sockets, client or server */
+	int ka_probes;
+	/**< CONTEXT: if ka_time was nonzero, after the timeout expires how many
+	 * times to try to get a response from the peer before giving up
+	 * and killing the connection */
+	int ka_interval;
+	/**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
+	 * attempt */
+	unsigned int timeout_secs;
+	/**< VHOST: various processes involving network roundtrips in the
+	 * library are protected from hanging forever by timeouts.  If
+	 * nonzero, this member lets you set the timeout used in seconds.
+	 * Otherwise a default timeout is used. */
+	unsigned int connect_timeout_secs;
+	/**< VHOST: client connections have this long to find a working server
+	 * from the DNS results, or the whole connection times out.  If zero,
+	 * a default timeout is used */
+	int bind_iface;
+	/**< VHOST: nonzero to strictly bind sockets to the interface name in
+	 * .iface (eg, "eth2"), using SO_BIND_TO_DEVICE.
+	 *
+	 * Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW
+	 * capability.
+	 *
+	 * Notice that common things like access network interface IP from
+	 * your local machine use your lo / loopback interface and will be
+	 * disallowed by this.
+	 */
+	unsigned int timeout_secs_ah_idle;
+	/**< VHOST: seconds to allow a client to hold an ah without using it.
+	 * 0 defaults to 10s. */
+#endif /* WITH_NETWORK */
+
+#if defined(LWS_WITH_TLS_SESSIONS)
+	uint32_t			tls_session_timeout;
+	/**< VHOST: seconds until timeout/ttl for newly created sessions.
+	 * 0 means default timeout (defined per protocol, usually 300s). */
+	uint32_t			tls_session_cache_max;
+	/**< VHOST: 0 for default limit of 10, or the maximum number of
+	 * client tls sessions we are willing to cache */
+#endif
+
+	gid_t gid;
+	/**< CONTEXT: group id to change to after setting listen socket,
+	 *   or -1. See also .username below. */
+	uid_t uid;
+	/**< CONTEXT: user id to change to after setting listen socket,
+	 *   or -1.  See also .groupname below. */
+	uint64_t options;
+	/**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */
+	void *user;
+	/**< VHOST + CONTEXT: optional user pointer that will be associated
+	 * with the context when creating the context (and can be retrieved by
+	 * lws_context_user(context), or with the vhost when creating the vhost
+	 * (and can be retrieved by lws_vhost_user(vhost)).  You will need to
+	 * use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately
+	 * if you care about giving the context and vhost different user pointer
+	 * values.
+	 */
+	unsigned int count_threads;
+	/**< CONTEXT: how many contexts to create in an array, 0 = 1 */
+	unsigned int fd_limit_per_thread;
+	/**< CONTEXT: nonzero means restrict each service thread to this
+	 * many fds, 0 means the default which is divide the process fd
+	 * limit by the number of threads.
+	 *
+	 * Note if this is nonzero, and fd_limit_per_thread multiplied by the
+	 * number of service threads is less than the process ulimit, then lws
+	 * restricts internal lookup table allocation to the smaller size, and
+	 * switches to a less efficient lookup scheme.  You should use this to
+	 * trade off speed against memory usage if you know the lws context
+	 * will only use a handful of fds.
+	 *
+	 * Bear in mind lws may use some fds internally, for example for the
+	 * cancel pipe, so you may need to allow for some extras for normal
+	 * operation.
+	 */
+	const char *vhost_name;
+	/**< VHOST: name of vhost, must match external DNS name used to
+	 * access the site, like "warmcat.com" as it's used to match
+	 * Host: header and / or SNI name for SSL.
+	 * CONTEXT: NULL, or the name to associate with the context for
+	 * context-specific logging
+	 */
+#if defined(LWS_WITH_PLUGINS)
+	const char * const *plugin_dirs;
+	/**< CONTEXT: NULL, or NULL-terminated array of directories to
+	 * scan for lws protocol plugins at context creation time */
+#endif
+	void *external_baggage_free_on_destroy;
+	/**< CONTEXT: NULL, or pointer to something externally malloc'd, that
+	 * should be freed when the context is destroyed.  This allows you to
+	 * automatically sync the freeing action to the context destruction
+	 * action, so there is no need for an external free() if the context
+	 * succeeded to create.
+	 */
+
+
+	unsigned int pt_serv_buf_size;
+	/**< CONTEXT: 0 = default of 4096.  This buffer is used by
+	 * various service related features including file serving, it
+	 * defines the max chunk of file that can be sent at once.
+	 * At the risk of lws having to buffer failed large sends, it
+	 * can be increased to, eg, 128KiB to improve throughput. */
+#if defined(LWS_WITH_FILE_OPS)
+	const struct lws_plat_file_ops *fops;
+	/**< CONTEXT: NULL, or pointer to an array of fops structs, terminated
+	 * by a sentinel with NULL .open.
+	 *
+	 * If NULL, lws provides just the platform file operations struct for
+	 * backwards compatibility.
+	 */
+#endif
+
+#if defined(LWS_WITH_SOCKS5)
+	const char *socks_proxy_address;
+	/**< VHOST: If non-NULL, attempts to proxy via the given address.
+	 * If proxy auth is required, use format
+	 * "username:password\@server:port" */
+	unsigned int socks_proxy_port;
+	/**< VHOST: If socks_proxy_address was non-NULL, uses this port
+	 * if nonzero, otherwise requires "server:port" in .socks_proxy_address
+	 */
+#endif
+
+#if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP)
+	cap_value_t caps[4];
+	/**< CONTEXT: array holding Linux capabilities you want to
+	 * continue to be available to the server after it transitions
+	 * to a noprivileged user.  Usually none are needed but for, eg,
+	 * .bind_iface, CAP_NET_RAW is required.  This gives you a way
+	 * to still have the capability but drop root.
+	 */
+	char count_caps;
+	/**< CONTEXT: count of Linux capabilities in .caps[].  0 means
+	 * no capabilities will be inherited from root (the default) */
+#endif
+	void **foreign_loops;
+	/**< CONTEXT: This is ignored if the context is not being started with
+	 *		an event loop, ie, .options has a flag like
+	 *		LWS_SERVER_OPTION_LIBUV.
+	 *
+	 *		NULL indicates lws should start its own even loop for
+	 *		each service thread, and deal with closing the loops
+	 *		when the context is destroyed.
+	 *
+	 *		Non-NULL means it points to an array of external
+	 *		("foreign") event loops that are to be used in turn for
+	 *		each service thread.  In the default case of 1 service
+	 *		thread, it can just point to one foreign event loop.
+	 */
+	void (*signal_cb)(void *event_lib_handle, int signum);
+	/**< CONTEXT: NULL: default signal handling.  Otherwise this receives
+	 *		the signal handler callback.  event_lib_handle is the
+	 *		native event library signal handle, eg uv_signal_t *
+	 *		for libuv.
+	 */
+	struct lws_context **pcontext;
+	/**< CONTEXT: if non-NULL, at the end of context destroy processing,
+	 * the pointer pointed to by pcontext is written with NULL.  You can
+	 * use this to let foreign event loops know that lws context destruction
+	 * is fully completed.
+	 */
+	void (*finalize)(struct lws_vhost *vh, void *arg);
+	/**< VHOST: NULL, or pointer to function that will be called back
+	 *	    when the vhost is just about to be freed.  The arg parameter
+	 *	    will be set to whatever finalize_arg is below.
+	 */
+	void *finalize_arg;
+	/**< VHOST: opaque pointer lws ignores but passes to the finalize
+	 *	    callback.  If you don't care, leave it NULL.
+	 */
+	const char *listen_accept_role;
+	/**< VHOST: NULL for default, or force accepted incoming connections to
+	 * bind to this role.  Uses the role names from their ops struct, eg,
+	 * "raw-skt".
+	 */
+	const char *listen_accept_protocol;
+	/**< VHOST: NULL for default, or force accepted incoming connections to
+	 * bind to this vhost protocol name.
+	 */
+	const struct lws_protocols **pprotocols;
+	/**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use
+	 * this array of pointers to protocols structs.  The end of the array
+	 * is marked by a NULL pointer.
+	 *
+	 * This is preferred over .protocols, because it allows the protocol
+	 * struct to be opaquely defined elsewhere, with just a pointer to it
+	 * needed to create the context with it.  .protocols requires also
+	 * the type of the user data to be known so its size can be given.
+	 */
+
+	const char *username; /**< CONTEXT: string username for post-init
+	 * permissions.  Like .uid but takes a string username. */
+	const char *groupname; /**< CONTEXT: string groupname for post-init
+	 * permissions.  Like .gid but takes a string groupname. */
+	const char *unix_socket_perms; /**< VHOST: if your vhost is listening
+	 * on a unix socket, you can give a "username:groupname" string here
+	 * to control the owner:group it's created with.  It's always created
+	 * with 0660 mode. */
+	const lws_system_ops_t *system_ops;
+	/**< CONTEXT: hook up lws_system_ apis to system-specific
+	 * implementations */
+	const lws_retry_bo_t *retry_and_idle_policy;
+	/**< VHOST: optional retry and idle policy to apply to this vhost.
+	 *   Currently only the idle parts are applied to the connections.
+	 */
+#if defined(LWS_WITH_SYS_STATE)
+	lws_state_notify_link_t * const *register_notifier_list;
+	/**< CONTEXT: NULL, or pointer to an array of notifiers that should
+	 * be registered during context creation, so they can see state change
+	 * events from very early on.  The array should end with a NULL. */
+#endif
+#if defined(LWS_WITH_SECURE_STREAMS)
+#if defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY)
+	const struct lws_ss_policy *pss_policies; /**< CONTEXT: point to first
+	 * in a linked-list of streamtype policies prepared by user code */
+#else
+	const char *pss_policies_json; /**< CONTEXT: point to a string
+	 * containing a JSON description of the secure streams policies.  Set
+	 * to NULL if not using Secure Streams.
+	 * If the platform supports files and the string does not begin with
+	 * '{', lws treats the string as a filepath to open to get the JSON
+	 * policy.
+	 */
+#endif
+	const struct lws_ss_plugin **pss_plugins; /**< CONTEXT: point to an array
+	 * of pointers to plugin structs here, terminated with a NULL ptr.
+	 * Set to NULL if not using Secure Streams. */
+	const char *ss_proxy_bind; /**< CONTEXT: NULL, or: ss_proxy_port == 0:
+	 * point to a string giving the Unix Domain Socket address to use (start
+	 * with @ for abstract namespace), ss_proxy_port nonzero: set the
+	 * network interface address (not name, it's ambiguous for ipv4/6) to
+	 * bind the tcp connection to the proxy to */
+	const char *ss_proxy_address; /**< CONTEXT: NULL, or if ss_proxy_port
+	 * nonzero: the tcp address of the ss proxy to connect to */
+	uint16_t ss_proxy_port; /* 0 = if connecting to ss proxy, do it via a
+	 * Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else
+	 * the socket path given in ss_proxy_bind (start it with a + or +@);
+	 * nonzero means connect via a tcp socket to the tcp address in
+	 * ss_proxy_bind and the given port */
+#endif
+
+	int rlimit_nofile;
+	/**< 0 = inherit the initial ulimit for files / sockets from the startup
+	 * environment.  Nonzero = try to set the limit for this process.
+	 */
+#if defined(LWS_WITH_PEER_LIMITS)
+	lws_peer_limits_notify_t pl_notify_cb;
+	/**< CONTEXT: NULL, or a callback to receive notifications each time a
+	 * connection is being dropped because of peer limits.
+	 *
+	 * The callback provides the context, and an lws_sockaddr46 with the
+	 * peer address and port.
+	 */
+	unsigned short ip_limit_ah;
+	/**< CONTEXT: max number of ah a single IP may use simultaneously
+	 *	      0 is no limit. This is a soft limit: if the limit is
+	 *	      reached, connections from that IP will wait in the ah
+	 *	      waiting list and not be able to acquire an ah until
+	 *	      a connection belonging to the IP relinquishes one it
+	 *	      already has.
+	 */
+	unsigned short ip_limit_wsi;
+	/**< CONTEXT: max number of wsi a single IP may use simultaneously.
+	 *	      0 is no limit.  This is a hard limit, connections from
+	 *	      the same IP will simply be dropped once it acquires the
+	 *	      amount of simultaneous wsi / accepted connections
+	 *	      given here.
+	 */
+
+#endif /* PEER_LIMITS */
+
+#if defined(LWS_WITH_SYS_FAULT_INJECTION)
+	lws_fi_ctx_t				fic;
+	/**< CONTEXT | VHOST: attach external Fault Injection context to the
+	 * lws_context or vhost.  If creating the context + default vhost in
+	 * one step, only the context binds to \p fi.  When creating a vhost
+	 * otherwise this can bind to the vhost so the faults can be injected
+	 * from the start.
+	 */
+#endif
+
+#if defined(LWS_WITH_SYS_SMD)
+	lws_smd_notification_cb_t		early_smd_cb;
+	/**< CONTEXT: NULL, or an smd notification callback that will be registered
+	 * immediately after the smd in the context is initialized.  This ensures
+	 * you can get all notifications without having to intercept the event loop
+	 * creation, eg, when using an event library.  Other callbacks can be
+	 * registered later manually without problems.
+	 */
+	void					*early_smd_opaque;
+	lws_smd_class_t				early_smd_class_filter;
+	lws_usec_t				smd_ttl_us;
+	/**< CONTEXT: SMD messages older than this many us are removed from the
+	 * queue and destroyed even if not fully delivered yet.  If zero,
+	 * defaults to 2 seconds (5 second for FREERTOS).
+	 */
+	uint16_t				smd_queue_depth;
+	/**< CONTEXT: Maximum queue depth, If zero defaults to 40
+	 * (20 for FREERTOS) */
+#endif
+
+#if defined(LWS_WITH_SYS_METRICS)
+	const struct lws_metric_policy		*metrics_policies;
+	/**< CONTEXT: non-SS policy metrics policies */
+	const char				*metrics_prefix;
+	/**< CONTEXT: prefix for this context's metrics, used to distinguish
+	 * metrics pooled from different processes / applications, so, eg what
+	 * would be "cpu.svc" if this is NULL becomes "myapp.cpu.svc" is this is
+	 * set to "myapp".  Policies are applied using the name with the prefix,
+	 * if present.
+	 */
+#endif
+
+	int					fo_listen_queue;
+	/**< VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the
+	 * platform supports it, with the given queue length for the listen
+	 * socket.
+	 */
+
+	const struct lws_plugin_evlib		*event_lib_custom;
+	/**< CONTEXT: If non-NULL, override event library selection so it uses
+	 * this custom event library implementation, instead of default internal
+	 * loop.  Don't set any other event lib context creation flags in that
+	 * case. it will be used automatically.  This is useful for integration
+	 * where an existing application is using its own handrolled event loop
+	 * instead of an event library, it provides a way to allow lws to use
+	 * the custom event loop natively as if it were an "event library".
+	 */
+
+#if defined(LWS_WITH_TLS_JIT_TRUST)
+	size_t					jitt_cache_max_footprint;
+	/**< CONTEXT: 0 for no limit, else max bytes used by JIT Trust cache...
+	 * LRU items are evicted to keep under this limit */
+	int					vh_idle_grace_ms;
+	/**< CONTEXT: 0 for default of 5000ms, or number of ms JIT Trust vhosts
+	 * are allowed to live without active connections using them. */
+#endif
+
+	lws_log_cx_t				*log_cx;
+	/**< CONTEXT: NULL to use the default, process-scope logging context,
+	 * else a specific logging context to associate with this context */
+
+#if defined(LWS_WITH_CACHE_NSCOOKIEJAR) && defined(LWS_WITH_CLIENT)
+	const char				*http_nsc_filepath;
+	/**< CONTEXT: Filepath to use for http netscape cookiejar file */
+
+	size_t					http_nsc_heap_max_footprint;
+	/**< CONTEXT: 0, or limit in bytes for heap usage of memory cookie
+	 * cache */
+	size_t					http_nsc_heap_max_items;
+	/**< CONTEXT: 0, or the max number of items allowed in the cookie cache
+	 * before destroying lru items to keep it under the limit */
+	size_t					http_nsc_heap_max_payload;
+	/**< CONTEXT: 0, or the maximum size of a single cookie we are able to
+	 * handle */
+#endif
+
+	/* Add new things just above here ---^
+	 * This is part of the ABI, don't needlessly break compatibility
+	 *
+	 * The below is to ensure later library versions with new
+	 * members added above will see 0 (default) even if the app
+	 * was not built against the newer headers.
+	 */
+
+	void *_unused[2]; /**< dummy */
+};
+
+/**
+ * lws_create_context() - Create the websocket handler
+ * \param info:	pointer to struct with parameters
+ *
+ *	This function creates the listening socket (if serving) and takes care
+ *	of all initialization in one step.
+ *
+ *	If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is
+ *	created; you're expected to create your own vhosts afterwards using
+ *	lws_create_vhost().  Otherwise a vhost named "default" is also created
+ *	using the information in the vhost-related members, for compatibility.
+ *
+ *	After initialization, it returns a struct lws_context * that
+ *	represents this server.  After calling, user code needs to take care
+ *	of calling lws_service() with the context pointer to get the
+ *	server's sockets serviced.  This must be done in the same process
+ *	context as the initialization call.
+ *
+ *	The protocol callback functions are called for a handful of events
+ *	including http requests coming in, websocket connections becoming
+ *	established, and data arriving; it's also called periodically to allow
+ *	async transmission.
+ *
+ *	HTTP requests are sent always to the FIRST protocol in protocol, since
+ *	at that time websocket protocol has not been negotiated.  Other
+ *	protocols after the first one never see any HTTP callback activity.
+ *
+ *	The server created is a simple http server by default; part of the
+ *	websocket standard is upgrading this http connection to a websocket one.
+ *
+ *	This allows the same server to provide files like scripts and favicon /
+ *	images or whatever over http and dynamic data over websockets all in
+ *	one place; they're all handled in the user callback.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_context *
+lws_create_context(const struct lws_context_creation_info *info);
+
+
+/**
+ * lws_context_destroy() - Destroy the websocket context
+ * \param context:	Websocket context
+ *
+ *	This function closes any active connections and then frees the
+ *	context.  After calling this, any further use of the context is
+ *	undefined.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_context_destroy(struct lws_context *context);
+
+typedef int (*lws_reload_func)(void);
+
+/**
+ * lws_context_deprecate() - Deprecate the websocket context
+ *
+ * \param context:	Websocket context
+ * \param cb: Callback notified when old context listen sockets are closed
+ *
+ *	This function is used on an existing context before superceding it
+ *	with a new context.
+ *
+ *	It closes any listen sockets in the context, so new connections are
+ *	not possible.
+ *
+ *	And it marks the context to be deleted when the number of active
+ *	connections into it falls to zero.
+ *
+ *	This is aimed at allowing seamless configuration reloads.
+ *
+ *	The callback cb will be called after the listen sockets are actually
+ *	closed and may be reopened.  In the callback the new context should be
+ *	configured and created.  (With libuv, socket close happens async after
+ *	more loop events).
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_context_deprecate(struct lws_context *context, lws_reload_func cb);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_context_is_deprecated(struct lws_context *context);
+
+/**
+ * lws_set_proxy() - Setups proxy to lws_context.
+ * \param vhost:	pointer to struct lws_vhost you want set proxy for
+ * \param proxy: pointer to c string containing proxy in format address:port
+ *
+ * Returns 0 if proxy string was parsed and proxy was setup.
+ * Returns -1 if proxy is NULL or has incorrect format.
+ *
+ * This is only required if your OS does not provide the http_proxy
+ * environment variable (eg, OSX)
+ *
+ *   IMPORTANT! You should call this function right after creation of the
+ *   lws_context and before call to connect. If you call this
+ *   function after connect behavior is undefined.
+ *   This function will override proxy settings made on lws_context
+ *   creation with genenv() call.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
+
+/**
+ * lws_set_socks() - Setup socks to lws_context.
+ * \param vhost:	pointer to struct lws_vhost you want set socks for
+ * \param socks: pointer to c string containing socks in format address:port
+ *
+ * Returns 0 if socks string was parsed and socks was setup.
+ * Returns -1 if socks is NULL or has incorrect format.
+ *
+ * This is only required if your OS does not provide the socks_proxy
+ * environment variable (eg, OSX)
+ *
+ *   IMPORTANT! You should call this function right after creation of the
+ *   lws_context and before call to connect. If you call this
+ *   function after connect behavior is undefined.
+ *   This function will override proxy settings made on lws_context
+ *   creation with genenv() call.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_set_socks(struct lws_vhost *vhost, const char *socks);
+
+struct lws_vhost;
+
+/**
+ * lws_create_vhost() - Create a vhost (virtual server context)
+ * \param context:	pointer to result of lws_create_context()
+ * \param info:		pointer to struct with parameters
+ *
+ * This function creates a virtual server (vhost) using the vhost-related
+ * members of the info struct.  You can create many vhosts inside one context
+ * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_vhost *
+lws_create_vhost(struct lws_context *context,
+		 const struct lws_context_creation_info *info);
+
+/**
+ * lws_vhost_destroy() - Destroy a vhost (virtual server context)
+ *
+ * \param vh:		pointer to result of lws_create_vhost()
+ *
+ * This function destroys a vhost.  Normally, if you just want to exit,
+ * then lws_destroy_context() will take care of everything.  If you want
+ * to destroy an individual vhost and all connections and allocations, you
+ * can do it with this.
+ *
+ * If the vhost has a listen sockets shared by other vhosts, it will be given
+ * to one of the vhosts sharing it rather than closed.
+ *
+ * The vhost close is staged according to the needs of the event loop, and if
+ * there are multiple service threads.  At the point the vhost itself if
+ * about to be freed, if you provided a finalize callback and optional arg at
+ * vhost creation time, it will be called just before the vhost is freed.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_vhost_destroy(struct lws_vhost *vh);
+
+/**
+ * lwsws_get_config_globals() - Parse a JSON server config file
+ * \param info:		pointer to struct with parameters
+ * \param d:		filepath of the config file
+ * \param config_strings: storage for the config strings extracted from JSON,
+ * 			  the pointer is incremented as strings are stored
+ * \param len:		pointer to the remaining length left in config_strings
+ *			  the value is decremented as strings are stored
+ *
+ * This function prepares a n lws_context_creation_info struct with global
+ * settings from a file d.
+ *
+ * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
+ */
+LWS_VISIBLE LWS_EXTERN int
+lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
+			 char **config_strings, int *len);
+
+/**
+ * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
+ * \param context:	pointer to result of lws_create_context()
+ * \param info:		pointer to struct with parameters
+ * \param d:		filepath of the config file
+ * \param config_strings: storage for the config strings extracted from JSON,
+ * 			  the pointer is incremented as strings are stored
+ * \param len:		pointer to the remaining length left in config_strings
+ *			  the value is decremented as strings are stored
+ *
+ * This function creates vhosts into a context according to the settings in
+ *JSON files found in directory d.
+ *
+ * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
+ */
+LWS_VISIBLE LWS_EXTERN int
+lwsws_get_config_vhosts(struct lws_context *context,
+			struct lws_context_creation_info *info, const char *d,
+			char **config_strings, int *len);
+
+/**
+ * lws_get_vhost() - return the vhost a wsi belongs to
+ *
+ * \param wsi: which connection
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_vhost *
+lws_get_vhost(struct lws *wsi);
+
+/**
+ * lws_get_vhost_name() - returns the name of a vhost
+ *
+ * \param vhost: which vhost
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_get_vhost_name(struct lws_vhost *vhost);
+
+/**
+ * lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL
+ *
+ * \param context: the lws_context to look in
+ * \param name: vhost name we are looking for
+ *
+ * Returns NULL, or the vhost with the name \p name
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_vhost *
+lws_get_vhost_by_name(struct lws_context *context, const char *name);
+
+/**
+ * lws_get_vhost_port() - returns the port a vhost listens on, or -1
+ *
+ * \param vhost: which vhost
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_get_vhost_port(struct lws_vhost *vhost);
+
+/**
+ * lws_get_vhost_user() - returns the user pointer for the vhost
+ *
+ * \param vhost: which vhost
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_get_vhost_user(struct lws_vhost *vhost);
+
+/**
+ * lws_get_vhost_iface() - returns the binding for the vhost listen socket
+ *
+ * \param vhost: which vhost
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_get_vhost_iface(struct lws_vhost *vhost);
+
+/**
+ * lws_json_dump_vhost() - describe vhost state and stats in JSON
+ *
+ * \param vh: the vhost
+ * \param buf: buffer to fill with JSON
+ * \param len: max length of buf
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len);
+
+/**
+ * lws_json_dump_context() - describe context state and stats in JSON
+ *
+ * \param context: the context
+ * \param buf: buffer to fill with JSON
+ * \param len: max length of buf
+ * \param hide_vhosts: nonzero to not provide per-vhost mount etc information
+ *
+ * Generates a JSON description of vhost state into buf
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_json_dump_context(const struct lws_context *context, char *buf, int len,
+		      int hide_vhosts);
+
+/**
+ * lws_vhost_user() - get the user data associated with the vhost
+ * \param vhost: Websocket vhost
+ *
+ * This returns the optional user pointer that can be attached to
+ * a vhost when it was created.  Lws never dereferences this pointer, it only
+ * sets it when the vhost is created, and returns it using this api.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_vhost_user(struct lws_vhost *vhost);
+
+/**
+ * lws_context_user() - get the user data associated with the context
+ * \param context: Websocket context
+ *
+ * This returns the optional user allocation that can be attached to
+ * the context the sockets live in at context_create time.  It's a way
+ * to let all sockets serviced in the same context share data without
+ * using globals statics in the user code.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_context_user(struct lws_context *context);
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_vh_tag(struct lws_vhost *vh);
+
+/**
+ * lws_context_is_being_destroyed() - find out if context is being destroyed
+ *
+ * \param context: the struct lws_context pointer
+ *
+ * Returns nonzero if the context has had lws_context_destroy() called on it...
+ * when using event library loops the destroy process can be asynchronous.  In
+ * the special case of libuv foreign loops, the failure to create the context
+ * may have to do work on the foreign loop to reverse the partial creation,
+ * meaning a failed context create cannot unpick what it did and return NULL.
+ *
+ * In that condition, a valid context that is already started the destroy
+ * process is returned, and this test api will return nonzero as a way to
+ * find out the create is in the middle of failing.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_context_is_being_destroyed(struct lws_context *context);
+
+/*! \defgroup vhost-mounts Vhost mounts and options
+ * \ingroup context-and-vhost-creation
+ *
+ * ##Vhost mounts and options
+ */
+///@{
+/** struct lws_protocol_vhost_options - linked list of per-vhost protocol
+ * 					name=value options
+ *
+ * This provides a general way to attach a linked-list of name=value pairs,
+ * which can also have an optional child link-list using the options member.
+ */
+struct lws_protocol_vhost_options {
+	const struct lws_protocol_vhost_options *next; /**< linked list */
+	const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */
+	const char *name; /**< name of name=value pair */
+	const char *value; /**< value of name=value pair */
+};
+
+/** enum lws_mount_protocols
+ * This specifies the mount protocol for a mountpoint, whether it is to be
+ * served from a filesystem, or it is a cgi etc.
+ */
+enum lws_mount_protocols {
+	LWSMPRO_HTTP		= 0, /**< http reverse proxy */
+	LWSMPRO_HTTPS		= 1, /**< https reverse proxy */
+	LWSMPRO_FILE		= 2, /**< serve from filesystem directory */
+	LWSMPRO_CGI		= 3, /**< pass to CGI to handle */
+	LWSMPRO_REDIR_HTTP	= 4, /**< redirect to http:// url */
+	LWSMPRO_REDIR_HTTPS	= 5, /**< redirect to https:// url */
+	LWSMPRO_CALLBACK	= 6, /**< hand by named protocol's callback */
+};
+
+/** enum lws_authentication_mode
+ * This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter
+ * is ignored unless LWSAUTHM_DEFAULT is set.
+ */
+enum lws_authentication_mode {
+	LWSAUTHM_DEFAULT = 0, /**< default authenticate only if basic_auth_login_file is provided */
+	LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 /**< Basic auth with a custom verifier */
+};
+
+/** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */
+#define AUTH_MODE_MASK 0xF0000000
+
+/** struct lws_http_mount
+ *
+ * arguments for mounting something in a vhost's url namespace
+ */
+struct lws_http_mount {
+	const struct lws_http_mount *mount_next;
+	/**< pointer to next struct lws_http_mount */
+	const char *mountpoint;
+	/**< mountpoint in http pathspace, eg, "/" */
+	const char *origin;
+	/**< path to be mounted, eg, "/var/www/warmcat.com" */
+	const char *def;
+	/**< default target, eg, "index.html" */
+	const char *protocol;
+	/**<"protocol-name" to handle mount */
+
+	const struct lws_protocol_vhost_options *cgienv;
+	/**< optional linked-list of cgi options.  These are created
+	 * as environment variables for the cgi process
+	 */
+	const struct lws_protocol_vhost_options *extra_mimetypes;
+	/**< optional linked-list of mimetype mappings */
+	const struct lws_protocol_vhost_options *interpret;
+	/**< optional linked-list of files to be interpreted */
+
+	int cgi_timeout;
+	/**< seconds cgi is allowed to live, if cgi://mount type */
+	int cache_max_age;
+	/**< max-age for reuse of client cache of files, seconds */
+	unsigned int auth_mask;
+	/**< bits set here must be set for authorized client session */
+
+	unsigned int cache_reusable:1; /**< set if client cache may reuse this */
+	unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */
+	unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */
+
+	unsigned char origin_protocol; /**< one of enum lws_mount_protocols */
+	unsigned char mountpoint_len; /**< length of mountpoint string */
+
+	const char *basic_auth_login_file;
+	/**<NULL, or filepath to use to check basic auth logins against. (requires LWSAUTHM_DEFAULT) */
+
+	/* Add new things just above here ---^
+	 * This is part of the ABI, don't needlessly break compatibility
+	 */
+};
+
+///@}
+///@}

include/libwebsockets/lws-cose.h

@@ -0,0 +1,511 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup cose COSE apis
+ * ##COSE related functions
+ * \ingroup lwsaoi
+ *
+ * COSE RFC 8152 relates to signed and encrypted CBOR
+ */
+//@{
+
+enum {
+	/*  RFC8152: Table 2: Common Header Parameters
+	 * https://www.iana.org/assignments/cose/cose.xhtml#header-parameters
+	 */
+
+	LWSCOSE_WKL_ALG				= 1,   /* int / tstr */
+	LWSCOSE_WKL_CRIT,			       /* [+ label ] */
+	LWSCOSE_WKL_CONTENT_TYPE,		       /* tstr / uint */
+	LWSCOSE_WKL_KID,			       /* bstr */
+	LWSCOSE_WKL_IV,				       /* bstr */
+	LWSCOSE_WKL_IV_PARTIAL,			       /* bstr */
+	LWSCOSE_WKL_COUNTERSIG,			       /* COSE sig(s) */
+	LWSCOSE_WKL_COUNTERSIG0			= 9,   /* bstr */
+	LWSCOSE_WKL_KID_CONTEXT,		       /* bstr */
+	LWSCOSE_WKL_CUPH_NONCE			= 256, /* bstr */
+	LWSCOSE_WKL_CUPH_OWNER_PUBKEY		= 257, /* array */
+
+	/*  RFC8152: Table 3: key map labels */
+
+	LWSCOSE_WKK_KTY				= 1, /* int / tstr */
+	LWSCOSE_WKK_KID,			     /* bstr */
+	LWSCOSE_WKK_ALG,			     /* int / tstr */
+	LWSCOSE_WKK_KEY_OPS,			     /* [ + (int / tstr) ] */
+	LWSCOSE_WKK_BASE_IV,			     /* bstr */
+
+	/*  RFC8152: Table 4: Key Operation Values */
+
+	LWSCOSE_WKKO_SIGN			= 1,
+	LWSCOSE_WKKO_VERIFY,
+	LWSCOSE_WKKO_ENCRYPT,
+	LWSCOSE_WKKO_DECRYPT,
+	LWSCOSE_WKKO_WRAP_KEY,
+	LWSCOSE_WKKO_UNWRAP_KEY,
+	LWSCOSE_WKKO_DERIVE_KEY,
+	LWSCOSE_WKKO_DERIVE_BITS,
+	LWSCOSE_WKKO_MAC_CREATE,
+	LWSCOSE_WKKO_MAC_VERIFY,
+
+	/*  RFC8152: Table 5: ECDSA algs */
+
+	LWSCOSE_WKAECDSA_ALG_ES256		= -7,
+	LWSCOSE_WKAECDSA_ALG_ES384		= -35,
+	LWSCOSE_WKAECDSA_ALG_ES512		= -36,
+
+	/*  RFC8152: Table 6: EDDSA algs */
+
+	LWSCOSE_WKAEDDSA_ALG_EDDSA		= -8,
+
+	/*  RFC8152: Table 7: HMAC algs */
+
+	LWSCOSE_WKAHMAC_256_64			= 4,
+	LWSCOSE_WKAHMAC_256_256,
+	LWSCOSE_WKAHMAC_384_384,
+	LWSCOSE_WKAHMAC_512_512,
+
+	/*  RFC8152: Table 8: AES algs */
+
+	LWSCOSE_WKAAES_128_64			= 14,
+	LWSCOSE_WKAAES_256_64,
+	LWSCOSE_WKAAES_128_128			= 25,
+	LWSCOSE_WKAAES_256_128,
+
+	/*  RFC8152: Table 9: AES GCM algs */
+
+	LWSCOSE_WKAAESGCM_128			= 1,
+	LWSCOSE_WKAAESGCM_192,
+	LWSCOSE_WKAAESGCM_256,
+
+	/*  RFC8152: Table 10: AES CCM algs */
+
+	LWSCOSE_WKAAESCCM_16_64_128		= 10,
+	LWSCOSE_WKAAESCCM_16_64_256,
+	LWSCOSE_WKAAESCCM_64_64_128,
+	LWSCOSE_WKAAESCCM_64_64_256,
+	LWSCOSE_WKAAESCCM_16_128_128,
+	LWSCOSE_WKAAESCCM_16_128_256,
+	LWSCOSE_WKAAESCCM_64_128_128,
+	LWSCOSE_WKAAESCCM_64_128_256,
+
+	/*  RFC8152: Table 11: CHACHA20 / Poly1305 */
+
+	LWSCOSE_WKACHACHA_POLY1305		= 24,
+
+	/*  RFC8152: Table 13: HKDF param */
+
+	LWSCOSE_WKAPHKDF_SALT			= -20,
+
+	/* RFC8152: Table 14: Context Algorithm Parameters */
+
+	LWSCOSE_WKAPCTX_PARTY_U_IDENTITY	= -21,
+	LWSCOSE_WKAPCTX_PARTY_U_NONCE		= -22,
+	LWSCOSE_WKAPCTX_PARTY_U_OTHER		= -23,
+	LWSCOSE_WKAPCTX_PARTY_V_IDENTITY	= -24,
+	LWSCOSE_WKAPCTX_PARTY_V_NONCE		= -25,
+	LWSCOSE_WKAPCTX_PARTY_V_OTHER		= -26,
+
+	/* RFC8152: Table 15: Direct key */
+
+	LWSCOSE_WKK_DIRECT_CEK			= -6,
+
+	/* RFC8152: Table 16: Direct key with KDF */
+
+	LWSCOSE_WKK_DIRECT_HKDF_SHA_256		= -10,
+	LWSCOSE_WKK_DIRECT_HKDF_SHA_512		= -11,
+	LWSCOSE_WKK_DIRECT_HKDF_AES_128		= -12,
+	LWSCOSE_WKK_DIRECT_HKDF_AES_256		= -13,
+
+	/* RFC8152: Table 17: AES Key Wrap Algorithm Values */
+
+	LWSCOSE_WKK_DIRECT_HKDFKW_SHA_256	= -3,
+	LWSCOSE_WKK_DIRECT_HKDFKW_SHA_512	= -4,
+	LWSCOSE_WKK_DIRECT_HKDFKW_AES_128	= -5,
+
+	/* RFC8152: Table 18: ECDH Algorithm Values */
+
+	LWSCOSE_WKAECDH_ALG_ES_HKDF_256		= -25,
+	LWSCOSE_WKAECDH_ALG_ES_HKDF_512		= -26,
+	LWSCOSE_WKAECDH_ALG_SS_HKDF_256		= -27,
+	LWSCOSE_WKAECDH_ALG_SS_HKDF_512		= -28,
+
+	/* RFC8152: Table 19: ECDH Algorithm Parameters */
+
+	LWSCOSE_WKAPECDH_EPHEMERAL_KEY		= -1,
+	LWSCOSE_WKAPECDH_STATIC_KEY		= -2,
+	LWSCOSE_WKAPECDH_STATIC_KEY_ID		= -3,
+
+	/* RFC8152: Table 20: ECDH Algorithm Parameters with key wrap */
+
+	LWSCOSE_WKAPECDH_ES_A128KW		= -29,
+	LWSCOSE_WKAPECDH_ES_A192KW		= -30,
+	LWSCOSE_WKAPECDH_ES_A256KW		= -31,
+	LWSCOSE_WKAPECDH_SS_A128KW		= -32,
+	LWSCOSE_WKAPECDH_SS_A192KW		= -33,
+	LWSCOSE_WKAPECDH_SS_A256KW		= -34,
+
+	/* RFC8152: Table 21: Key Type Values
+	 *  https://www.iana.org/assignments/cose/cose.xhtml#key-type
+	 */
+
+	LWSCOSE_WKKTV_OKP			= 1,
+	LWSCOSE_WKKTV_EC2			= 2,
+	LWSCOSE_WKKTV_RSA			= 3,
+	LWSCOSE_WKKTV_SYMMETRIC			= 4,
+	LWSCOSE_WKKTV_HSS_LMS			= 5,
+	LWSCOSE_WKKTV_WALNUTDSA			= 6,
+
+
+	/* RFC8152: Table 22: Elliptic Curves
+	 * https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves
+	 */
+
+	LWSCOSE_WKEC_P256			= 1,
+	LWSCOSE_WKEC_P384,
+	LWSCOSE_WKEC_P521,
+	LWSCOSE_WKEC_X25519,
+	LWSCOSE_WKEC_X448,
+	LWSCOSE_WKEC_ED25519,
+	LWSCOSE_WKEC_ED448,
+	LWSCOSE_WKEC_SECP256K1,
+
+	/* RFC8152: Table 23: EC Key Parameters */
+
+	LWSCOSE_WKECKP_CRV			= -1,
+	LWSCOSE_WKECKP_X			= -2,
+	LWSCOSE_WKECKP_Y			= -3,
+	LWSCOSE_WKECKP_D			= -4,
+
+	/* RFC8152: Table 24: Octet Key Pair (OKP) Parameters */
+
+	LWSCOSE_WKOKP_CRV			= -1,
+	LWSCOSE_WKOKP_X				= -2,
+	LWSCOSE_WKOKP_D				= -4,
+
+	/* Additional from
+	 * https://www.iana.org/assignments/cose/cose.xhtml#key-type-parameters
+	 */
+
+	LWSCOSE_WKKPRSA_N			= -1,
+	LWSCOSE_WKKPRSA_E			= -2,
+	LWSCOSE_WKKPRSA_D			= -3,
+	LWSCOSE_WKKPRSA_P			= -4,
+	LWSCOSE_WKKPRSA_Q			= -5,
+	LWSCOSE_WKKPRSA_DP			= -6,
+	LWSCOSE_WKKPRSA_DQ			= -7,
+	LWSCOSE_WKKPRSA_QINV			= -8,
+	LWSCOSE_WKKPRSA_OTHER			= -9,
+	LWSCOSE_WKKPRSA_RI			= -10,
+	LWSCOSE_WKKPRSA_DI			= -11,
+	LWSCOSE_WKKPRSA_TI			= -12,
+
+	/* RFC8152: Table 25: Symmetric Key Parameters */
+
+	LWSCOSE_WKSYMKP_KEY_VALUE		= 4,
+
+	/* RFC8152: Table 26: CoAP Content-Formats for COSE */
+
+	LWSCOAP_CONTENTFORMAT_COSE_SIGN		= 98,
+	LWSCOAP_CONTENTFORMAT_COSE_SIGN1	= 18,
+	LWSCOAP_CONTENTFORMAT_COSE_ENCRYPT	= 96,
+	LWSCOAP_CONTENTFORMAT_COSE_ENCRYPT0	= 16,
+	LWSCOAP_CONTENTFORMAT_COSE_MAC		= 97,
+	LWSCOAP_CONTENTFORMAT_COSE_MAC0		= 17,
+	LWSCOAP_CONTENTFORMAT_COSE_KEY		= 101,
+	LWSCOAP_CONTENTFORMAT_COSE_KEY_SET	= 102,
+
+	/* RFC8152: Table 27: Header Parameter for CounterSignature0 */
+
+	LWSCOSE_WKL_COUNTERSIGNATURE0		= 9, /* bstr */
+
+	/* RFC8812: Table 1: RSASSA-PKCS1-v1_5 Algorithm Values */
+
+	LWSCOSE_WKARSA_ALG_RS256		= -257, /* + SHA-256 */
+	LWSCOSE_WKARSA_ALG_RS384		= -258, /* + SHA-384 */
+	LWSCOSE_WKARSA_ALG_RS512		= -259, /* + SHA-512 */
+};
+
+enum enum_cose_key_meta_tok {
+	COSEKEY_META_KTY,
+	COSEKEY_META_KID,
+	COSEKEY_META_KEY_OPS,
+	COSEKEY_META_BASE_IV,
+	COSEKEY_META_ALG,
+
+	LWS_COUNT_COSE_KEY_ELEMENTS
+};
+
+typedef int64_t cose_param_t;
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_cose_alg_to_name(cose_param_t alg);
+
+LWS_VISIBLE LWS_EXTERN cose_param_t
+lws_cose_name_to_alg(const char *name);
+
+/*
+ * cose_key
+ */
+
+typedef struct lws_cose_key {
+	/* key data elements */
+	struct lws_gencrypto_keyelem	e[LWS_GENCRYPTO_MAX_KEYEL_COUNT];
+	/* generic meta key elements, like KID */
+	struct lws_gencrypto_keyelem 	meta[LWS_COUNT_COSE_KEY_ELEMENTS];
+	lws_dll2_t			list; /* used when part of a set */
+	int				gencrypto_kty;	/**< one of LWS_GENCRYPTO_KTY_ */
+	cose_param_t			kty;
+	cose_param_t			cose_alg;
+	cose_param_t			cose_curve;
+	char 				private_key; /* nonzero = has private key elements */
+} lws_cose_key_t;
+
+typedef int (*lws_cose_key_import_callback)(struct lws_cose_key *s, void *user);
+
+/** lws_cose_jwk_import() - Create an lws_cose_key_t object from cose_key CBOR
+ *
+ * \param pkey_set: NULL, or a pointer to an lws_dll2_owner_t for a cose_key set
+ * \param cb: callback for each jwk-processed key, or NULL if importing a single
+ *	      key with no parent "keys" JSON
+ * \param user: pointer to be passed to the callback, otherwise ignored by lws.
+ *		NULL if importing a single key with no parent "keys" JSON
+ * \param in: a single cose_key
+ * \param len: the length of the cose_key in bytes
+ *
+ * Creates a single lws_cose_key_t if \p pkey_set is NULL or if the incoming
+ * CBOR doesn't start with an array, otherwise expects a CBOR array containing
+ * zero or more cose_key CBOR, and adds each to the \p pkey_set
+ * lws_dll2_owner_t struct.  Created lws_cose_key_t are filled with data from
+ * the COSE representation and can be used with other COSE crypto ops.
+ */
+LWS_VISIBLE LWS_EXTERN lws_cose_key_t *
+lws_cose_key_import(lws_dll2_owner_t *pkey_set, lws_cose_key_import_callback cb,
+		    void *user, const uint8_t *in, size_t len);
+
+/** lws_cose_key_export() - Create cose_key CBOR from an lws_cose_key_t
+ *
+ * \param ck: the lws_cose_key_t to export to CBOR
+ * \param ctx: the CBOR writing context (same as for lws_lec_printf())
+ * \param flags: 0 to export only public elements, or LWSJWKF_EXPORT_PRIVATE
+ *
+ * Creates an lws_jwk struct filled with data from the COSE representation.
+ */
+LWS_VISIBLE LWS_EXTERN enum lws_lec_pctx_ret
+lws_cose_key_export(lws_cose_key_t *ck, lws_lec_pctx_t *ctx, int flags);
+
+/**
+ * lws_cose_key_generate() - generate a fresh key
+ *
+ * \param context: the lws_context used to get random
+ * \param cose_kty: one of LWSCOSE_WKKTV_ indicating the well-known key type
+ * \param use_mask: 0, or a bitfield where (1 << LWSCOSE_WKKO_...) set means valid for use
+ * \param bits: key bits for RSA
+ * \param curve: for EC keys, one of "P-256", "P-384" or "P-521" currently
+ * \param kid: string describing the key, or NULL
+ *
+ * Create an lws_cose_key_t of the specified type and return it
+ */
+LWS_VISIBLE LWS_EXTERN lws_cose_key_t *
+lws_cose_key_generate(struct lws_context *context, cose_param_t cose_kty,
+		      int use_mask, int bits, const char *curve,
+		      const uint8_t *kid, size_t kl);
+
+LWS_VISIBLE LWS_EXTERN lws_cose_key_t *
+lws_cose_key_from_set(lws_dll2_owner_t *set, const uint8_t *kid, size_t kl);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_cose_key_destroy(lws_cose_key_t **ck);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_cose_key_set_destroy(lws_dll2_owner_t *o);
+
+/* only available in _DEBUG build */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_cose_key_dump(const lws_cose_key_t *ck);
+
+/*
+ * cose_sign
+ */
+
+struct lws_cose_validate_context;
+
+
+enum lws_cose_sig_types {
+	SIGTYPE_UNKNOWN,
+	SIGTYPE_MULTI,
+	SIGTYPE_SINGLE,
+	SIGTYPE_COUNTERSIGNED, /* not yet supported */
+	SIGTYPE_MAC, /* only supported for validation */
+	SIGTYPE_MAC0,
+};
+
+/* a list of these result objects is the output of the validation process */
+
+typedef struct {
+	lws_dll2_t		list;
+
+	const lws_cose_key_t	*cose_key;
+	cose_param_t		cose_alg;
+
+	int			result; /* 0 = validated */
+
+} lws_cose_validate_res_t;
+
+enum {
+	LCOSESIGEXTCB_RET_FINISHED,
+	LCOSESIGEXTCB_RET_AGAIN,
+	LCOSESIGEXTCB_RET_ERROR		= -1
+};
+
+typedef struct {
+	struct lws_cose_validate_context *cps;
+	const uint8_t			 *ext;
+	size_t				 xl;
+} lws_cose_sig_ext_pay_t;
+
+typedef int (*lws_cose_sign_ext_pay_cb_t)(lws_cose_sig_ext_pay_t *x);
+typedef int (*lws_cose_validate_pay_cb_t)(struct lws_cose_validate_context *cps,
+					  void *opaque, const uint8_t *paychunk,
+					  size_t paychunk_len);
+
+typedef struct lws_cose_validate_create_info {
+	struct lws_context		*cx;
+	/**< REQUIRED: the lws context */
+	lws_dll2_owner_t		*keyset;
+	/**< REQUIRED: one or more cose_keys */
+
+	enum lws_cose_sig_types		sigtype;
+	/**<  0 if a CBOR tag is in the sig, else one of SIGTYPE_MULTI,
+	 * SIGTYPE_SINGLE, etc*/
+
+	lws_cose_validate_pay_cb_t	pay_cb;
+	/**< optional: called back with unvalidated payload pieces */
+	void				*pay_opaque;
+	/**< optional: passed into pay_cb callback along with payload chunk */
+
+	lws_cose_sign_ext_pay_cb_t	ext_cb;
+	/**< optional extra application data provision callback */
+	void				*ext_opaque;
+	/**< optional extra application data provision callback opaque */
+	size_t				ext_len;
+	/**< if we have extra app data, this must be set to the length of it */
+} lws_cose_validate_create_info_t;
+
+/**
+ * lws_cose_validate_create() - create a signature validation context
+ *
+ * \param info: struct describing the validation context to create
+ *
+ * Creates a signature validation context set up as described in \p info.
+ *
+ * You can then pass the signature cbor chunks to it using
+ * lws_cose_validate_chunk(), finialize and get the results list using
+ * lws_cose_validate_results() and destroy with lws_cose_validate_destroy().
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_cose_validate_context *
+lws_cose_validate_create(const lws_cose_validate_create_info_t *info);
+
+/**
+ * lws_cose_validate_chunk() - passes chunks of CBOR into the signature validator
+ *
+ * \param cps: the validation context
+ * \param in: the chunk of CBOR (does not have to be logically complete)
+ * \param in_len: number of bytes available at \p in
+ *
+ * Parses signature CBOR to produce a list of result objects.
+ *
+ *
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_cose_validate_chunk(struct lws_cose_validate_context *cps,
+			const uint8_t *in, size_t in_len, size_t *used_in);
+
+LWS_VISIBLE LWS_EXTERN lws_dll2_owner_t *
+lws_cose_validate_results(struct lws_cose_validate_context *cps);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_cose_validate_destroy(struct lws_cose_validate_context **cps);
+
+struct lws_cose_sign_context;
+
+#define LCSC_FL_ADD_CBOR_TAG		(1 << 0)
+#define LCSC_FL_ADD_CBOR_PREFER_MAC0	(1 << 1)
+
+typedef struct lws_cose_sign_create_info {
+	struct lws_context		*cx;
+	/**< REQUIRED: the lws context */
+	lws_dll2_owner_t		*keyset;
+	/**< REQUIRED: one or more cose_keys */
+
+	lws_lec_pctx_t			*lec;
+	/**< REQUIRED: the cbor output context to emit to, user must
+	 * initialize with lws_lec_init() beforehand */
+
+	lws_cose_sign_ext_pay_cb_t	ext_cb;
+	/**< optional extra application data provision callback */
+	void				*ext_opaque;
+	/**< optional extra application data provision callback opaque */
+	size_t				ext_len;
+	/**< if we have extra app data, this must be set to the length of it */
+
+	size_t				inline_payload_len;
+	/**< REQUIRED: size of the inline payload we will provide */
+
+	int				flags;
+	/**< bitmap of  LCSC_FL_* */
+	enum lws_cose_sig_types		sigtype;
+	/**< 0, or sign type hint */
+} lws_cose_sign_create_info_t;
+
+/**
+ * lws_cose_sign_create() - Create a signing context
+ *
+ * \param info: a structure describing the signing context you want to create
+ *
+ * This allocates and returns a signing context created according to what is in
+ * the \p info parameter.
+ *
+ * \p info must be prepared with the lws_context, a keyset to use, a CBOR
+ * output context, and the inline payload length.
+ *
+ * Returns NULL on failure or the created signing context ready to add alg(s)
+ * to.
+ */
+
+LWS_VISIBLE LWS_EXTERN struct lws_cose_sign_context *
+lws_cose_sign_create(const lws_cose_sign_create_info_t *info);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_cose_sign_add(struct lws_cose_sign_context *csc, cose_param_t alg,
+		  const lws_cose_key_t *ck);
+
+LWS_VISIBLE LWS_EXTERN enum lws_lec_pctx_ret
+lws_cose_sign_payload_chunk(struct lws_cose_sign_context *csc,
+			    const uint8_t *in, size_t in_len);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_cose_sign_destroy(struct lws_cose_sign_context **csc);
+
+//@}

include/libwebsockets/lws-dbus.h

@@ -0,0 +1,94 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * must be included manually as
+ *
+ *  #include <libwebsockets/lws-dbus.h>
+ *
+ * if dbus apis needed
+ */
+
+#if !defined(__LWS_DBUS_H__)
+#define __LWS_DBUS_H__
+
+#include <dbus/dbus.h>
+
+/* helper type to simplify implementing methods as individual functions */
+typedef DBusHandlerResult (*lws_dbus_message_handler)(DBusConnection *conn,
+			   DBusMessage *message, DBusMessage **reply, void *d);
+
+struct lws_dbus_ctx;
+typedef void (*lws_dbus_closing_t)(struct lws_dbus_ctx *ctx);
+
+struct lws_dbus_ctx {
+	struct lws_dll2_owner owner; /* dbusserver ctx: HEAD of accepted list */
+	struct lws_dll2 next; /* dbusserver ctx: HEAD of accepted list */
+	struct lws_vhost *vh; /* the vhost we logically bind to in lws */
+	int tsi;	/* the lws thread service index (0 if only one service
+			   thread as is the default */
+	DBusConnection *conn;
+	DBusServer *dbs;
+	DBusWatch *w[4];
+ 	DBusPendingCall *pc;
+
+ 	char hup;
+ 	char timeouts;
+
+ 	/* cb_closing callback will be called after the connection and this
+ 	 * related ctx struct have effectively gone out of scope.
+ 	 *
+ 	 * The callback should close and clean up the connection and free the
+ 	 * ctx.
+ 	 */
+ 	lws_dbus_closing_t cb_closing;
+};
+
+/**
+ * lws_dbus_connection_setup() - bind dbus connection object to lws event loop
+ *
+ * \param ctx: additional information about the connection
+ * \param conn: the DBusConnection object to bind
+ *
+ * This configures a DBusConnection object to use lws for watchers and timeout
+ * operations.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_dbus_connection_setup(struct lws_dbus_ctx *ctx, DBusConnection *conn,
+			  lws_dbus_closing_t cb_closing);
+
+/**
+ * lws_dbus_server_listen() - bind dbus connection object to lws event loop
+ *
+ * \param ctx: additional information about the connection
+ * \param ads: the DBUS address to listen on, eg, "unix:abstract=mysocket"
+ * \param err: a DBusError object to take any extra error information
+ * \param new_conn: a callback function to prepare new accepted connections
+ *
+ * This creates a DBusServer and binds it to the lws event loop, and your
+ * callback to accept new connections.
+ */
+LWS_VISIBLE LWS_EXTERN DBusServer *
+lws_dbus_server_listen(struct lws_dbus_ctx *ctx, const char *ads,
+		       DBusError *err, DBusNewConnectionFunction new_conn);
+
+#endif

include/libwebsockets/lws-diskcache.h

@@ -0,0 +1,187 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup diskcache LWS disk cache
+ * ## Disk cache API
+ *
+ * Lws provides helper apis useful if you need a disk cache containing hashed
+ * files and need to delete files from it on an LRU basis to keep it below some
+ * size limit.
+ *
+ * The API `lws_diskcache_prepare()` deals with creating the cache dir and
+ * 256 subdirs, which are used according to the first two chars of the hex
+ * hash of the cache file.
+ *
+ * `lws_diskcache_create()` and `lws_diskcache_destroy()` allocate and free
+ * an opaque struct that represents the disk cache.
+ *
+ * `lws_diskcache_trim()` should be called at eg, 1s intervals to perform the
+ * cache dir monitoring and LRU autodelete in the background lazily.  It can
+ * be done in its own thread or on a timer... it monitors the directories in a
+ * stateful way that stats one or more file in the cache per call, and keeps
+ * a list of the oldest files as it goes.  When it completes a scan, if the
+ * aggregate size is over the limit, it will delete oldest files first to try
+ * to keep it under the limit.
+ *
+ * The cache size monitoring is extremely efficient in time and memory even when
+ * the cache directory becomes huge.
+ *
+ * `lws_diskcache_query()` is used to determine if the file already exists in
+ * the cache, or if it must be created.  If it must be created, then the file
+ * is opened using a temp name that must be converted to a findable name with
+ * `lws_diskcache_finalize_name()` when the generation of the file contents are
+ * complete.  Aborted cached files that did not complete generation will be
+ * flushed by the LRU eventually.  If the file already exists, it is 'touched'
+ * to make it new again and the fd returned.
+ *
+ */
+///@{
+
+struct lws_diskcache_scan;
+
+/**
+ * lws_diskcache_create() - creates an opaque struct representing the disk cache
+ *
+ * \param cache_dir_base: The cache dir path, eg `/var/cache/mycache`
+ * \param cache_size_limit: maximum size on disk the cache is allowed to use
+ *
+ * This returns an opaque `struct lws_diskcache_scan *` which represents the
+ * disk cache, the trim scanning state and so on.  You should use
+ * `lws_diskcache_destroy()` to free it to destroy it.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_diskcache_scan *
+lws_diskcache_create(const char *cache_dir_base, uint64_t cache_size_limit);
+
+/**
+ * lws_diskcache_destroy() - destroys the pointer returned by ...create()
+ *
+ * \param lds: pointer to the pointer returned by lws_diskcache_create()
+ *
+ * Frees *lds and any allocations it did, and then sets *lds to NULL and
+ * returns.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_diskcache_destroy(struct lws_diskcache_scan **lds);
+
+/**
+ * lws_diskcache_prepare() - ensures the cache dir structure exists on disk
+ *
+ * \param cache_base_dir: The cache dir path, eg `/var/cache/mycache`
+ * \param mode: octal dir mode to enforce, like 0700
+ * \param uid: uid the cache dir should belong to
+ *
+ * This should be called while your app is still privileged.  It will create
+ * the cache directory structure on disk as necessary, enforce the given access
+ * mode on it and set the given uid as the owner.  It won't make any trouble
+ * if the cache already exists.
+ *
+ * Typically the mode is 0700 and the owner is the user that your application
+ * will transition to use when it drops root privileges.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_diskcache_prepare(const char *cache_base_dir, int mode, uid_t uid);
+
+#define LWS_DISKCACHE_QUERY_NO_CACHE	0
+#define LWS_DISKCACHE_QUERY_EXISTS	1
+#define LWS_DISKCACHE_QUERY_CREATING	2
+#define LWS_DISKCACHE_QUERY_ONGOING	3 /* something else is creating it */
+
+/**
+ * lws_diskcache_query() - ensures the cache dir structure exists on disk
+ *
+ * \param lds: The opaque struct representing the disk cache
+ * \param is_bot: nonzero means the request is from a bot.  Don't create new cache contents if so.
+ * \param hash_hex: hex string representation of the cache object hash
+ * \param _fd: pointer to the fd to be set
+ * \param cache: destination string to take the cache filepath
+ * \param cache_len: length of the buffer at `cache`
+ * \param extant_cache_len: pointer to a size_t to take any extant cached file size
+ *
+ * This function is called when you want to find if the hashed name already
+ * exists in the cache.  The possibilities for the return value are
+ *
+ *  - LWS_DISKCACHE_QUERY_NO_CACHE: It's not in the cache and you can't create
+ *    it in the cache for whatever reason.
+ *  - LWS_DISKCACHE_QUERY_EXISTS: It exists in the cache.  It's open RDONLY and
+ *    *_fd has been set to the file descriptor.  *extant_cache_len has been set
+ *    to the size of the cached file in bytes.  cache has been set to the
+ *    full filepath of the cached file.  Closing _fd is your responsibility.
+ *  - LWS_DISKCACHE_QUERY_CREATING: It didn't exist, but a temp file has been
+ *    created in the cache and *_fd set to a file descriptor opened on it RDWR.
+ *    You should create the contents, and call `lws_diskcache_finalize_name()`
+ *    when it is done.  Closing _fd is your responsibility.
+ *  - LWS_DISKCACHE_QUERY_ONGOING: not returned by this api, but you may find it
+ *    desirable to make a wrapper function which can handle another asynchronous
+ *    process that is already creating the cached file.  This can be used to
+ *    indicate that situation externally... how to determine the same thing is
+ *    already being generated is out of scope of this api.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_diskcache_query(struct lws_diskcache_scan *lds, int is_bot,
+		    const char *hash_hex, int *_fd, char *cache, int cache_len,
+		    size_t *extant_cache_len);
+
+/**
+ * lws_diskcache_query() - ensures the cache dir structure exists on disk
+ *
+ * \param cache: The cache file temp name returned with LWS_DISKCACHE_QUERY_CREATING
+ *
+ * This renames the cache file you are creating to its final name.  It should
+ * be called on the temp name returned by `lws_diskcache_query()` if it gave a
+ * LWS_DISKCACHE_QUERY_CREATING return, after you have filled the cache file and
+ * closed it.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_diskcache_finalize_name(char *cache);
+
+/**
+ * lws_diskcache_trim() - performs one or more file checks in the cache for size management
+ *
+ * \param lds: The opaque object representing the cache
+ *
+ * This should be called periodically to statefully walk the cache on disk
+ * collecting the oldest files.  When it has visited every file, if the cache
+ * is oversize it will delete the oldest files until it's back under size again.
+ *
+ * Each time it's called, it will look at one or more dir in the cache.  If
+ * called when the cache is oversize, it increases the amount of work done each
+ * call until it is reduced again.  Typically it will take 256 calls before it
+ * deletes anything, so if called once per second, it will delete files once
+ * every 4 minutes.  Each call is very inexpensive both in memory and time.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_diskcache_trim(struct lws_diskcache_scan *lds);
+
+
+/**
+ * lws_diskcache_secs_to_idle() - see how long to idle before calling trim
+ *
+ * \param lds: The opaque object representing the cache
+ *
+ * If the cache is undersize, there's no need to monitor it immediately.  This
+ * suggests how long to "sleep" before calling `lws_diskcache_trim()` again.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_diskcache_secs_to_idle(struct lws_diskcache_scan *lds);
+///@}

include/libwebsockets/lws-display.h

@@ -0,0 +1,158 @@
+/*
+ * lws abstract display
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#if !defined(__LWS_DISPLAY_H__)
+#define __LWS_DISPLAY_H__
+
+#include <stdint.h>
+
+typedef uint16_t lws_display_scalar;
+
+/*
+ * This is embedded in the actual display implementation object at the top,
+ * so a pointer to this can be cast to a pointer to the implementation object
+ * by any code that is specific to how it was implemented.
+ *
+ * Notice for the backlight / display intensity we contain pwm_ops... these can
+ * be some other pwm_ops like existing gpio pwm ops, or handled in a customized
+ * way like set oled contrast.  Either way, the pwm level is arrived at via a
+ * full set of lws_led_sequences capable of generic lws transitions
+ */
+
+typedef struct lws_display {
+	int (*init)(const struct lws_display *disp);
+	const lws_pwm_ops_t		*bl_pwm_ops;
+	int (*contrast)(const struct lws_display *disp, uint8_t contrast);
+	int (*blit)(const struct lws_display *disp, const uint8_t *src,
+		    lws_display_scalar x, lws_display_scalar y,
+		    lws_display_scalar w, lws_display_scalar h);
+	int (*power)(const struct lws_display *disp, int state);
+
+	const lws_led_sequence_def_t	*bl_active;
+	const lws_led_sequence_def_t	*bl_dim;
+	const lws_led_sequence_def_t	*bl_transition;
+
+	void				*variant;
+
+	int				bl_index;
+
+	lws_display_scalar		w;
+	/**< display surface width in pixels */
+	lws_display_scalar		h;
+	/**< display surface height in pixels */
+
+	uint8_t				latency_wake_ms;
+	/**< ms required after wake from sleep before display usable again...
+	 * delay bringing up the backlight for this amount of time on wake.
+	 * This is managed via a sul on the event loop, not blocking. */
+} lws_display_t;
+
+/*
+ * This contains dynamic data related to display state
+ */
+
+enum lws_display_controller_state {
+	LWSDISPS_OFF,
+	LWSDISPS_AUTODIMMED,	  /* is in pre- blanking static dim mode */
+	LWSDISPS_BECOMING_ACTIVE, /* waiting for wake latency before active */
+	LWSDISPS_ACTIVE,	  /* is active */
+	LWSDISPS_GOING_OFF	  /* dimming then off */
+};
+
+typedef struct lws_display_state {
+
+	lws_sorted_usec_list_t		sul_autodim;
+	const lws_display_t		*disp;
+	struct lws_context		*ctx;
+
+	int				autodim_ms;
+	int				off_ms;
+
+	struct lws_led_state		*bl_lcs;
+
+	lws_led_state_chs_t		chs;
+	/* set of sequencer transition channels */
+
+	enum lws_display_controller_state state;
+
+} lws_display_state_t;
+
+/**
+ * lws_display_state_init() - initialize display states
+ *
+ * \param lds: the display state object
+ * \param ctx: the lws context
+ * \param autodim_ms: ms since last active report to dim display (<0 = never)
+ * \param off_ms: ms since dim to turn display off (<0 = never)
+ * \param bl_lcs: the led controller instance that has the backlight
+ * \param disp: generic display object we belong to
+ *
+ * This initializes a display's state, and sets up the optional screen auto-dim
+ * and blanking on inactive, and gradual brightness change timer.
+ *
+ *  - auto-dim then off: set autodim to some ms and off_ms to some ms
+ *  - auto-dim only: set autodim to some ms and off_ms to -1
+ *  - off-only: set autodim to some ms and off_ms to 0
+ *  - neither: set both autodim and off_ms to -1
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_display_state_init(lws_display_state_t *lds, struct lws_context *ctx,
+		       int autodim_ms, int off_ms, struct lws_led_state *bl_lcs,
+		       const lws_display_t *disp);
+
+/**
+ * lws_display_state_set_brightness() - gradually change the brightness
+ *
+ * \param lds: the display state we are changing
+ * \param target: the target brightness to transition to
+ *
+ * Adjusts the brightness gradually twoards the target at 20Hz
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_display_state_set_brightness(lws_display_state_t *lds,
+				 const lws_led_sequence_def_t *pwmseq);
+
+/*
+ * lws_display_state_active() - inform the system the display is active
+ *
+ * \param lds: the display state we are marking as active
+ *
+ * Resets the auto-dim and auto-off timers and makes sure the display is on and
+ * at the active brightness level
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_display_state_active(lws_display_state_t *lds);
+
+/*
+ * lws_display_state_off() - turns off the related display
+ *
+ * \param lds: the display state we are turning off
+ *
+ * Turns the display to least power mode or completely off if possible.
+ * Disables the timers related to dimming and blanking.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_display_state_off(lws_display_state_t *lds);
+
+#endif

include/libwebsockets/lws-dll2.h

@@ -0,0 +1,305 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup ll linked-lists
+* ##Linked list apis
+*
+* simple single and doubly-linked lists
+*/
+///@{
+
+/**
+ * lws_start_foreach_ll(): linkedlist iterator helper start
+ *
+ * \param type: type of iteration, eg, struct xyz *
+ * \param it: iterator var name to create
+ * \param start: start of list
+ *
+ * This helper creates an iterator and starts a while (it) {
+ * loop.  The iterator runs through the linked list starting at start and
+ * ends when it gets a NULL.
+ * The while loop should be terminated using lws_start_foreach_ll().
+ */
+#define lws_start_foreach_ll(type, it, start)\
+{ \
+	type it = start; \
+	while (it) {
+
+/**
+ * lws_end_foreach_ll(): linkedlist iterator helper end
+ *
+ * \param it: same iterator var name given when starting
+ * \param nxt: member name in the iterator pointing to next list element
+ *
+ * This helper is the partner for lws_start_foreach_ll() that ends the
+ * while loop.
+ */
+
+#define lws_end_foreach_ll(it, nxt) \
+		it = it->nxt; \
+	} \
+}
+
+/**
+ * lws_start_foreach_ll_safe(): linkedlist iterator helper start safe against delete
+ *
+ * \param type: type of iteration, eg, struct xyz *
+ * \param it: iterator var name to create
+ * \param start: start of list
+ * \param nxt: member name in the iterator pointing to next list element
+ *
+ * This helper creates an iterator and starts a while (it) {
+ * loop.  The iterator runs through the linked list starting at start and
+ * ends when it gets a NULL.
+ * The while loop should be terminated using lws_end_foreach_ll_safe().
+ * Performs storage of next increment for situations where iterator can become invalidated
+ * during iteration.
+ */
+#define lws_start_foreach_ll_safe(type, it, start, nxt)\
+{ \
+	type it = start; \
+	while (it) { \
+		type next_##it = it->nxt;
+
+/**
+ * lws_end_foreach_ll_safe(): linkedlist iterator helper end (pre increment storage)
+ *
+ * \param it: same iterator var name given when starting
+ *
+ * This helper is the partner for lws_start_foreach_ll_safe() that ends the
+ * while loop. It uses the precreated next_ variable already stored during
+ * start.
+ */
+
+#define lws_end_foreach_ll_safe(it) \
+		it = next_##it; \
+	} \
+}
+
+/**
+ * lws_start_foreach_llp(): linkedlist pointer iterator helper start
+ *
+ * \param type: type of iteration, eg, struct xyz **
+ * \param it: iterator var name to create
+ * \param start: start of list
+ *
+ * This helper creates an iterator and starts a while (it) {
+ * loop.  The iterator runs through the linked list starting at the
+ * address of start and ends when it gets a NULL.
+ * The while loop should be terminated using lws_start_foreach_llp().
+ *
+ * This helper variant iterates using a pointer to the previous linked-list
+ * element.  That allows you to easily delete list members by rewriting the
+ * previous pointer to the element's next pointer.
+ */
+#define lws_start_foreach_llp(type, it, start)\
+{ \
+	type it = &(start); \
+	while (*(it)) {
+
+#define lws_start_foreach_llp_safe(type, it, start, nxt)\
+{ \
+	type it = &(start); \
+	type next; \
+	while (*(it)) { \
+		next = &((*(it))->nxt); \
+
+/**
+ * lws_end_foreach_llp(): linkedlist pointer iterator helper end
+ *
+ * \param it: same iterator var name given when starting
+ * \param nxt: member name in the iterator pointing to next list element
+ *
+ * This helper is the partner for lws_start_foreach_llp() that ends the
+ * while loop.
+ */
+
+#define lws_end_foreach_llp(it, nxt) \
+		it = &(*(it))->nxt; \
+	} \
+}
+
+#define lws_end_foreach_llp_safe(it) \
+		it = next; \
+	} \
+}
+
+#define lws_ll_fwd_insert(\
+	___new_object,	/* pointer to new object */ \
+	___m_list,	/* member for next list object ptr */ \
+	___list_head	/* list head */ \
+		) {\
+		___new_object->___m_list = ___list_head; \
+		___list_head = ___new_object; \
+	}
+
+#define lws_ll_fwd_remove(\
+	___type,	/* type of listed object */ \
+	___m_list,	/* member for next list object ptr */ \
+	___target,	/* object to remove from list */ \
+	___list_head	/* list head */ \
+	) { \
+                lws_start_foreach_llp(___type **, ___ppss, ___list_head) { \
+                        if (*___ppss == ___target) { \
+                                *___ppss = ___target->___m_list; \
+                                break; \
+                        } \
+                } lws_end_foreach_llp(___ppss, ___m_list); \
+	}
+
+
+/*
+ * doubly linked-list
+ */
+
+/*
+ * lws_dll2_owner / lws_dll2 : more capable version of lws_dll.  Differences:
+ *
+ *  - there's an explicit lws_dll2_owner struct which holds head, tail and
+ *    count of members.
+ *
+ *  - list members all hold a pointer to their owner.  So user code does not
+ *    have to track anything about exactly what lws_dll2_owner list the object
+ *    is a member of.
+ *
+ *  - you can use lws_dll unless you want the member count or the ability to
+ *    not track exactly which list it's on.
+ *
+ *  - layout is compatible with lws_dll (but lws_dll apis will not update the
+ *    new stuff)
+ */
+
+
+struct lws_dll2;
+struct lws_dll2_owner;
+
+typedef struct lws_dll2 {
+	struct lws_dll2		*prev;
+	struct lws_dll2		*next;
+	struct lws_dll2_owner	*owner;
+} lws_dll2_t;
+
+typedef struct lws_dll2_owner {
+	struct lws_dll2		*tail;
+	struct lws_dll2		*head;
+
+	uint32_t		count;
+} lws_dll2_owner_t;
+
+LWS_VISIBLE LWS_EXTERN int
+lws_dll2_is_detached(const struct lws_dll2 *d);
+
+static LWS_INLINE const struct lws_dll2_owner *
+lws_dll2_owner(const struct lws_dll2 *d) { return d->owner; }
+
+static LWS_INLINE struct lws_dll2 *
+lws_dll2_get_head(struct lws_dll2_owner *owner) { return owner->head; }
+
+static LWS_INLINE struct lws_dll2 *
+lws_dll2_get_tail(struct lws_dll2_owner *owner) { return owner->tail; }
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_add_head(struct lws_dll2 *d, struct lws_dll2_owner *owner);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_add_tail(struct lws_dll2 *d, struct lws_dll2_owner *owner);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_remove(struct lws_dll2 *d);
+
+typedef int (*lws_dll2_foreach_cb_t)(struct lws_dll2 *d, void *user);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_dll2_foreach_safe(struct lws_dll2_owner *owner, void *user,
+		      lws_dll2_foreach_cb_t cb);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_clear(struct lws_dll2 *d);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_owner_clear(struct lws_dll2_owner *d);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_add_before(struct lws_dll2 *d, struct lws_dll2 *after);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_add_sorted(lws_dll2_t *d, lws_dll2_owner_t *own,
+		    int (*compare)(const lws_dll2_t *d, const lws_dll2_t *i));
+
+LWS_VISIBLE LWS_EXTERN void
+lws_dll2_add_sorted_priv(lws_dll2_t *d, lws_dll2_owner_t *own, void *priv,
+			 int (*compare3)(void *priv, const lws_dll2_t *d,
+					 const lws_dll2_t *i));
+
+LWS_VISIBLE LWS_EXTERN void *
+_lws_dll2_search_sz_pl(lws_dll2_owner_t *own, const char *name, size_t namelen,
+		      size_t dll2_ofs, size_t ptr_ofs);
+
+/*
+ * Searches objects in an owner list linearly and returns one with a given
+ * member C-string matching a supplied length-provided string if it exists, else
+ * NULL.
+ */
+
+#define lws_dll2_search_sz_pl(own, name, namelen, type, membd2list, membptr) \
+		((type *)_lws_dll2_search_sz_pl(own, name, namelen, \
+				       offsetof(type, membd2list), \
+				       offsetof(type, membptr)))
+
+#if defined(_DEBUG)
+void
+lws_dll2_describe(struct lws_dll2_owner *owner, const char *desc);
+#else
+#define lws_dll2_describe(x, y)
+#endif
+
+/*
+ * these are safe against the current container object getting deleted,
+ * since the hold his next in a temp and go to that next.  ___tmp is
+ * the temp.
+ */
+
+#define lws_start_foreach_dll_safe(___type, ___it, ___tmp, ___start) \
+{ \
+	___type ___it = ___start; \
+	while (___it) { \
+		___type ___tmp = (___it)->next;
+
+#define lws_end_foreach_dll_safe(___it, ___tmp) \
+		___it = ___tmp; \
+	} \
+}
+
+#define lws_start_foreach_dll(___type, ___it, ___start) \
+{ \
+	___type ___it = ___start; \
+	while (___it) {
+
+#define lws_end_foreach_dll(___it) \
+		___it = (___it)->next; \
+	} \
+}
+
+///@}
+

include/libwebsockets/lws-dsh.h

@@ -0,0 +1,148 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*
+ * lws_dsh (Disordered Shared Heap) is an opaque abstraction supporting a single
+ * linear buffer (overallocated at end of the lws_dsh_t) which may contain
+ * multiple kinds of packets that are retired out of order, and tracked by kind.
+ *
+ * Each kind of packet has an lws_dll2 list of its kind of packets and acts as
+ * a FIFO; packets of a particular type are always retired in order.  But there
+ * is no requirement about the order types are retired matching the original
+ * order they arrived.
+ * 
+ * Gaps are tracked as just another kind of "packet" list.
+ *
+ * "allocations" (including gaps) are prepended by an lws_dsh_object_t.
+ *
+ * dsh may themselves be on an lws_dll2_owner list, and under memory pressure
+ * allocate into other buffers on the list.
+ *
+ * All management structures exist inside the allocated buffer.
+ */
+
+/**
+ * lws_dsh_create() - Allocate a DSH buffer
+ *
+ * \param owner: the owning list this dsh belongs on, or NULL if standalone
+ * \param buffer_size: the allocation in bytes
+ * \param count_kinds: how many separately-tracked fifos use the buffer
+ *
+ * This makes a single heap allocation that includes internal tracking objects
+ * in the buffer.  Sub-allocated objects are bound to a "kind" index and
+ * managed via a FIFO for each kind.
+ *
+ * Every "kind" of allocation shares the same buffer space.
+ *
+ * Multiple buffers may be bound together in an lws_dll2 list, and if an
+ * allocation cannot be satisfied by the local buffer, space can be borrowed
+ * from other dsh in the same list (the local dsh FIFO tracks these "foreign"
+ * allocations as if they were local).
+ *
+ * Returns an opaque pointer to the dsh, or NULL if allocation failed.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_dsh *
+lws_dsh_create(lws_dll2_owner_t *owner, size_t buffer_size, int count_kinds);
+
+/**
+ * lws_dsh_destroy() - Destroy a DSH buffer
+ *
+ * \param pdsh: pointer to the dsh pointer
+ *
+ * Deallocates the DSH and sets *pdsh to NULL.
+ *
+ * Before destruction, any foreign buffer usage on the part of this dsh are
+ * individually freed.  All dsh on the same list are walked and checked if they
+ * have their own foreign allocations on the dsh buffer being destroyed.  If so,
+ * it attempts to migrate the allocation to a dsh that is not currently being
+ * destroyed.  If all else fails (basically the buffer memory is being shrunk)
+ * unmigratable objects are cleanly destroyed.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_dsh_destroy(struct lws_dsh **pdsh);
+
+/**
+ * lws_dsh_alloc_tail() - make a suballocation inside a dsh
+ *
+ * \param dsh: the dsh tracking the allocation
+ * \param kind: the kind of allocation
+ * \param src1: the first source data to copy
+ * \param size1: the size of the first source data
+ * \param src2: the second source data to copy (after the first), or NULL
+ * \param size2: the size of the second source data
+ *
+ * Allocates size1 + size2 bytes in a dsh (it prefers the given dsh but will
+ * borrow space from other dsh on the same list if necessary) and copies size1
+ * bytes into it from src1, followed by size2 bytes from src2 if src2 isn't
+ * NULL.  The actual suballocation is a bit larger because of alignment and a
+ * prepended management header.
+ *
+ * The suballocation is added to the kind-specific FIFO at the tail.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_dsh_alloc_tail(struct lws_dsh *dsh, int kind, const void *src1,
+		   size_t size1, const void *src2, size_t size2);
+
+/**
+ * lws_dsh_free() - free a suballocation from the dsh
+ *
+ * \param obj: a pointer to a void * that pointed to the allocated payload
+ *
+ * This returns the space used by \p obj in the dsh buffer to the free list
+ * of the dsh the allocation came from.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_dsh_free(void **obj);
+
+LWS_VISIBLE LWS_EXTERN size_t
+lws_dsh_get_size(struct lws_dsh *dsh, int kind);
+
+/**
+ * lws_dsh_get_head() - get the head allocation inside the dsh
+ *
+ * \param dsh: the dsh tracking the allocation
+ * \param kind: the kind of allocation
+ * \param obj: pointer to a void * to be set to the payload
+ * \param size: set to the size of the allocation
+ *
+ * This gets the "next" object in the kind FIFO for the dsh, and returns 0 if
+ * any.  If none, returns nonzero.
+ *
+ * This is nondestructive of the fifo or the payload.  Use lws_dsh_free on
+ * obj to remove the entry from the kind fifo and return the payload to the
+ * free list.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_dsh_get_head(struct lws_dsh *dsh, int kind, void **obj, size_t *size);
+
+/**
+ * lws_dsh_describe() - DEBUG BUILDS ONLY dump the dsh to the logs
+ *
+ * \param dsh: the dsh to dump
+ * \param desc: text that appears at the top of the dump
+ *
+ * Useful information for debugging lws_dsh
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_dsh_describe(struct lws_dsh *dsh, const char *desc);

include/libwebsockets/lws-eventlib-exports.h

@@ -0,0 +1,150 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * These are exports needed by event lib plugins.
+ */
+
+enum lws_event_lib_ops_flags {
+	LELOF_ISPOLL				= (1 >> 0),
+	LELOF_DESTROY_FINAL			= (1 >> 1),
+};
+
+enum {
+	LWS_EV_READ				= (1 << 0),
+	LWS_EV_WRITE				= (1 << 1),
+	LWS_EV_START				= (1 << 2),
+	LWS_EV_STOP				= (1 << 3),
+};
+
+struct lws_event_loop_ops {
+	const char *name;
+	/* event loop-specific context init during context creation */
+	int (*init_context)(struct lws_context *context,
+			    const struct lws_context_creation_info *info);
+	/* called during lws_destroy_context */
+	int (*destroy_context1)(struct lws_context *context);
+	/* called during lws_destroy_context2 */
+	int (*destroy_context2)(struct lws_context *context);
+	/* init vhost listening wsi */
+	int (*init_vhost_listen_wsi)(struct lws *wsi);
+	/* init the event loop for a pt */
+	int (*init_pt)(struct lws_context *context, void *_loop, int tsi);
+	/* called at end of first phase of close_free_wsi()  */
+	int (*wsi_logical_close)(struct lws *wsi);
+	/* return nonzero if client connect not allowed  */
+	int (*check_client_connect_ok)(struct lws *wsi);
+	/* close handle manually  */
+	void (*close_handle_manually)(struct lws *wsi);
+	/* event loop accept processing  */
+	int (*sock_accept)(struct lws *wsi);
+	/* control wsi active events  */
+	void (*io)(struct lws *wsi, unsigned int flags);
+	/* run the event loop for a pt */
+	void (*run_pt)(struct lws_context *context, int tsi);
+	/* called before pt is destroyed */
+	void (*destroy_pt)(struct lws_context *context, int tsi);
+	/* called just before wsi is freed  */
+	void (*destroy_wsi)(struct lws *wsi);
+	/* return nonzero if caller thread is not loop service thread  */
+	int (*foreign_thread)(struct lws_context *context, int tsi);
+
+	uint8_t	flags;
+
+	uint16_t	evlib_size_ctx;
+	uint16_t	evlib_size_pt;
+	uint16_t	evlib_size_vh;
+	uint16_t	evlib_size_wsi;
+};
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_evlib_wsi_to_evlib_pt(struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_evlib_tsi_to_evlib_pt(struct lws_context *ctx, int tsi);
+
+ /*
+  * You should consider these opaque for normal user code.
+  */
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_realloc(void *ptr, size_t size, const char *reason);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_vhost_destroy1(struct lws_vhost *vh);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_close_free_wsi(struct lws *wsi, enum lws_close_status reason,
+		   const char *caller);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_vhost_foreach_listen_wsi(struct lws_context *cx, void *arg,
+			     lws_dll2_foreach_cb_t cb);
+
+struct lws_context_per_thread;
+LWS_VISIBLE LWS_EXTERN void
+lws_service_do_ripe_rxflow(struct lws_context_per_thread *pt);
+
+#if !defined(wsi_from_fd) && !defined(WIN32) && !defined(_WIN32)
+struct lws_context;
+LWS_VISIBLE LWS_EXTERN struct lws *
+wsi_from_fd(const struct lws_context *context, int fd);
+#endif
+
+LWS_VISIBLE LWS_EXTERN int
+_lws_plat_service_forced_tsi(struct lws_context *context, int tsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_context_destroy2(struct lws_context *context);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_destroy_event_pipe(struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void
+__lws_close_free_wsi_final(struct lws *wsi);
+
+#if LWS_MAX_SMP > 1
+
+struct lws_mutex_refcount {
+	pthread_mutex_t lock;
+	pthread_t lock_owner;
+	const char *last_lock_reason;
+	char lock_depth;
+	char metadata;
+};
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mutex_refcount_assert_held(struct lws_mutex_refcount *mr);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mutex_refcount_init(struct lws_mutex_refcount *mr);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mutex_refcount_destroy(struct lws_mutex_refcount *mr);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mutex_refcount_lock(struct lws_mutex_refcount *mr, const char *reason);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mutex_refcount_unlock(struct lws_mutex_refcount *mr);
+
+#endif

include/libwebsockets/lws-fault-injection.h

@@ -0,0 +1,251 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * Fault injection api if built with LWS_WITH_SYS_FAULT_INJECTION
+ */
+
+typedef struct lws_xos {
+	uint64_t s[4];
+} lws_xos_t;
+
+/**
+ * lws_xos_init() - seed xoshiro256 PRNG
+ *
+ * \param xos: the prng state object to initialize
+ * \param seed: the 64-bit seed
+ *
+ * Initialize PRNG \xos with the starting state represented by \p seed
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_xos_init(struct lws_xos *xos, uint64_t seed);
+
+/**
+ * lws_xos() - get next xoshiro256 PRNG result and update state
+ *
+ * \param xos: the PRNG state to use
+ *
+ * Returns next 64-bit PRNG result.  These are cheap to get,
+ * quite a white noise sequence, and completely deterministic
+ * according to the seed it was initialized with.
+ */
+LWS_VISIBLE LWS_EXTERN uint64_t LWS_WARN_UNUSED_RESULT
+lws_xos(struct lws_xos *xos);
+
+/**
+ * lws_xos_percent() - return 1 a given percent of the time on average
+ *
+ * \param xos: the PRNG state to use
+ * \param percent: chance in 100 of returning 1
+ *
+ * Returns 1 if next random % 100 is < \p percent, such that
+ * 100 always returns 1, 0 never returns 1, and the chance linearly scales
+ * inbetween
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_xos_percent(struct lws_xos *xos, int percent);
+
+#if defined(LWS_WITH_SYS_FAULT_INJECTION)
+
+enum {
+	LWSFI_ALWAYS,
+	LWSFI_DETERMINISTIC,	/* do .count injections after .pre then stop */
+	LWSFI_PROBABILISTIC,	/* .pre % chance of injection */
+	LWSFI_PATTERN,		/* use .count bits in .pattern after .pre */
+	LWSFI_PATTERN_ALLOC,	/* as _PATTERN, but .pattern is malloc'd */
+	LWSFI_RANGE		/* pick a number between pre and count */
+};
+
+typedef struct lws_fi {
+	const char		*name;
+	const uint8_t		*pattern;
+	uint64_t		pre;
+	uint64_t		count;
+	uint64_t		times;		/* start at 0, tracks usage */
+	char			type;		/* LWSFI_* */
+} lws_fi_t;
+
+typedef struct lws_fi_ctx {
+	lws_dll2_owner_t	fi_owner;
+	struct lws_xos		xos;
+	const char		*name;
+} lws_fi_ctx_t;
+
+/**
+ * lws_fi() - find out if we should perform the named fault injection this time
+ *
+ * \param fic: fault injection tracking context
+ * \param fi_name: name of fault injection
+ *
+ * This checks if the named fault is configured in the fi tracking context
+ * provided, if it is, then it will make a decision if the named fault should
+ * be applied this time, using the tracking in the named lws_fi_t.
+ *
+ * If the provided context has a parent, that is also checked for the named fi
+ * item recursively, with the first found being used to determine if to inject
+ * or not.
+ *
+ * If LWS_WITH_SYS_FAULT_INJECTION is not defined, then this always return 0.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fi(const lws_fi_ctx_t *fic, const char *fi_name);
+
+/**
+ * lws_fi_range() - get a random number from a range
+ *
+ * \param fic: fault injection tracking context
+ * \param fi_name: name of fault injection
+ * \param result: points to uint64_t to be set to the result
+ *
+ * This lets you get a random number from an externally-set range, set using a
+ * fault injection syntax like "myfault(123..456)".  That will cause us to
+ * return a number between those two inclusive, from the seeded PRNG.
+ *
+ * This is useful when you used lws_fi() with its own fault name to decide
+ * whether to inject the fault, and then the code to cause the fault needs
+ * additional constrained pseudo-random fuzzing for, eg, delays before issuing
+ * the fault.
+ *
+ * Returns 0 if \p *result is set, else nonzero for failure.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fi_range(const lws_fi_ctx_t *fic, const char *name, uint64_t *result);
+
+/**
+ * lws_fi_add() - add an allocated copy of fault injection to a context
+ *
+ * \param fic: fault injection tracking context
+ * \param fi: the fault injection details
+ *
+ * This allocates a copy of \p fi and attaches it to the fault injection context
+ * \p fic.  \p fi can go out of scope after this safely.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fi_add(lws_fi_ctx_t *fic, const lws_fi_t *fi);
+
+/**
+ * lws_fi_remove() - remove an allocated copy of fault injection from a context
+ *
+ * \param fic: fault injection tracking context
+ * \param name: the fault injection name to remove
+ *
+ * This looks for the named fault injection and removes and destroys it from
+ * the specified fault injection context
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_fi_remove(lws_fi_ctx_t *fic, const char *name);
+
+/**
+ * lws_fi_import() - transfers all the faults from one context to another
+ *
+ * \param fic_dest: the fault context to receive the faults
+ * \param fic_src: the fault context that will be emptied out into \p fic_dest
+ *
+ * This is used to initialize created object fault injection contexts from
+ * the caller.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_fi_import(lws_fi_ctx_t *fic_dest, const lws_fi_ctx_t *fic_src);
+
+/**
+ * lws_fi_inherit_copy() - attach copies of matching fault injection objects to dest
+ *
+ * \param fic_dest: destination Fault Injection context
+ * \param fic_src: parent fault context that may contain matching rules
+ * \param scope: the name of the path match required, eg, "vh"
+ * \param value: the dynamic name of our match, eg, "myvhost"
+ *
+ * If called with scope "vh" and value "myvhost", then matches faults starting
+ * "vh=myvhost/", strips that part of the name if it matches and makes a copy
+ * of the rule with the modified name attached to the destination Fault Injection
+ * context.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_fi_inherit_copy(lws_fi_ctx_t *fic_dest, const lws_fi_ctx_t *fic_src,
+		    const char *scope, const char *value);
+
+/**
+ * lws_fi_destroy() - removes all allocated fault injection entries
+ *
+ * \param fic: fault injection tracking context
+ *
+ * This walks any allocated fault injection entries in \p fic and detaches and
+ * destroys them.  It doesn't try to destroc \p fic itself, since this is
+ * not usually directly allocated.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_fi_destroy(const lws_fi_ctx_t *fic);
+
+/**
+ * lws_fi_deserialize() - adds fault in string form to Fault Injection Context
+ *
+ * \p fic: the fault injection context
+ * \p sers: the string serializing the desired fault details
+ *
+ * This turns a string like "ss=captive_portal_detect/wsi/dnsfail(10%)" into
+ * a fault injection struct added to the fault injection context \p fic
+ *
+ * You can prepare the context creation info .fic with these before creating
+ * the context, and use namespace paths on those to target other objects.
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_fi_deserialize(lws_fi_ctx_t *fic, const char *sers);
+
+LWS_VISIBLE LWS_EXTERN int
+_lws_fi_user_wsi_fi(struct lws *wsi, const char *name);
+LWS_VISIBLE LWS_EXTERN int
+_lws_fi_user_context_fi(struct lws_context *ctx, const char *name);
+
+#if defined(LWS_WITH_SECURE_STREAMS)
+struct lws_ss_handle;
+LWS_VISIBLE LWS_EXTERN int
+_lws_fi_user_ss_fi(struct lws_ss_handle *h, const char *name);
+#if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
+struct lws_sspc_handle;
+LWS_VISIBLE LWS_EXTERN int
+_lws_fi_user_sspc_fi(struct lws_sspc_handle *h, const char *name);
+#endif
+#endif
+
+#define lws_fi_user_wsi_fi(_wsi, _name) _lws_fi_user_wsi_fi(_wsi, _name)
+#define lws_fi_user_context_fi(_ctx, _name) _lws_fi_user_context_fi(_ctx, _name)
+#define lws_fi_user_ss_fi(_h, _name) _lws_fi_user_ss_fi(_h, _name)
+#define lws_fi_user_sspc_fi(_h, _name) _lws_fi_user_sspc_fi(_h, _name)
+
+#else
+
+/*
+ * Helper so we can leave lws_fi() calls embedded in the code being tested,
+ * if fault injection is not enabled then it just always says "no" at buildtime.
+ */
+
+#define lws_fi(_fi_name, _fic) (0)
+#define lws_fi_destroy(_x)
+#define lws_fi_inherit_copy(_a, _b, _c, _d)
+#define lws_fi_deserialize(_x, _y)
+#define lws_fi_user_wsi_fi(_wsi, _name) (0)
+#define lws_fi_user_context_fi(_wsi, _name) (0)
+#define lws_fi_user_ss_fi(_h, _name) (0)
+#define lws_fi_user_sspc_fi(_h, _name) (0)
+
+#endif

include/libwebsockets/lws-freertos.h

@@ -0,0 +1,87 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is included from libwebsockets.h if LWS_PLAT_FREERTOS
+ */
+
+typedef int lws_sockfd_type;
+typedef int lws_filefd_type;
+
+#if defined(LWS_AMAZON_RTOS)
+#include <FreeRTOS.h>
+#include <event_groups.h>
+#include <string.h>
+#include "timers.h"
+#include <lwip/sockets.h>
+
+/*
+ * Later lwip (at least 2.1.12) already defines these in its own headers
+ * protected by the same test as used here... if POLLIN / POLLOUT already exist
+ * then assume no need to declare those and struct pollfd.
+ *
+ * Older lwip needs these declarations done here.
+ */
+
+#if !defined(POLLIN) && !defined(POLLOUT)
+
+struct pollfd {
+	lws_sockfd_type fd; /**< fd related to */
+	short events; /**< which POLL... events to respond to */
+	short revents; /**< which POLL... events occurred */
+};
+#define POLLIN		0x0001
+#define POLLPRI		0x0002
+#define POLLOUT		0x0004
+#define POLLERR		0x0008
+#define POLLHUP		0x0010
+#define POLLNVAL	0x0020
+
+#endif
+
+#else /* LWS_AMAZON_RTOS */
+#include <freertos/FreeRTOS.h>
+#include <freertos/event_groups.h>
+#include <string.h>
+#include "esp_wifi.h"
+#include "esp_system.h"
+#include "esp_event.h"
+//#include "esp_event_loop.h"
+#include "nvs.h"
+#include "driver/gpio.h"
+#include "esp_spi_flash.h"
+#include "freertos/timers.h"
+
+#if defined(LWS_ESP_PLATFORM)
+#include "lwip/sockets.h"
+#include "lwip/netdb.h"
+#if defined(LWS_WITH_DRIVERS)
+#include "libwebsockets/lws-gpio.h"
+extern const lws_gpio_ops_t lws_gpio_plat;
+#endif
+#endif
+
+#endif /* LWS_AMAZON_RTOS */
+
+#if !defined(CONFIG_FREERTOS_HZ)
+#define CONFIG_FREERTOS_HZ 100
+#endif

include/libwebsockets/lws-fts.h

@@ -0,0 +1,215 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup search Search
+ *
+ * ##Full-text search
+ *
+ * Lws provides superfast indexing and fulltext searching from index files on
+ * storage.
+ */
+///@{
+
+struct lws_fts;
+struct lws_fts_file;
+
+/*
+ * Queries produce their results in an lwsac, using these public API types.
+ * The first thing in the lwsac is always a struct lws_fts_result (see below)
+ * containing heads for linked-lists of the other result types.
+ */
+
+/* one filepath's results */
+
+struct lws_fts_result_filepath {
+	struct lws_fts_result_filepath *next;
+	int matches;	/* logical number of matches */
+	int matches_length;	/* bytes in length table (may be zero) */
+	int lines_in_file;
+	int filepath_length;
+
+	/* - uint32_t line table follows (first for alignment) */
+	/* - filepath (of filepath_length) follows */
+};
+
+/* autocomplete result */
+
+struct lws_fts_result_autocomplete {
+	struct lws_fts_result_autocomplete *next;
+	int instances;
+	int agg_instances;
+	int ac_length;
+	char elided; /* children skipped in interest of antecedent children */
+	char has_children;
+
+	/* - autocomplete suggestion (of length ac_length) follows */
+};
+
+/*
+ * The results lwsac always starts with this.  If no results and / or no
+ * autocomplete the members may be NULL.  This implies the symbol nor any
+ * suffix on it exists in the trie file.
+ */
+struct lws_fts_result {
+	struct lws_fts_result_filepath *filepath_head;
+	struct lws_fts_result_autocomplete *autocomplete_head;
+	int duration_ms;
+	int effective_flags; /* the search flags that were used */
+};
+
+/*
+ * index creation functions
+ */
+
+/**
+ * lws_fts_create() - Create a new index file
+ *
+ * \param fd: The fd opened for write
+ *
+ * Inits a new index file, returning a struct lws_fts to represent it
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_fts *
+lws_fts_create(int fd);
+
+/**
+ * lws_fts_destroy() - Finalize a new index file / destroy the trie lwsac
+ *
+ * \param trie: The previously opened index being finalized
+ *
+ * Finalizes an index file that was being created, and frees the memory involved
+ * *trie is set to NULL afterwards.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_fts_destroy(struct lws_fts **trie);
+
+/**
+ * lws_fts_file_index() - Create a new entry in the trie file for an input path
+ *
+ * \param t: The previously opened index being written
+ * \param filepath: The filepath (which may be virtual) associated with this file
+ * \param filepath_len: The number of chars in the filepath
+ * \param priority: not used yet
+ *
+ * Returns an ordinal that represents this new filepath in the index file.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fts_file_index(struct lws_fts *t, const char *filepath, int filepath_len,
+		   int priority);
+
+/**
+ * lws_fts_fill() - Process all or a bufferload of input file
+ *
+ * \param t: The previously opened index being written
+ * \param file_index: The ordinal representing this input filepath
+ * \param buf: A bufferload of data from the input file
+ * \param len: The number of bytes in buf
+ *
+ * Indexes a buffer of data from the input file.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fts_fill(struct lws_fts *t, uint32_t file_index, const char *buf,
+	     size_t len);
+
+/**
+ * lws_fts_serialize() - Store the in-memory trie into the index file
+ *
+ * \param t: The previously opened index being written
+ *
+ * The trie is held in memory where it can be added to... after all the input
+ * filepaths and data have been processed, this is called to serialize /
+ * write the trie data into the index file.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fts_serialize(struct lws_fts *t);
+
+/*
+ * index search functions
+ */
+
+/**
+ * lws_fts_open() - Open an existing index file to search it
+ *
+ * \param filepath: The filepath to the index file to open
+ *
+ * Opening the index file returns an opaque struct lws_fts_file * that is
+ * used to perform other operations on it, or NULL if it can't be opened.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_fts_file *
+lws_fts_open(const char *filepath);
+
+#define LWSFTS_F_QUERY_AUTOCOMPLETE	(1 << 0)
+#define LWSFTS_F_QUERY_FILES		(1 << 1)
+#define LWSFTS_F_QUERY_FILE_LINES	(1 << 2)
+#define LWSFTS_F_QUERY_QUOTE_LINE	(1 << 3)
+
+struct lws_fts_search_params {
+	/* the actual search term */
+	const char *needle;
+	 /* if non-NULL, FILE results for this filepath only */
+	const char *only_filepath;
+	/* will be set to the results lwsac */
+	struct lwsac *results_head;
+	/* combination of LWSFTS_F_QUERY_* flags */
+	int flags;
+	/* maximum number of autocomplete suggestions to return */
+	int max_autocomplete;
+	/* maximum number of filepaths to return */
+	int max_files;
+	/* maximum number of line number results to return per filepath */
+	int max_lines;
+};
+
+/**
+ * lws_fts_search() - Perform a search operation on an index
+ *
+ * \param jtf: The index file struct returned by lws_fts_open
+ * \param ftsp: The struct lws_fts_search_params filled in by the caller
+ *
+ * The caller should memset the ftsp struct to 0 to ensure members that may be
+ * introduced in later versions contain known values, then set the related
+ * members to describe the kind of search action required.
+ *
+ * ftsp->results_head is the results lwsac, or NULL.  It should be freed with
+ * lwsac_free() when the results are finished with.
+ *
+ * Returns a pointer into the results lwsac that is a struct lws_fts_result
+ * containing the head pointers into linked-lists of results for autocomplete
+ * and filepath data, along with some sundry information.  This does not need
+ * to be freed since freeing the lwsac will also remove this and everything it
+ * points to.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_fts_result *
+lws_fts_search(struct lws_fts_file *jtf, struct lws_fts_search_params *ftsp);
+
+/**
+ * lws_fts_close() - Close a previously-opened index file
+ *
+ * \param jtf: The pointer returned from the open
+ *
+ * Closes the file handle on the index and frees any allocations
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_fts_close(struct lws_fts_file *jtf);
+
+///@}

include/libwebsockets/lws-genaes.h

@@ -0,0 +1,170 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup generic AES
+ * ## Generic AES related functions
+ *
+ * Lws provides generic AES functions that abstract the ones
+ * provided by whatever tls library you are linking against.
+ *
+ * It lets you use the same code if you build against mbedtls or OpenSSL
+ * for example.
+ */
+///@{
+
+#if defined(LWS_WITH_MBEDTLS)
+#include <mbedtls/aes.h>
+#include <mbedtls/gcm.h>
+#endif
+
+enum enum_aes_modes {
+	LWS_GAESM_CBC,
+	LWS_GAESM_CFB128,
+	LWS_GAESM_CFB8,
+	LWS_GAESM_CTR,
+	LWS_GAESM_ECB,
+	LWS_GAESM_OFB,
+	LWS_GAESM_XTS,		/* care... requires double-length key */
+	LWS_GAESM_GCM,
+	LWS_GAESM_KW,
+};
+
+enum enum_aes_operation {
+	LWS_GAESO_ENC,
+	LWS_GAESO_DEC
+};
+
+enum enum_aes_padding {
+	LWS_GAESP_NO_PADDING,
+	LWS_GAESP_WITH_PADDING
+};
+
+/* include/libwebsockets/lws-jwk.h must be included before this */
+
+#define LWS_AES_BLOCKSIZE 128
+#define LWS_AES_CBC_BLOCKLEN 16
+
+struct lws_genaes_ctx {
+#if defined(LWS_WITH_MBEDTLS)
+	union {
+		mbedtls_aes_context ctx;
+#if defined(MBEDTLS_CIPHER_MODE_XTS)
+		mbedtls_aes_xts_context ctx_xts;
+#endif
+		mbedtls_gcm_context ctx_gcm;
+	} u;
+#else
+	EVP_CIPHER_CTX *ctx;
+	const EVP_CIPHER *cipher;
+	ENGINE *engine;
+	char init;
+#endif
+	unsigned char tag[16];
+	struct lws_gencrypto_keyelem *k;
+	enum enum_aes_operation op;
+	enum enum_aes_modes mode;
+	enum enum_aes_padding padding;
+	int taglen;
+	char underway;
+};
+
+/** lws_genaes_create() - Create RSA public decrypt context
+ *
+ * \param ctx: your struct lws_genaes_ctx
+ * \param op: LWS_GAESO_ENC or LWS_GAESO_DEC
+ * \param mode: one of LWS_GAESM_
+ * \param el: struct prepared with key element data
+ * \param padding: 0 = no padding, 1 = padding
+ * \param engine: if openssl engine used, pass the pointer here
+ *
+ * Creates an RSA context with a public key associated with it, formed from
+ * the key elements in \p el.
+ *
+ * Returns 0 for OK or nonzero for error.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genaes_create(struct lws_genaes_ctx *ctx, enum enum_aes_operation op,
+		  enum enum_aes_modes mode, struct lws_gencrypto_keyelem *el,
+		  enum enum_aes_padding padding, void *engine);
+
+/** lws_genaes_destroy() - Destroy genaes AES context
+ *
+ * \param ctx: your struct lws_genaes_ctx
+ * \param tag: NULL, or, GCM-only: buffer to receive tag
+ * \param tlen: 0, or, GCM-only: length of tag buffer
+ *
+ * Destroys any allocations related to \p ctx.
+ *
+ * For GCM only, up to tlen bytes of tag buffer will be set on exit.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genaes_destroy(struct lws_genaes_ctx *ctx, unsigned char *tag, size_t tlen);
+
+/** lws_genaes_crypt() - Encrypt or decrypt
+ *
+ * \param ctx: your struct lws_genaes_ctx
+ * \param in: input plaintext or ciphertext
+ * \param len: length of input (which is always length of output)
+ * \param out: output plaintext or ciphertext
+ * \param iv_or_nonce_ctr_or_data_unit_16: NULL, iv, nonce_ctr16, or data_unit16
+ * \param stream_block_16: pointer to 16-byte stream block for CTR mode only
+ * \param nc_or_iv_off: NULL or pointer to nc, or iv_off
+ * \param taglen: length of tag
+ *
+ * Encrypts or decrypts using the AES mode set when the ctx was created.
+ * The last three arguments have different meanings depending on the mode:
+ *
+ * 			      KW   CBC  CFB128 CFB8 CTR    ECB  OFB    XTS
+ * iv_or_nonce_ct.._unit_16 : iv   iv   iv     iv   nonce  NULL iv     dataunt
+ * stream_block_16	    : NULL NULL NULL   NULL stream NULL NULL   NULL
+ * nc_or_iv_off		    : NULL NULL iv_off NULL nc_off NULL iv_off NULL
+ *
+ * For GCM:
+ *
+ * iv_or_nonce_ctr_or_data_unit_16 : iv
+ * stream_block_16		   : pointer to tag
+ * nc_or_iv_off			   : set pointed-to size_t to iv length
+ * in				   : first call: additional data, subsequently
+ *				   :   input data
+ * len				   : first call: add data length, subsequently
+ *				   :   input / output length
+ *
+ * The length of the optional arg is always 16 if used, regardless of the mode.
+ *
+ * Returns 0 for OK or nonzero for error.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genaes_crypt(struct lws_genaes_ctx *ctx, const uint8_t *in, size_t len,
+		 uint8_t *out,
+		 uint8_t *iv_or_nonce_ctr_or_data_unit_16,
+		 uint8_t *stream_block_16,
+		 size_t *nc_or_iv_off, int taglen);
+
+///@}

include/libwebsockets/lws-gencrypto.h

@@ -0,0 +1,137 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*
+ * These are gencrypto-level constants... they are used by both JOSE and direct
+ * gencrypto code.  However while JWK relies on these, using gencrypto apis has
+ * no dependency at all on any JOSE type.
+ */
+
+enum lws_gencrypto_kty {
+	LWS_GENCRYPTO_KTY_UNKNOWN,
+
+	LWS_GENCRYPTO_KTY_OCT,
+	LWS_GENCRYPTO_KTY_RSA,
+	LWS_GENCRYPTO_KTY_EC
+};
+
+/*
+ * Keytypes where the same element name is reused must all agree to put the
+ * same-named element at the same e[] index.  It's because when used with jwk,
+ * we parse and store in incoming key data, but we may not be informed of the
+ * definitive keytype until the end.
+ */
+
+enum lws_gencrypto_oct_tok {
+	LWS_GENCRYPTO_OCT_KEYEL_K, /* note... same offset as AES K */
+
+	LWS_GENCRYPTO_OCT_KEYEL_COUNT
+};
+
+enum lws_gencrypto_rsa_tok {
+	LWS_GENCRYPTO_RSA_KEYEL_E,
+	LWS_GENCRYPTO_RSA_KEYEL_N,
+	LWS_GENCRYPTO_RSA_KEYEL_D, /* note... same offset as EC D */
+	LWS_GENCRYPTO_RSA_KEYEL_P,
+	LWS_GENCRYPTO_RSA_KEYEL_Q,
+	LWS_GENCRYPTO_RSA_KEYEL_DP,
+	LWS_GENCRYPTO_RSA_KEYEL_DQ,
+	LWS_GENCRYPTO_RSA_KEYEL_QI,
+
+	/* we don't actively use these if given, but may come from COSE */
+
+	LWS_GENCRYPTO_RSA_KEYEL_OTHER,
+	LWS_GENCRYPTO_RSA_KEYEL_RI,
+	LWS_GENCRYPTO_RSA_KEYEL_DI,
+	LWS_GENCRYPTO_RSA_KEYEL_TI,
+
+	LWS_GENCRYPTO_RSA_KEYEL_COUNT
+};
+
+enum lws_gencrypto_ec_tok {
+	LWS_GENCRYPTO_EC_KEYEL_CRV,
+	LWS_GENCRYPTO_EC_KEYEL_X,
+	/* note... same offset as RSA D */
+	LWS_GENCRYPTO_EC_KEYEL_D = LWS_GENCRYPTO_RSA_KEYEL_D,
+	LWS_GENCRYPTO_EC_KEYEL_Y,
+
+	LWS_GENCRYPTO_EC_KEYEL_COUNT
+};
+
+enum lws_gencrypto_aes_tok {
+	/* note... same offset as OCT K */
+	LWS_GENCRYPTO_AES_KEYEL_K = LWS_GENCRYPTO_OCT_KEYEL_K,
+
+	LWS_GENCRYPTO_AES_KEYEL_COUNT
+};
+
+/* largest number of key elements for any algorithm */
+#define LWS_GENCRYPTO_MAX_KEYEL_COUNT LWS_GENCRYPTO_RSA_KEYEL_COUNT
+
+/* this "stretchy" type holds individual key element data in binary form.
+ * It's typcially used in an array with the layout mapping the element index to
+ * the key element meaning defined by the enums above.  An array of these of
+ * length LWS_GENCRYPTO_MAX_KEYEL_COUNT can define key elements for any key
+ * type.
+ */
+
+typedef struct lws_gencrypto_keyelem {
+	uint8_t *buf;
+	uint32_t len;
+} lws_gc_elem_t;
+
+
+/**
+ * lws_gencrypto_bits_to_bytes() - returns rounded up bytes needed for bits
+ *
+ * \param bits
+ *
+ * Returns the number of bytes needed to store the given number of bits.  If
+ * a byte is partially used, the byte count is rounded up.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_gencrypto_bits_to_bytes(int bits);
+
+/**
+ * lws_base64_size() - returns estimated size of base64 encoding
+ *
+ * \param bytes
+ *
+ * Returns a slightly oversize estimate of the size of a base64 encoded version
+ * of the given amount of unencoded data.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_base64_size(int bytes);
+
+/**
+ * lws_gencrypto_padded_length() - returns PKCS#5/#7 padded length
+ *
+ * @param blocksize - blocksize to pad to
+ * @param len - Length of input to pad
+ *
+ * Returns the length of a buffer originally of size len after PKCS#5 or PKCS#7
+ * padding has been applied to it.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_gencrypto_padded_length(size_t block_size, size_t len);

include/libwebsockets/lws-genec.h

@@ -0,0 +1,211 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+enum enum_genec_alg {
+	LEGENEC_UNKNOWN,
+
+	LEGENEC_ECDH,
+	LEGENEC_ECDSA
+};
+
+struct lws_genec_ctx {
+#if defined(LWS_WITH_MBEDTLS)
+	union {
+		mbedtls_ecdh_context *ctx_ecdh;
+		mbedtls_ecdsa_context *ctx_ecdsa;
+	} u;
+#else
+	EVP_PKEY_CTX *ctx[2];
+#endif
+	struct lws_context *context;
+	const struct lws_ec_curves *curve_table;
+	enum enum_genec_alg genec_alg;
+
+	char has_private;
+};
+
+#if defined(LWS_WITH_MBEDTLS)
+enum enum_lws_dh_side {
+	LDHS_OURS = MBEDTLS_ECDH_OURS,
+	LDHS_THEIRS = MBEDTLS_ECDH_THEIRS
+};
+#else
+enum enum_lws_dh_side {
+	LDHS_OURS,
+	LDHS_THEIRS
+};
+#endif
+
+struct lws_ec_curves {
+	const char *name;
+	int tls_lib_nid;
+	uint16_t key_bytes;
+};
+
+
+/* ECDH-specific apis */
+
+/** lws_genecdh_create() - Create a genecdh
+ *
+ * \param ctx: your genec context
+ * \param context: your lws_context (for RNG access)
+ * \param curve_table: NULL, enabling P-256, P-384 and P-521, or a replacement
+ *		       struct lws_ec_curves array, terminated by an entry with
+ *		       .name = NULL, of curves you want to allow
+ *
+ * Initializes a genecdh
+ */
+LWS_VISIBLE int
+lws_genecdh_create(struct lws_genec_ctx *ctx, struct lws_context *context,
+		   const struct lws_ec_curves *curve_table);
+
+/** lws_genecdh_set_key() - Apply an EC key to our or theirs side
+ *
+ * \param ctx: your genecdh context
+ * \param el: your key elements
+ * \param side: LDHS_OURS or LDHS_THEIRS
+ *
+ * Applies an EC key to one side or the other of an ECDH ctx
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdh_set_key(struct lws_genec_ctx *ctx, struct lws_gencrypto_keyelem *el,
+		    enum enum_lws_dh_side side);
+
+/** lws_genecdh_new_keypair() - Create a genec with a new public / private key
+ *
+ * \param ctx: your genec context
+ * \param side: LDHS_OURS or LDHS_THEIRS
+ * \param curve_name: an EC curve name, like "P-256"
+ * \param el: array pf LWS_GENCRYPTO_EC_KEYEL_COUNT key elems to take the new key
+ *
+ * Creates a genecdh with a newly minted EC public / private key
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdh_new_keypair(struct lws_genec_ctx *ctx, enum enum_lws_dh_side side,
+		        const char *curve_name, struct lws_gencrypto_keyelem *el);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdh_compute_shared_secret(struct lws_genec_ctx *ctx, uint8_t *ss,
+		  int *ss_len);
+
+
+/* ECDSA-specific apis */
+
+/** lws_genecdsa_create() - Create a genecdsa and
+ *
+ * \param ctx: your genec context
+ * \param context: your lws_context (for RNG access)
+ * \param curve_table: NULL, enabling P-256, P-384 and P-521, or a replacement
+ *		       struct lws_ec_curves array, terminated by an entry with
+ *		       .name = NULL, of curves you want to allow
+ *
+ * Initializes a genecdh
+ */
+LWS_VISIBLE int
+lws_genecdsa_create(struct lws_genec_ctx *ctx, struct lws_context *context,
+		    const struct lws_ec_curves *curve_table);
+
+/** lws_genecdsa_new_keypair() - Create a genecdsa with a new public / private key
+ *
+ * \param ctx: your genec context
+ * \param curve_name: an EC curve name, like "P-256"
+ * \param el: array pf LWS_GENCRYPTO_EC_KEYEL_COUNT key elements to take the new key
+ *
+ * Creates a genecdsa with a newly minted EC public / private key
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdsa_new_keypair(struct lws_genec_ctx *ctx, const char *curve_name,
+			 struct lws_gencrypto_keyelem *el);
+
+/** lws_genecdsa_set_key() - Apply an EC key to an ecdsa context
+ *
+ * \param ctx: your genecdsa context
+ * \param el: your key elements
+ *
+ * Applies an EC key to an ecdsa context
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdsa_set_key(struct lws_genec_ctx *ctx,
+		     const struct lws_gencrypto_keyelem *el);
+
+/** lws_genecdsa_hash_sig_verify_jws() - Verifies a JWS ECDSA signature on a given hash
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: unencrypted payload (usually a recomputed hash)
+ * \param hash_type: one of LWS_GENHASH_TYPE_
+ * \param keybits: number of bits in the crypto key
+ * \param sig: pointer to the signature we received with the payload
+ * \param sig_len: length of the signature we are checking in bytes
+ *
+ * This just looks at the signed hash... that's why there's no input length
+ * parameter, it's decided by the choice of hash.  It's up to you to confirm
+ * separately the actual payload matches the hash that was confirmed by this to
+ * be validly signed.
+ *
+ * Returns <0 for error, or 0 if signature matches the hash + key..
+ *
+ * The JWS ECDSA signature verification algorithm differs to generic ECDSA
+ * signatures and they're not interoperable.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdsa_hash_sig_verify_jws(struct lws_genec_ctx *ctx, const uint8_t *in,
+				 enum lws_genhash_types hash_type, int keybits,
+				 const uint8_t *sig, size_t sig_len);
+
+/** lws_genecdsa_hash_sign_jws() - Creates a JWS ECDSA signature for a hash you provide
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: precomputed hash
+ * \param hash_type: one of LWS_GENHASH_TYPE_
+ * \param keybits: number of bits in the crypto key
+ * \param sig: pointer to buffer to take signature
+ * \param sig_len: length of the buffer (must be >= length of key N)
+ *
+ * Returns <0 for error, or >=0 for success.
+ *
+ * This creates a JWS ECDSA signature for a hash you already computed and provide.
+ *
+ * The JWS ECDSA signature generation algorithm differs to generic ECDSA
+ * signatures and they're not interoperable.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genecdsa_hash_sign_jws(struct lws_genec_ctx *ctx, const uint8_t *in,
+			   enum lws_genhash_types hash_type, int keybits,
+			   uint8_t *sig, size_t sig_len);
+
+
+/* Apis that apply to both ECDH and ECDSA */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_genec_destroy(struct lws_genec_ctx *ctx);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_genec_destroy_elements(struct lws_gencrypto_keyelem *el);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_genec_dump(struct lws_gencrypto_keyelem *el);

include/libwebsockets/lws-genhash.h

@@ -0,0 +1,189 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup generichash Generic Hash
+ * ## Generic Hash related functions
+ *
+ * Lws provides generic hash / digest accessors that abstract the ones
+ * provided by whatever tls library you are linking against.
+ *
+ * It lets you use the same code if you build against mbedtls or OpenSSL
+ * for example.
+ */
+///@{
+
+enum lws_genhash_types {
+	LWS_GENHASH_TYPE_UNKNOWN,
+	LWS_GENHASH_TYPE_MD5,
+	LWS_GENHASH_TYPE_SHA1,
+	LWS_GENHASH_TYPE_SHA256,
+	LWS_GENHASH_TYPE_SHA384,
+	LWS_GENHASH_TYPE_SHA512,
+};
+
+enum lws_genhmac_types {
+	LWS_GENHMAC_TYPE_UNKNOWN,
+	LWS_GENHMAC_TYPE_SHA256,
+	LWS_GENHMAC_TYPE_SHA384,
+	LWS_GENHMAC_TYPE_SHA512,
+};
+
+#define LWS_GENHASH_LARGEST 64
+
+struct lws_genhash_ctx {
+        uint8_t type;
+#if defined(LWS_WITH_MBEDTLS)
+        union {
+		mbedtls_md5_context md5;
+        	mbedtls_sha1_context sha1;
+		mbedtls_sha256_context sha256;
+		mbedtls_sha512_context sha512; /* 384 also uses this */
+		const mbedtls_md_info_t *hmac;
+        } u;
+#else
+        const EVP_MD *evp_type;
+        EVP_MD_CTX *mdctx;
+#endif
+};
+
+struct lws_genhmac_ctx {
+        uint8_t type;
+#if defined(LWS_WITH_MBEDTLS)
+	const mbedtls_md_info_t *hmac;
+	mbedtls_md_context_t ctx;
+#else
+	const EVP_MD *evp_type;
+
+#if defined(LWS_HAVE_EVP_PKEY_new_raw_private_key)
+	EVP_MD_CTX *ctx;
+	EVP_PKEY *key;
+#else
+#if defined(LWS_HAVE_HMAC_CTX_new)
+        HMAC_CTX *ctx;
+#else
+        HMAC_CTX ctx;
+#endif
+#endif
+
+#endif
+};
+
+/** lws_genhash_size() - get hash size in bytes
+ *
+ * \param type:	one of LWS_GENHASH_TYPE_...
+ *
+ * Returns number of bytes in this type of hash, if the hash type is unknown, it
+ * will return 0.
+ */
+LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
+lws_genhash_size(enum lws_genhash_types type);
+
+/** lws_genhmac_size() - get hash size in bytes
+ *
+ * \param type:	one of LWS_GENHASH_TYPE_...
+ *
+ * Returns number of bytes in this type of hmac, if the hmac type is unknown, it
+ * will return 0.
+ */
+LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
+lws_genhmac_size(enum lws_genhmac_types type);
+
+/** lws_genhash_init() - prepare your struct lws_genhash_ctx for use
+ *
+ * \param ctx: your struct lws_genhash_ctx
+ * \param type:	one of LWS_GENHASH_TYPE_...
+ *
+ * Initializes the hash context for the type you requested
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_genhash_init(struct lws_genhash_ctx *ctx, enum lws_genhash_types type);
+
+/** lws_genhash_update() - digest len bytes of the buffer starting at in
+ *
+ * \param ctx: your struct lws_genhash_ctx
+ * \param in: start of the bytes to digest
+ * \param len: count of bytes to digest
+ *
+ * Updates the state of your hash context to reflect digesting len bytes from in
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_genhash_update(struct lws_genhash_ctx *ctx, const void *in, size_t len);
+
+/** lws_genhash_destroy() - copy out the result digest and destroy the ctx
+ *
+ * \param ctx: your struct lws_genhash_ctx
+ * \param result: NULL, or where to copy the result hash
+ *
+ * Finalizes the hash and copies out the digest.  Destroys any allocations such
+ * that ctx can safely go out of scope after calling this.
+ *
+ * NULL result is supported so that you can destroy the ctx cleanly on error
+ * conditions, where there is no valid result.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genhash_destroy(struct lws_genhash_ctx *ctx, void *result);
+
+/** lws_genhmac_init() - prepare your struct lws_genhmac_ctx for use
+ *
+ * \param ctx: your struct lws_genhmac_ctx
+ * \param type:	one of LWS_GENHMAC_TYPE_...
+ * \param key: pointer to the start of the HMAC key
+ * \param key_len: length of the HMAC key
+ *
+ * Initializes the hash context for the type you requested
+ *
+ * If the return is nonzero, it failed and there is nothing needing to be
+ * destroyed.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_genhmac_init(struct lws_genhmac_ctx *ctx, enum lws_genhmac_types type,
+		 const uint8_t *key, size_t key_len);
+
+/** lws_genhmac_update() - digest len bytes of the buffer starting at in
+ *
+ * \param ctx: your struct lws_genhmac_ctx
+ * \param in: start of the bytes to digest
+ * \param len: count of bytes to digest
+ *
+ * Updates the state of your hash context to reflect digesting len bytes from in
+ *
+ * If the return is nonzero, it failed and needs destroying.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_genhmac_update(struct lws_genhmac_ctx *ctx, const void *in, size_t len);
+
+/** lws_genhmac_destroy() - copy out the result digest and destroy the ctx
+ *
+ * \param ctx: your struct lws_genhmac_ctx
+ * \param result: NULL, or where to copy the result hash
+ *
+ * Finalizes the hash and copies out the digest.  Destroys any allocations such
+ * that ctx can safely go out of scope after calling this.
+ *
+ * NULL result is supported so that you can destroy the ctx cleanly on error
+ * conditions, where there is no valid result.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genhmac_destroy(struct lws_genhmac_ctx *ctx, void *result);
+///@}

include/libwebsockets/lws-genrsa.h

@@ -0,0 +1,255 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup genericRSA Generic RSA
+ * ## Generic RSA related functions
+ *
+ * Lws provides generic RSA functions that abstract the ones
+ * provided by whatever OpenSSL library you are linking against.
+ *
+ * It lets you use the same code if you build against mbedtls or OpenSSL
+ * for example.
+ */
+///@{
+
+/* include/libwebsockets/lws-jwk.h must be included before this */
+
+enum enum_genrsa_mode {
+	LGRSAM_PKCS1_1_5,
+	LGRSAM_PKCS1_OAEP_PSS,
+
+	LGRSAM_COUNT
+};
+
+struct lws_genrsa_ctx {
+#if defined(LWS_WITH_MBEDTLS)
+	mbedtls_rsa_context *ctx;
+#else
+	BIGNUM *bn[LWS_GENCRYPTO_RSA_KEYEL_COUNT];
+	EVP_PKEY_CTX *ctx;
+	RSA *rsa;
+#endif
+	struct lws_context *context;
+	enum enum_genrsa_mode mode;
+};
+
+/** lws_genrsa_public_decrypt_create() - Create RSA public decrypt context
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param el: struct prepared with key element data
+ * \param context: lws_context for RNG
+ * \param mode: RSA mode, one of LGRSAM_ constants
+ * \param oaep_hashid: the lws genhash id for the hash used in MFG1 hash
+ *			used in OAEP mode - normally, SHA1
+ *
+ * Creates an RSA context with a public key associated with it, formed from
+ * the key elements in \p el.
+ *
+ * Mode LGRSAM_PKCS1_1_5 is in widespread use but has weaknesses.  It's
+ * recommended to use LGRSAM_PKCS1_OAEP_PSS for new implementations.
+ *
+ * Returns 0 for OK or nonzero for error.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_create(struct lws_genrsa_ctx *ctx,
+		  const struct lws_gencrypto_keyelem *el,
+		  struct lws_context *context, enum enum_genrsa_mode mode,
+		  enum lws_genhash_types oaep_hashid);
+
+/** lws_genrsa_destroy_elements() - Free allocations in genrsa_elements
+ *
+ * \param el: your struct lws_gencrypto_keyelem
+ *
+ * This is a helper for user code making use of struct lws_gencrypto_keyelem
+ * where the elements are allocated on the heap, it frees any non-NULL
+ * buf element and sets the buf to NULL.
+ *
+ * NB: lws_genrsa_public_... apis do not need this as they take care of the key
+ * creation and destruction themselves.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_genrsa_destroy_elements(struct lws_gencrypto_keyelem *el);
+
+/** lws_genrsa_new_keypair() - Create new RSA keypair
+ *
+ * \param context: your struct lws_context (may be used for RNG)
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param mode: RSA mode, one of LGRSAM_ constants
+ * \param el: struct to get the new key element data allocated into it
+ * \param bits: key size, eg, 4096
+ *
+ * Creates a new RSA context and generates a new keypair into it, with \p bits
+ * bits.
+ *
+ * Returns 0 for OK or nonzero for error.
+ *
+ * Mode LGRSAM_PKCS1_1_5 is in widespread use but has weaknesses.  It's
+ * recommended to use LGRSAM_PKCS1_OAEP_PSS for new implementations.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_new_keypair(struct lws_context *context, struct lws_genrsa_ctx *ctx,
+		       enum enum_genrsa_mode mode, struct lws_gencrypto_keyelem *el,
+		       int bits);
+
+/** lws_genrsa_public_encrypt() - Perform RSA public key encryption
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: plaintext input
+ * \param in_len: length of plaintext input
+ * \param out: encrypted output
+ *
+ * Performs PKCS1 v1.5 Encryption
+ *
+ * Returns <0 for error, or length of decrypted data.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_public_encrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
+			  size_t in_len, uint8_t *out);
+
+/** lws_genrsa_private_encrypt() - Perform RSA private key encryption
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: plaintext input
+ * \param in_len: length of plaintext input
+ * \param out: encrypted output
+ *
+ * Performs PKCS1 v1.5 Encryption
+ *
+ * Returns <0 for error, or length of decrypted data.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_private_encrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
+			   size_t in_len, uint8_t *out);
+
+/** lws_genrsa_public_decrypt() - Perform RSA public key decryption
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: encrypted input
+ * \param in_len: length of encrypted input
+ * \param out: decrypted output
+ * \param out_max: size of output buffer
+ *
+ * Performs PKCS1 v1.5 Decryption
+ *
+ * Returns <0 for error, or length of decrypted data.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_public_decrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
+			  size_t in_len, uint8_t *out, size_t out_max);
+
+/** lws_genrsa_private_decrypt() - Perform RSA private key decryption
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: encrypted input
+ * \param in_len: length of encrypted input
+ * \param out: decrypted output
+ * \param out_max: size of output buffer
+ *
+ * Performs PKCS1 v1.5 Decryption
+ *
+ * Returns <0 for error, or length of decrypted data.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_private_decrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
+			   size_t in_len, uint8_t *out, size_t out_max);
+
+/** lws_genrsa_hash_sig_verify() - Verifies RSA signature on a given hash
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: input to be hashed
+ * \param hash_type: one of LWS_GENHASH_TYPE_
+ * \param sig: pointer to the signature we received with the payload
+ * \param sig_len: length of the signature we are checking in bytes
+ *
+ * Returns <0 for error, or 0 if signature matches the payload + key.
+ *
+ * This just looks at a hash... that's why there's no input length
+ * parameter, it's decided by the choice of hash.   It's up to you to confirm
+ * separately the actual payload matches the hash that was confirmed by this to
+ * be validly signed.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_hash_sig_verify(struct lws_genrsa_ctx *ctx, const uint8_t *in,
+			   enum lws_genhash_types hash_type,
+			   const uint8_t *sig, size_t sig_len);
+
+/** lws_genrsa_hash_sign() - Creates an ECDSA signature for a hash you provide
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param in: input to be hashed and signed
+ * \param hash_type: one of LWS_GENHASH_TYPE_
+ * \param sig: pointer to buffer to take signature
+ * \param sig_len: length of the buffer (must be >= length of key N)
+ *
+ * Returns <0 for error, or \p sig_len for success.
+ *
+ * This creates an RSA signature for a hash you already computed and provide.
+ * You should have created the hash before calling this by iterating over the
+ * actual payload you need to confirm.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_hash_sign(struct lws_genrsa_ctx *ctx, const uint8_t *in,
+		     enum lws_genhash_types hash_type,
+		     uint8_t *sig, size_t sig_len);
+
+/** lws_genrsa_public_decrypt_destroy() - Destroy RSA public decrypt context
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ *
+ * Destroys any allocations related to \p ctx.
+ *
+ * This and related APIs operate identically with OpenSSL or mbedTLS backends.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_genrsa_destroy(struct lws_genrsa_ctx *ctx);
+
+/** lws_genrsa_render_pkey_asn1() - Exports public or private key to ASN1/DER
+ *
+ * \param ctx: your struct lws_genrsa_ctx
+ * \param _private: 0 = public part only, 1 = all parts of the key
+ * \param pkey_asn1: pointer to buffer to take the ASN1
+ * \param pkey_asn1_len: max size of the pkey_asn1_len
+ *
+ * Returns length of pkey_asn1 written, or -1 for error.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_genrsa_render_pkey_asn1(struct lws_genrsa_ctx *ctx, int _private,
+			    uint8_t *pkey_asn1, size_t pkey_asn1_len);
+///@}

include/libwebsockets/lws-gpio.h

@@ -0,0 +1,60 @@
+/*
+ * Generic GPIO ops
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is like an abstract class for gpio, a real implementation provides
+ * functions for the ops that use the underlying OS gpio arrangements.
+ */
+
+#if !defined(__LWS_GPIO_H__)
+#define __LWS_GPIO_H__
+
+typedef int _lws_plat_gpio_t;
+
+typedef enum {
+	LWSGGPIO_IRQ_NONE,
+	LWSGGPIO_IRQ_RISING,
+	LWSGGPIO_IRQ_FALLING,
+	LWSGGPIO_IRQ_CHANGE,
+	LWSGGPIO_IRQ_LOW,
+	LWSGGPIO_IRQ_HIGH
+} lws_gpio_irq_t;
+
+enum {
+	LWSGGPIO_FL_READ			= (1 << 0),
+	LWSGGPIO_FL_WRITE			= (1 << 1),
+	LWSGGPIO_FL_PULLUP			= (1 << 2),
+	LWSGGPIO_FL_PULLDOWN			= (1 << 3),
+	LWSGGPIO_FL_START_LOW			= (1 << 4),
+};
+
+typedef void (*lws_gpio_irq_cb_t)(void *arg);
+
+typedef struct lws_gpio_ops {
+	void (*mode)(_lws_plat_gpio_t gpio, int flags);
+	int (*read)(_lws_plat_gpio_t gpio);
+	void (*set)(_lws_plat_gpio_t gpio, int val);
+	int (*irq_mode)(_lws_plat_gpio_t gpio, lws_gpio_irq_t irq,
+			lws_gpio_irq_cb_t cb, void *arg);
+} lws_gpio_ops_t;
+
+#endif

include/libwebsockets/lws-http.h

@@ -0,0 +1,1028 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/* minimal space for typical headers and CSP stuff */
+
+#define LWS_RECOMMENDED_MIN_HEADER_SPACE 2048
+
+/*! \defgroup http HTTP
+
+    Modules related to handling HTTP
+*/
+//@{
+
+/*! \defgroup httpft HTTP File transfer
+ * \ingroup http
+
+    APIs for sending local files in response to HTTP requests
+*/
+//@{
+
+/**
+ * lws_get_mimetype() - Determine mimetype to use from filename
+ *
+ * \param file:		filename
+ * \param m:		NULL, or mount context
+ *
+ * This uses a canned list of known filetypes first, if no match and m is
+ * non-NULL, then tries a list of per-mount file suffix to mimtype mappings.
+ *
+ * Returns either NULL or a pointer to the mimetype matching the file.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_get_mimetype(const char *file, const struct lws_http_mount *m);
+
+/**
+ * lws_serve_http_file() - Send a file back to the client using http
+ * \param wsi:		Websocket instance (available from user callback)
+ * \param file:		The file to issue over http
+ * \param content_type:	The http content type, eg, text/html
+ * \param other_headers:	NULL or pointer to header string
+ * \param other_headers_len:	length of the other headers if non-NULL
+ *
+ *	This function is intended to be called from the callback in response
+ *	to http requests from the client.  It allows the callback to issue
+ *	local files down the http link in a single step.
+ *
+ *	Returning <0 indicates error and the wsi should be closed.  Returning
+ *	>0 indicates the file was completely sent and
+ *	lws_http_transaction_completed() called on the wsi (and close if != 0)
+ *	==0 indicates the file transfer is started and needs more service later,
+ *	the wsi should be left alone.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_serve_http_file(struct lws *wsi, const char *file, const char *content_type,
+		    const char *other_headers, int other_headers_len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_serve_http_file_fragment(struct lws *wsi);
+//@}
+
+
+enum http_status {
+	HTTP_STATUS_CONTINUE					= 100,
+
+	HTTP_STATUS_OK						= 200,
+	HTTP_STATUS_NO_CONTENT					= 204,
+	HTTP_STATUS_PARTIAL_CONTENT				= 206,
+
+	HTTP_STATUS_MOVED_PERMANENTLY				= 301,
+	HTTP_STATUS_FOUND					= 302,
+	HTTP_STATUS_SEE_OTHER					= 303,
+	HTTP_STATUS_NOT_MODIFIED				= 304,
+
+	HTTP_STATUS_BAD_REQUEST					= 400,
+	HTTP_STATUS_UNAUTHORIZED,
+	HTTP_STATUS_PAYMENT_REQUIRED,
+	HTTP_STATUS_FORBIDDEN,
+	HTTP_STATUS_NOT_FOUND,
+	HTTP_STATUS_METHOD_NOT_ALLOWED,
+	HTTP_STATUS_NOT_ACCEPTABLE,
+	HTTP_STATUS_PROXY_AUTH_REQUIRED,
+	HTTP_STATUS_REQUEST_TIMEOUT,
+	HTTP_STATUS_CONFLICT,
+	HTTP_STATUS_GONE,
+	HTTP_STATUS_LENGTH_REQUIRED,
+	HTTP_STATUS_PRECONDITION_FAILED,
+	HTTP_STATUS_REQ_ENTITY_TOO_LARGE,
+	HTTP_STATUS_REQ_URI_TOO_LONG,
+	HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE,
+	HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE,
+	HTTP_STATUS_EXPECTATION_FAILED,
+
+	HTTP_STATUS_INTERNAL_SERVER_ERROR			= 500,
+	HTTP_STATUS_NOT_IMPLEMENTED,
+	HTTP_STATUS_BAD_GATEWAY,
+	HTTP_STATUS_SERVICE_UNAVAILABLE,
+	HTTP_STATUS_GATEWAY_TIMEOUT,
+	HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED,
+};
+/*! \defgroup html-chunked-substitution HTML Chunked Substitution
+ * \ingroup http
+ *
+ * ##HTML chunked Substitution
+ *
+ * APIs for receiving chunks of text, replacing a set of variable names via
+ * a callback, and then prepending and appending HTML chunked encoding
+ * headers.
+ */
+//@{
+
+struct lws_process_html_args {
+	char *p; /**< pointer to the buffer containing the data */
+	int len; /**< length of the original data at p */
+	int max_len; /**< maximum length we can grow the data to */
+	int final; /**< set if this is the last chunk of the file */
+	int chunked; /**< 0 == unchunked, 1 == produce chunk headers
+			(incompatible with HTTP/2) */
+};
+
+typedef const char *(*lws_process_html_state_cb)(void *data, int index);
+
+struct lws_process_html_state {
+	char *start; /**< pointer to start of match */
+	char swallow[16]; /**< matched character buffer */
+	int pos; /**< position in match */
+	void *data; /**< opaque pointer */
+	const char * const *vars; /**< list of variable names */
+	int count_vars; /**< count of variable names */
+
+	lws_process_html_state_cb replace;
+		/**< called on match to perform substitution */
+};
+
+/*! lws_chunked_html_process() - generic chunked substitution
+ * \param args: buffer to process using chunked encoding
+ * \param s: current processing state
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_chunked_html_process(struct lws_process_html_args *args,
+			 struct lws_process_html_state *s);
+//@}
+
+/** \defgroup HTTP-headers-read HTTP headers: read
+ * \ingroup http
+ *
+ * ##HTTP header releated functions
+ *
+ *  In lws the client http headers are temporarily stored in a pool, only for the
+ *  duration of the http part of the handshake.  It's because in most cases,
+ *  the header content is ignored for the whole rest of the connection lifetime
+ *  and would then just be taking up space needlessly.
+ *
+ *  During LWS_CALLBACK_HTTP when the URI path is delivered is the last time
+ *  the http headers are still allocated, you can use these apis then to
+ *  look at and copy out interesting header content (cookies, etc)
+ *
+ *  Notice that the header total length reported does not include a terminating
+ *  '\0', however you must allocate for it when using the _copy apis.  So the
+ *  length reported for a header containing "123" is 3, but you must provide
+ *  a buffer of length 4 so that "123\0" may be copied into it, or the copy
+ *  will fail with a nonzero return code.
+ *
+ *  In the special case of URL arguments, like ?x=1&y=2, the arguments are
+ *  stored in a token named for the method, eg,  WSI_TOKEN_GET_URI if it
+ *  was a GET or WSI_TOKEN_POST_URI if POST.  You can check the total
+ *  length to confirm the method.
+ *
+ *  For URL arguments, each argument is stored urldecoded in a "fragment", so
+ *  you can use the fragment-aware api lws_hdr_copy_fragment() to access each
+ *  argument in turn: the fragments contain urldecoded strings like x=1 or y=2.
+ *
+ *  As a convenience, lws has an api that will find the fragment with a
+ *  given name= part, lws_get_urlarg_by_name().
+ */
+///@{
+
+/** struct lws_tokens
+ * you need these to look at headers that have been parsed if using the
+ * LWS_CALLBACK_FILTER_CONNECTION callback.  If a header from the enum
+ * list below is absent, .token = NULL and len = 0.  Otherwise .token
+ * points to .len chars containing that header content.
+ */
+struct lws_tokens {
+	unsigned char *token; /**< pointer to start of the token */
+	int len; /**< length of the token's value */
+};
+
+/* enum lws_token_indexes
+ * these have to be kept in sync with lextable.h / minilex.c
+ *
+ * NOTE: These public enums are part of the abi.  If you want to add one,
+ * add it at where specified so existing users are unaffected.
+ */
+enum lws_token_indexes {
+	WSI_TOKEN_GET_URI, /* 0 */
+	WSI_TOKEN_POST_URI,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_OPTIONS_URI,
+#endif
+	WSI_TOKEN_HOST,
+	WSI_TOKEN_CONNECTION,
+	WSI_TOKEN_UPGRADE, /* 5 */
+	WSI_TOKEN_ORIGIN,
+#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_DRAFT,
+#endif
+	WSI_TOKEN_CHALLENGE,
+#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_EXTENSIONS,
+	WSI_TOKEN_KEY1, /* 10 */
+	WSI_TOKEN_KEY2,
+	WSI_TOKEN_PROTOCOL,
+	WSI_TOKEN_ACCEPT,
+	WSI_TOKEN_NONCE,
+#endif
+	WSI_TOKEN_HTTP,
+#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP2_SETTINGS, /* 16 */
+#endif
+	WSI_TOKEN_HTTP_ACCEPT,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_AC_REQUEST_HEADERS,
+#endif
+	WSI_TOKEN_HTTP_IF_MODIFIED_SINCE,
+	WSI_TOKEN_HTTP_IF_NONE_MATCH, /* 20 */
+	WSI_TOKEN_HTTP_ACCEPT_ENCODING,
+	WSI_TOKEN_HTTP_ACCEPT_LANGUAGE,
+	WSI_TOKEN_HTTP_PRAGMA,
+	WSI_TOKEN_HTTP_CACHE_CONTROL,
+	WSI_TOKEN_HTTP_AUTHORIZATION,
+	WSI_TOKEN_HTTP_COOKIE,
+	WSI_TOKEN_HTTP_CONTENT_LENGTH, /* 27 */
+	WSI_TOKEN_HTTP_CONTENT_TYPE,
+	WSI_TOKEN_HTTP_DATE,
+	WSI_TOKEN_HTTP_RANGE,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_REFERER,
+#endif
+#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_KEY,
+	WSI_TOKEN_VERSION,
+	WSI_TOKEN_SWORIGIN,
+#endif
+#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_COLON_AUTHORITY,
+	WSI_TOKEN_HTTP_COLON_METHOD,
+	WSI_TOKEN_HTTP_COLON_PATH,
+	WSI_TOKEN_HTTP_COLON_SCHEME,
+	WSI_TOKEN_HTTP_COLON_STATUS,
+#endif
+
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_ACCEPT_CHARSET,
+#endif
+	WSI_TOKEN_HTTP_ACCEPT_RANGES,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN,
+#endif
+	WSI_TOKEN_HTTP_AGE,
+	WSI_TOKEN_HTTP_ALLOW,
+	WSI_TOKEN_HTTP_CONTENT_DISPOSITION,
+	WSI_TOKEN_HTTP_CONTENT_ENCODING,
+	WSI_TOKEN_HTTP_CONTENT_LANGUAGE,
+	WSI_TOKEN_HTTP_CONTENT_LOCATION,
+	WSI_TOKEN_HTTP_CONTENT_RANGE,
+	WSI_TOKEN_HTTP_ETAG,
+	WSI_TOKEN_HTTP_EXPECT,
+	WSI_TOKEN_HTTP_EXPIRES,
+	WSI_TOKEN_HTTP_FROM,
+	WSI_TOKEN_HTTP_IF_MATCH,
+	WSI_TOKEN_HTTP_IF_RANGE,
+	WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE,
+	WSI_TOKEN_HTTP_LAST_MODIFIED,
+	WSI_TOKEN_HTTP_LINK,
+	WSI_TOKEN_HTTP_LOCATION,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_MAX_FORWARDS,
+	WSI_TOKEN_HTTP_PROXY_AUTHENTICATE,
+	WSI_TOKEN_HTTP_PROXY_AUTHORIZATION,
+#endif
+	WSI_TOKEN_HTTP_REFRESH,
+	WSI_TOKEN_HTTP_RETRY_AFTER,
+	WSI_TOKEN_HTTP_SERVER,
+	WSI_TOKEN_HTTP_SET_COOKIE,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY,
+#endif
+	WSI_TOKEN_HTTP_TRANSFER_ENCODING,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_HTTP_USER_AGENT,
+	WSI_TOKEN_HTTP_VARY,
+	WSI_TOKEN_HTTP_VIA,
+	WSI_TOKEN_HTTP_WWW_AUTHENTICATE,
+#endif
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_PATCH_URI,
+	WSI_TOKEN_PUT_URI,
+	WSI_TOKEN_DELETE_URI,
+#endif
+
+	WSI_TOKEN_HTTP_URI_ARGS,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_PROXY,
+	WSI_TOKEN_HTTP_X_REAL_IP,
+#endif
+	WSI_TOKEN_HTTP1_0,
+	WSI_TOKEN_X_FORWARDED_FOR,
+	WSI_TOKEN_CONNECT,
+	WSI_TOKEN_HEAD_URI,
+#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_TE,
+	WSI_TOKEN_REPLAY_NONCE, /* ACME */
+#endif
+#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_COLON_PROTOCOL,
+#endif
+	WSI_TOKEN_X_AUTH_TOKEN,
+	WSI_TOKEN_DSS_SIGNATURE,
+
+	/****** add new things just above ---^ ******/
+
+	/* use token storage to stash these internally, not for
+	 * user use */
+
+	_WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
+	_WSI_TOKEN_CLIENT_PEER_ADDRESS,
+	_WSI_TOKEN_CLIENT_URI,
+	_WSI_TOKEN_CLIENT_HOST,
+	_WSI_TOKEN_CLIENT_ORIGIN,
+	_WSI_TOKEN_CLIENT_METHOD,
+	_WSI_TOKEN_CLIENT_IFACE,
+	_WSI_TOKEN_CLIENT_ALPN,
+
+	/* always last real token index*/
+	WSI_TOKEN_COUNT,
+
+	/* parser state additions, no storage associated */
+	WSI_TOKEN_NAME_PART,
+#if defined(LWS_WITH_CUSTOM_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
+	WSI_TOKEN_UNKNOWN_VALUE_PART,
+#endif
+	WSI_TOKEN_SKIPPING,
+	WSI_TOKEN_SKIPPING_SAW_CR,
+	WSI_PARSING_COMPLETE,
+	WSI_INIT_TOKEN_MUXURL,
+};
+
+struct lws_token_limits {
+	unsigned short token_limit[WSI_TOKEN_COUNT]; /**< max chars for this token */
+};
+
+enum lws_h2_settings {
+	H2SET_HEADER_TABLE_SIZE = 1,
+	H2SET_ENABLE_PUSH,
+	H2SET_MAX_CONCURRENT_STREAMS,
+	H2SET_INITIAL_WINDOW_SIZE,
+	H2SET_MAX_FRAME_SIZE,
+	H2SET_MAX_HEADER_LIST_SIZE,
+	H2SET_RESERVED7,
+	H2SET_ENABLE_CONNECT_PROTOCOL, /* defined in mcmanus-httpbis-h2-ws-02 */
+
+	H2SET_COUNT /* always last */
+};
+
+/**
+ * lws_token_to_string() - returns a textual representation of a hdr token index
+ *
+ * \param token: token index
+ */
+LWS_VISIBLE LWS_EXTERN const unsigned char *
+lws_token_to_string(enum lws_token_indexes token);
+
+/**
+ * lws_hdr_total_length: report length of all fragments of a header totalled up
+ *		The returned length does not include the space for a
+ *		terminating '\0'
+ *
+ * \param wsi: websocket connection
+ * \param h: which header index we are interested in
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h);
+
+/**
+ * lws_hdr_fragment_length: report length of a single fragment of a header
+ *		The returned length does not include the space for a
+ *		terminating '\0'
+ *
+ * \param wsi: websocket connection
+ * \param h: which header index we are interested in
+ * \param frag_idx: which fragment of h we want to get the length of
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h,
+			int frag_idx);
+
+/**
+ * lws_hdr_copy() - copy all fragments of the given header to a buffer
+ *		The buffer length len must include space for an additional
+ *		terminating '\0', or it will fail returning -1.
+ *
+ * \param wsi: websocket connection
+ * \param dest: destination buffer
+ * \param len: length of destination buffer
+ * \param h: which header index we are interested in
+ *
+ * copies the whole, aggregated header, even if it was delivered in
+ * several actual headers piece by piece.  Returns -1 or length of the whole
+ * header.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hdr_copy(struct lws *wsi, char *dest, int len, enum lws_token_indexes h);
+
+/**
+ * lws_hdr_copy_fragment() - copy a single fragment of the given header to a buffer
+ *		The buffer length len must include space for an additional
+ *		terminating '\0', or it will fail returning -1.
+ *		If the requested fragment index is not present, it fails
+ *		returning -1.
+ *
+ * \param wsi: websocket connection
+ * \param dest: destination buffer
+ * \param len: length of destination buffer
+ * \param h: which header index we are interested in
+ * \param frag_idx: which fragment of h we want to copy
+ *
+ * Normally this is only useful
+ * to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS
+ * fragment 0 will contain "x=1" and fragment 1 "y=2"
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hdr_copy_fragment(struct lws *wsi, char *dest, int len,
+		      enum lws_token_indexes h, int frag_idx);
+
+/**
+ * lws_hdr_custom_length() - return length of a custom header
+ *
+ * \param wsi: websocket connection
+ * \param name: header string (including terminating :)
+ * \param nlen: length of name
+ *
+ * Lws knows about 100 common http headers, and parses them into indexes when
+ * it recognizes them.  When it meets a header that it doesn't know, it stores
+ * the name and value directly, and you can look them up using
+ * lws_hdr_custom_length() and lws_hdr_custom_copy().
+ *
+ * This api returns -1, or the length of the value part of the header if it
+ * exists.  Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to
+ * use this api.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hdr_custom_length(struct lws *wsi, const char *name, int nlen);
+
+/**
+ * lws_hdr_custom_copy() - copy value part of a custom header
+ *
+ * \param wsi: websocket connection
+ * \param dst: pointer to buffer to receive the copy
+ * \param len: number of bytes available at dst
+ * \param name: header string (including terminating :)
+ * \param nlen: length of name
+ *
+ * Lws knows about 100 common http headers, and parses them into indexes when
+ * it recognizes them.  When it meets a header that it doesn't know, it stores
+ * the name and value directly, and you can look them up using
+ * lws_hdr_custom_length() and lws_hdr_custom_copy().
+ *
+ * This api returns -1, or the length of the string it copied into dst if it
+ * was big enough to contain both the string and an extra terminating NUL. Lws
+ * must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to use this api.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hdr_custom_copy(struct lws *wsi, char *dst, int len, const char *name,
+		    int nlen);
+
+typedef void (*lws_hdr_custom_fe_cb_t)(const char *name, int nlen, void *opaque);
+/**
+ * lws_hdr_custom_name_foreach() - Iterate the custom header names
+ *
+ * \param wsi: websocket connection
+ * \param cb: callback for each custom header name
+ * \param opaque: ignored by lws except to pass to callback
+ *
+ * Lws knows about 100 common http headers, and parses them into indexes when
+ * it recognizes them.  When it meets a header that it doesn't know, it stores
+ * the name and value directly, and you can look them up using
+ * lws_hdr_custom_length() and lws_hdr_custom_copy().
+ * 
+ * This api returns -1 on error else 0. Use lws_hdr_custom_copy() to get the
+ * values of headers. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by
+ * default) to use this api.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hdr_custom_name_foreach(struct lws *wsi, lws_hdr_custom_fe_cb_t cb, void *opaque);
+
+/**
+ * lws_get_urlarg_by_name_safe() - get copy and return length of y for x=y urlargs
+ *
+ * \param wsi: the connection to check
+ * \param name: the arg name, like "token" or "token="
+ * \param buf: the buffer to receive the urlarg (including the name= part)
+ * \param len: the length of the buffer to receive the urlarg
+ *
+ * Returns -1 if not present, else the length of y in the urlarg name=y.  If
+ * zero or greater, then buf contains a copy of the string y.  Any = after the
+ * name match is trimmed off if the name does not end with = itself.
+ *
+ * This returns the explicit length and so can deal with binary blobs that are
+ * percent-encoded.  It also makes sure buf has a NUL just after the valid
+ * length so it can work with NUL-based apis if you don't care about truncation.
+ *
+ * buf may have been written even when -1 is returned indicating no match.
+ *
+ * Use this in place of lws_get_urlarg_by_name() that does not return an
+ * explicit length.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_get_urlarg_by_name_safe(struct lws *wsi, const char *name, char *buf, int len);
+
+/**
+ * lws_get_urlarg_by_name() - return pointer to arg value if present
+ *
+ * \param wsi: the connection to check
+ * \param name: the arg name, like "token="
+ * \param buf: the buffer to receive the urlarg (including the name= part)
+ * \param len: the length of the buffer to receive the urlarg
+ *
+ *     Returns NULL if not found or a pointer inside buf to just after the
+ *     name= part.
+ *
+ * This assumed the argument can be represented with a NUL-terminated string.
+ * It can't correctly deal with binary values encoded with %XX, eg. %00 will
+ * be understood to terminate the string.
+ *
+ * Use lws_get_urlarg_by_name_safe() instead of this, which returns the length.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_get_urlarg_by_name(struct lws *wsi, const char *name, char *buf, int len)
+/* LWS_WARN_DEPRECATED */;
+///@}
+
+/*! \defgroup HTTP-headers-create HTTP headers: create
+ *
+ * ## HTTP headers: Create
+ *
+ * These apis allow you to create HTTP response headers in a way compatible with
+ * both HTTP/1.x and HTTP/2.
+ *
+ * They each append to a buffer taking care about the buffer end, which is
+ * passed in as a pointer.  When data is written to the buffer, the current
+ * position p is updated accordingly.
+ *
+ * All of these apis are LWS_WARN_UNUSED_RESULT as they can run out of space
+ * and fail with nonzero return.
+ */
+///@{
+
+#define LWSAHH_CODE_MASK			((1 << 16) - 1)
+#define LWSAHH_FLAG_NO_SERVER_NAME		(1 << 30)
+
+/**
+ * lws_add_http_header_status() - add the HTTP response status code
+ *
+ * \param wsi: the connection to check
+ * \param code: an HTTP code like 200, 404 etc (see enum http_status)
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Adds the initial response code, so should be called first.
+ *
+ * Code may additionally take OR'd flags:
+ *
+ *    LWSAHH_FLAG_NO_SERVER_NAME:  don't apply server name header this time
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_add_http_header_status(struct lws *wsi,
+			   unsigned int code, unsigned char **p,
+			   unsigned char *end);
+/**
+ * lws_add_http_header_by_name() - append named header and value
+ *
+ * \param wsi: the connection to check
+ * \param name: the hdr name, like "my-header:"
+ * \param value: the value after the = for this header
+ * \param length: the length of the value
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Appends name: value to the headers
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_add_http_header_by_name(struct lws *wsi, const unsigned char *name,
+			    const unsigned char *value, int length,
+			    unsigned char **p, unsigned char *end);
+/**
+ * lws_add_http_header_by_token() - append given header and value
+ *
+ * \param wsi: the connection to check
+ * \param token: the token index for the hdr
+ * \param value: the value after the = for this header
+ * \param length: the length of the value
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Appends name=value to the headers, but is able to take advantage of better
+ * HTTP/2 coding mechanisms where possible.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_add_http_header_by_token(struct lws *wsi, enum lws_token_indexes token,
+			     const unsigned char *value, int length,
+			     unsigned char **p, unsigned char *end);
+/**
+ * lws_add_http_header_content_length() - append content-length helper
+ *
+ * \param wsi: the connection to check
+ * \param content_length: the content length to use
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Appends content-length: content_length to the headers
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_add_http_header_content_length(struct lws *wsi,
+				   lws_filepos_t content_length,
+				   unsigned char **p, unsigned char *end);
+/**
+ * lws_finalize_http_header() - terminate header block
+ *
+ * \param wsi: the connection to check
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Indicates no more headers will be added
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_finalize_http_header(struct lws *wsi, unsigned char **p,
+			 unsigned char *end);
+
+/**
+ * lws_finalize_write_http_header() - Helper finializing and writing http headers
+ *
+ * \param wsi: the connection to check
+ * \param start: pointer to the start of headers in the buffer, eg &buf[LWS_PRE]
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Terminates the headers correctly accoring to the protocol in use (h1 / h2)
+ * and writes the headers.  Returns nonzero for error.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_finalize_write_http_header(struct lws *wsi, unsigned char *start,
+			       unsigned char **p, unsigned char *end);
+
+#define LWS_ILLEGAL_HTTP_CONTENT_LEN ((lws_filepos_t)-1ll)
+
+/**
+ * lws_add_http_common_headers() - Helper preparing common http headers
+ *
+ * \param wsi: the connection to check
+ * \param code: an HTTP code like 200, 404 etc (see enum http_status)
+ * \param content_type: the content type, like "text/html"
+ * \param content_len: the content length, in bytes
+ * \param p: pointer to current position in buffer pointer
+ * \param end: pointer to end of buffer
+ *
+ * Adds the initial response code, so should be called first.
+ *
+ * Code may additionally take OR'd flags:
+ *
+ *    LWSAHH_FLAG_NO_SERVER_NAME:  don't apply server name header this time
+ *
+ * This helper just calls public apis to simplify adding headers that are
+ * commonly needed.  If it doesn't fit your case, or you want to add additional
+ * headers just call the public apis directly yourself for what you want.
+ *
+ * You can miss out the content length header by providing the constant
+ * LWS_ILLEGAL_HTTP_CONTENT_LEN for the content_len.
+ *
+ * It does not call lws_finalize_http_header(), to allow you to add further
+ * headers after calling this.  You will need to call that yourself at the end.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_add_http_common_headers(struct lws *wsi, unsigned int code,
+			    const char *content_type, lws_filepos_t content_len,
+			    unsigned char **p, unsigned char *end);
+
+enum {
+	LWSHUMETH_GET,
+	LWSHUMETH_POST,
+	LWSHUMETH_OPTIONS,
+	LWSHUMETH_PUT,
+	LWSHUMETH_PATCH,
+	LWSHUMETH_DELETE,
+	LWSHUMETH_CONNECT,
+	LWSHUMETH_HEAD,
+	LWSHUMETH_COLON_PATH,
+};
+
+/**
+ * lws_http_get_uri_and_method() - Get information on method and url
+ *
+ * \param wsi: the connection to get information on
+ * \param puri_ptr: points to pointer to set to url
+ * \param puri_len: points to int to set to uri length
+ *
+ * Returns -1 or method index as one of the LWSHUMETH_ constants
+ *
+ * If returns method, *puri_ptr is set to the method's URI string and *puri_len
+ * to its length
+ */
+
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_http_get_uri_and_method(struct lws *wsi, char **puri_ptr, int *puri_len);
+
+///@}
+
+/*! \defgroup urlendec Urlencode and Urldecode
+ * \ingroup http
+ *
+ * ##HTML chunked Substitution
+ *
+ * APIs for receiving chunks of text, replacing a set of variable names via
+ * a callback, and then prepending and appending HTML chunked encoding
+ * headers.
+ */
+//@{
+
+/**
+ * lws_urlencode() - like strncpy but with urlencoding
+ *
+ * \param escaped: output buffer
+ * \param string: input buffer ('/0' terminated)
+ * \param len: output buffer max length
+ *
+ * Because urlencoding expands the output string, it's not
+ * possible to do it in-place, ie, with escaped == string
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_urlencode(char *escaped, const char *string, int len);
+
+/*
+ * URLDECODE 1 / 2
+ *
+ * This simple urldecode only operates until the first '\0' and requires the
+ * data to exist all at once
+ */
+/**
+ * lws_urldecode() - like strncpy but with urldecoding
+ *
+ * \param string: output buffer
+ * \param escaped: input buffer ('\0' terminated)
+ * \param len: output buffer max length
+ *
+ * This is only useful for '\0' terminated strings
+ *
+ * Since urldecoding only shrinks the output string, it is possible to
+ * do it in-place, ie, string == escaped
+ *
+ * Returns 0 if completed OK or nonzero for urldecode violation (non-hex chars
+ * where hex required, etc)
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_urldecode(char *string, const char *escaped, int len);
+///@}
+
+/**
+ * lws_http_date_render_from_unix() - render unixtime as RFC7231 date string
+ *
+ * \param buf:		Destination string buffer
+ * \param len:		avilable length of dest string buffer in bytes
+ * \param t:		pointer to the time_t to render
+ *
+ * Returns 0 if time_t is rendered into the string buffer successfully, else
+ * nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_date_render_from_unix(char *buf, size_t len, const time_t *t);
+
+/**
+ * lws_http_date_parse_unix() - parse a RFC7231 date string into unixtime
+ *
+ * \param b:		Source string buffer
+ * \param len:		avilable length of source string buffer in bytes
+ * \param t:		pointer to the destination time_t to set
+ *
+ * Returns 0 if string buffer parsed as RFC7231 time successfully, and
+ * *t set to the parsed unixtime, else return nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_date_parse_unix(const char *b, size_t len, time_t *t);
+
+/**
+ * lws_http_check_retry_after() - increase a timeout if retry-after present
+ *
+ * \param wsi:		http stream this relates to
+ * \param us_interval_in_out: default us retry interval on entry may be updated
+ *
+ * This function may extend the incoming retry interval if the server has
+ * requested that using retry-after: header.  It won't reduce the incoming
+ * retry interval, only leave it alone or increase it.
+ *
+ * *us_interval_in_out should be set to a default retry interval on entry, if
+ * the wsi has a retry-after time or interval that resolves to an interval
+ * longer than the entry *us_interval_in_out, that will be updated to the longer
+ * interval and return 0.
+ *
+ * If no usable retry-after or the time is now or in the past,
+ * *us_interval_in_out is left alone and the function returns nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_check_retry_after(struct lws *wsi, lws_usec_t *us_interval_in_out);
+
+/**
+ * lws_return_http_status() - Return simple http status
+ * \param wsi:		Websocket instance (available from user callback)
+ * \param code:		Status index, eg, 404
+ * \param html_body:		User-readable HTML description < 1KB, or NULL
+ *
+ *	Helper to report HTTP errors back to the client cleanly and
+ *	consistently
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_return_http_status(struct lws *wsi, unsigned int code,
+		       const char *html_body);
+
+/**
+ * lws_http_redirect() - write http redirect out on wsi
+ *
+ * \param wsi:	websocket connection
+ * \param code:	HTTP response code (eg, 301)
+ * \param loc:	where to redirect to
+ * \param len:	length of loc
+ * \param p:	pointer current position in buffer (updated as we write)
+ * \param end:	pointer to end of buffer
+ *
+ * Returns amount written, or < 0 indicating fatal write failure.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len,
+		  unsigned char **p, unsigned char *end);
+
+/**
+ * lws_http_transaction_completed() - wait for new http transaction or close
+ * \param wsi:	websocket connection
+ *
+ *	Returns nonzero if the HTTP connection must close now
+ *	Returns 0 and resets connection to wait for new HTTP header /
+ *	  transaction if possible
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_http_transaction_completed(struct lws *wsi);
+
+/**
+ * lws_http_headers_detach() - drop the associated headers storage and allow
+ *				it to be reused by another connection
+ * \param wsi:	http connection
+ *
+ * If the wsi has an ah headers struct attached, detach it.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_headers_detach(struct lws *wsi);
+
+/**
+ * lws_http_mark_sse() - called to indicate this http stream is now doing SSE
+ *
+ * \param wsi:	http connection
+ *
+ * Cancel any timeout on the wsi, and for h2, mark the network connection as
+ * containing an immortal stream for the duration the SSE stream is open.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_mark_sse(struct lws *wsi);
+
+/**
+ * lws_h2_client_stream_long_poll_rxonly() - h2 stream to immortal read-only
+ *
+ * \param wsi: h2 stream client wsi
+ *
+ * Send END_STREAM-flagged zero-length DATA frame to set client stream wsi into
+ * half-closed (local) and remote into half-closed (remote).  Set the client
+ * stream wsi to be immortal (not subject to timeouts).
+ *
+ * Used if the remote server supports immortal long poll to put the stream into
+ * a read-only state where it can wait as long as needed for rx.
+ *
+ * Returns 0 if the process (which happens asynchronously) started or non-zero
+ * if it wasn't an h2 stream.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_h2_client_stream_long_poll_rxonly(struct lws *wsi);
+
+/**
+ * lws_http_compression_apply() - apply an http compression transform
+ *
+ * \param wsi: the wsi to apply the compression transform to
+ * \param name: NULL, or the name of the compression transform, eg, "deflate"
+ * \param p: pointer to pointer to headers buffer
+ * \param end: pointer to end of headers buffer
+ * \param decomp: 0 = add compressor to wsi, 1 = add decompressor
+ *
+ * This allows transparent compression of dynamically generated HTTP.  The
+ * requested compression (eg, "deflate") is only applied if the client headers
+ * indicated it was supported (and it has support in lws), otherwise it's a NOP.
+ *
+ * If the requested compression method is NULL, then the supported compression
+ * formats are tried, and for non-decompression (server) mode the first that's
+ * found on the client's accept-encoding header is chosen.
+ *
+ * NOTE: the compression transform, same as h2 support, relies on the user
+ * code using LWS_WRITE_HTTP and then LWS_WRITE_HTTP_FINAL on the last part
+ * written.  The internal lws fileserving code already does this.
+ *
+ * If the library was built without the cmake option
+ * LWS_WITH_HTTP_STREAM_COMPRESSION set, then a NOP is provided for this api,
+ * allowing user code to build either way and use compression if available.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_compression_apply(struct lws *wsi, const char *name,
+			   unsigned char **p, unsigned char *end, char decomp);
+
+/**
+ * lws_http_is_redirected_to_get() - true if redirected to GET
+ *
+ * \param wsi: the wsi to check
+ *
+ * Check if the wsi is currently in GET mode, after, eg, doing a POST and
+ * receiving a 303.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_is_redirected_to_get(struct lws *wsi);
+
+/**
+ * lws_http_cookie_get() - return copy of named cookie if present
+ *
+ * \param wsi: the wsi to check
+ * \param name: name of the cookie
+ * \param buf: buffer to store the cookie contents into
+ * \param max_len: on entry, maximum length of buf... on exit, used len of buf
+ *
+ * If no cookie header, or no cookie of the requested name, or the value is
+ * larger than can fit in buf, returns nonzero.
+ *
+ * If the cookie is found, copies its value into buf with a terminating NUL,
+ * sets *max_len to the used length, and returns 0.
+ *
+ * This handles the parsing of the possibly multi-cookie header string and
+ * terminating the requested cookie at the next ; if present.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_cookie_get(struct lws *wsi, const char *name, char *buf, size_t *max);
+
+/**
+ * lws_http_client_http_error() - determine if the response code indicates an error
+ *
+ * \param code: the response code to test
+ *
+ * Returns nonzero if the code indicates an error, else zero if reflects a
+ * non-error condition
+ */
+#define lws_http_client_http_resp_is_error(code) (!(code < 400))
+
+/**
+ * lws_h2_update_peer_txcredit() - manually update stream peer tx credit
+ *
+ * \param wsi: the h2 child stream whose peer credit to change
+ * \param sid: the stream ID, or LWS_H2_STREAM_SID for the wsi stream ID
+ * \param bump: signed change to confer upon peer tx credit for sid
+ *
+ * In conjunction with LCCSCF_H2_MANUAL_RXFLOW flag, allows the user code to
+ * selectively starve the remote peer of the ability to send us data on a client
+ * connection.
+ *
+ * Normally lws sends an initial window size for the peer to send to it of 0,
+ * but during the header phase it sends a WINDOW_UPDATE to increase the amount
+ * available.  LCCSCF_H2_MANUAL_RXFLOW restricts this initial increase in tx
+ * credit for the stream, before it has been asked to send us anything, to the
+ * amount specified in the client info .manual_initial_tx_credit member, and
+ * this api can be called to send the other side permission to send us up to
+ * \p bump additional bytes.
+ *
+ * The nwsi tx credit is updated automatically for exactly what was sent to us
+ * on a stream with LCCSCF_H2_MANUAL_RXFLOW flag, but the stream's own tx credit
+ * must be handled manually by user code via this api.
+ *
+ * Returns 0 for success or nonzero for failure.
+ */
+#define LWS_H2_STREAM_SID -1
+LWS_VISIBLE LWS_EXTERN int
+lws_h2_update_peer_txcredit(struct lws *wsi, unsigned int sid, int bump);
+
+
+/**
+ * lws_h2_get_peer_txcredit_estimate() - return peer tx credit estimate
+ *
+ * \param wsi: the h2 child stream whose peer credit estimate to return
+ *
+ * Returns the estimated amount of tx credit at the peer, in other words the
+ * number of bytes the peer is authorized to send to us.
+ *
+ * It's an 'estimate' because we don't know how much is already in flight
+ * towards us and actually already used.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_h2_get_peer_txcredit_estimate(struct lws *wsi);
+
+///@}
+

include/libwebsockets/lws-i2c.h

@@ -0,0 +1,54 @@
+/*
+ * Generic I2C ops
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is like an abstract class for i2c, a real implementation provides
+ * functions for the ops that use the underlying OS arrangements.
+ */
+
+#if !defined(__LWS_I2C_H__)
+#define __LWS_I2C_H__
+
+#include <stdint.h>
+#include <stddef.h>
+
+typedef struct lws_i2c_ops {
+	int  (*init)(const struct lws_i2c_ops *ctx);
+	int  (*start)(const struct lws_i2c_ops *ctx);
+	void (*stop)(const struct lws_i2c_ops *ctx);
+	int  (*write)(const struct lws_i2c_ops *ctx, uint8_t data);
+	int  (*read)(const struct lws_i2c_ops *ctx);
+	void (*set_ack)(const struct lws_i2c_ops *octx, int ack);
+} lws_i2c_ops_t;
+
+/*
+ * These are implemented by calling the ops above, and so are generic
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_i2c_command(const lws_i2c_ops_t *ctx, uint8_t ads7, uint8_t c);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_i2c_command_list(const lws_i2c_ops_t *ctx, uint8_t ads7, const uint8_t *buf,
+		     size_t len);
+
+#endif

include/libwebsockets/lws-ili9341-spi.h

@@ -0,0 +1,54 @@
+/*
+ * lws abstract display implementation for ili9341 on spi
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#if !defined(__LWS_DISPLAY_ILI9341_SPI_H__)
+#define __LWS_DISPLAY_ILI9341_SPI_H__
+
+
+typedef struct lws_display_ili9341 {
+
+	lws_display_t		disp; /* use lws_display_ili9341_ops to set */
+	const lws_spi_ops_t	*spi;	      /* spi ops */
+
+	const lws_gpio_ops_t	*gpio;	      /* NULL or gpio ops */
+	_lws_plat_gpio_t	reset_gpio;   /* if gpio ops, nReset gpio # */
+
+	uint8_t			spi_index; /* cs index starting from 0 */
+
+} lws_display_ili9341_t;
+
+int
+lws_display_ili9341_spi_init(const struct lws_display *disp);
+int
+lws_display_ili9341_spi_blit(const struct lws_display *disp, const uint8_t *src,
+                             lws_display_scalar x, lws_display_scalar y,
+                             lws_display_scalar w, lws_display_scalar h);
+int
+lws_display_ili9341_spi_power(const struct lws_display *disp, int state);
+
+#define lws_display_ili9341_ops \
+	.init = lws_display_ili9341_spi_init, \
+	.blit = lws_display_ili9341_spi_blit, \
+	.power = lws_display_ili9341_spi_power
+#endif

include/libwebsockets/lws-jose.h

@@ -0,0 +1,214 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+enum lws_jws_jose_hdr_indexes {
+	LJJHI_ALG,	/* REQUIRED */
+	LJJHI_JKU,	/* Optional: string */
+	LJJHI_JWK,	/* Optional: jwk JSON object: public key: */
+	LJJHI_KID,	/* Optional: string */
+	LJJHI_X5U,	/* Optional: string: url of public key cert / chain */
+	LJJHI_X5C,	/* Optional: base64 (NOT -url): actual cert */
+	LJJHI_X5T,	/* Optional: base64url: SHA-1 of actual cert */
+	LJJHI_X5T_S256, /* Optional: base64url: SHA-256 of actual cert */
+	LJJHI_TYP,	/* Optional: string: media type */
+	LJJHI_CTY,	/* Optional: string: content media type */
+	LJJHI_CRIT,	/* Optional for send, REQUIRED: array of strings:
+			 * mustn't contain standardized strings or null set */
+
+	LJJHI_RECIPS_HDR,
+	LJJHI_RECIPS_HDR_ALG,
+	LJJHI_RECIPS_HDR_KID,
+	LJJHI_RECIPS_EKEY,
+
+	LJJHI_ENC,	/* JWE only: Optional: string */
+	LJJHI_ZIP,	/* JWE only: Optional: string ("DEF" = deflate) */
+
+	LJJHI_EPK,	/* Additional arg for JWE ECDH:  ephemeral public key */
+	LJJHI_APU,	/* Additional arg for JWE ECDH:  base64url */
+	LJJHI_APV,	/* Additional arg for JWE ECDH:  base64url */
+	LJJHI_IV,	/* Additional arg for JWE AES:   base64url */
+	LJJHI_TAG,	/* Additional arg for JWE AES:   base64url */
+	LJJHI_P2S,	/* Additional arg for JWE PBES2: base64url: salt */
+	LJJHI_P2C,	/* Additional arg for JWE PBES2: integer: count */
+
+	LWS_COUNT_JOSE_HDR_ELEMENTS
+};
+
+enum lws_jose_algtype {
+	LWS_JOSE_ENCTYPE_NONE,
+
+	LWS_JOSE_ENCTYPE_RSASSA_PKCS1_1_5,
+	LWS_JOSE_ENCTYPE_RSASSA_PKCS1_OAEP,
+	LWS_JOSE_ENCTYPE_RSASSA_PKCS1_PSS,
+
+	LWS_JOSE_ENCTYPE_ECDSA,
+	LWS_JOSE_ENCTYPE_ECDHES,
+
+	LWS_JOSE_ENCTYPE_AES_CBC,
+	LWS_JOSE_ENCTYPE_AES_CFB128,
+	LWS_JOSE_ENCTYPE_AES_CFB8,
+	LWS_JOSE_ENCTYPE_AES_CTR,
+	LWS_JOSE_ENCTYPE_AES_ECB,
+	LWS_JOSE_ENCTYPE_AES_OFB,
+	LWS_JOSE_ENCTYPE_AES_XTS,	/* care: requires double-length key */
+	LWS_JOSE_ENCTYPE_AES_GCM,
+};
+
+/* there's a table of these defined in lws-gencrypto-common.c */
+
+struct lws_jose_jwe_alg {
+	enum lws_genhash_types hash_type;
+	enum lws_genhmac_types hmac_type;
+	enum lws_jose_algtype algtype_signing; /* the signing cipher */
+	enum lws_jose_algtype algtype_crypto; /* the encryption cipher */
+	const char *alg; /* the JWA enc alg name, eg "ES512" */
+	const char *curve_name; /* NULL, or, eg, "P-256" */
+	unsigned short keybits_min, keybits_fixed;
+	unsigned short ivbits;
+};
+
+/*
+ * For JWS, "JOSE header" is defined to be the union of...
+ *
+ * o  JWS Protected Header
+ * o  JWS Unprotected Header
+ *
+ * For JWE, the "JOSE header" is the union of...
+ *
+ * o  JWE Protected Header
+ * o  JWE Shared Unprotected Header
+ * o  JWE Per-Recipient Unprotected Header
+ */
+
+#define LWS_JWS_MAX_RECIPIENTS 3
+
+struct lws_jws_recpient {
+	/*
+	 * JOSE per-recipient unprotected header... for JWS this contains
+	 * protected / header / signature
+	 */
+	struct lws_gencrypto_keyelem unprot[LWS_COUNT_JOSE_HDR_ELEMENTS];
+	struct lws_jwk jwk_ephemeral;	/* recipient ephemeral key if any */
+	struct lws_jwk jwk;		/* recipient "jwk" key if any */
+};
+
+struct lws_jose {
+	/* JOSE protected and unprotected header elements */
+	struct lws_gencrypto_keyelem e[LWS_COUNT_JOSE_HDR_ELEMENTS];
+
+	struct lws_jws_recpient recipient[LWS_JWS_MAX_RECIPIENTS];
+
+	char typ[32];
+
+	/* information from the protected header part */
+	const struct lws_jose_jwe_alg *alg;
+	const struct lws_jose_jwe_alg *enc_alg;
+
+	int recipients; /* count of used recipient[] entries */
+};
+
+/**
+ * lws_jose_init() - prepare a struct lws_jose for use
+ *
+ * \param jose: the jose header struct to prepare
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_jose_init(struct lws_jose *jose);
+
+/**
+ * lws_jose_destroy() - retire a struct lws_jose from use
+ *
+ * \param jose: the jose header struct to destroy
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_jose_destroy(struct lws_jose *jose);
+
+/**
+ * lws_gencrypto_jws_alg_to_definition() - look up a jws alg name
+ *
+ * \param alg: the jws alg name
+ * \param jose: pointer to the pointer to the info struct to set on success
+ *
+ * Returns 0 if *jose set, else nonzero for failure
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_gencrypto_jws_alg_to_definition(const char *alg,
+				    const struct lws_jose_jwe_alg **jose);
+
+/**
+ * lws_gencrypto_jwe_alg_to_definition() - look up a jwe alg name
+ *
+ * \param alg: the jwe alg name
+ * \param jose: pointer to the pointer to the info struct to set on success
+ *
+ * Returns 0 if *jose set, else nonzero for failure
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_gencrypto_jwe_alg_to_definition(const char *alg,
+				    const struct lws_jose_jwe_alg **jose);
+
+/**
+ * lws_gencrypto_jwe_enc_to_definition() - look up a jwe enc name
+ *
+ * \param alg: the jwe enc name
+ * \param jose: pointer to the pointer to the info struct to set on success
+ *
+ * Returns 0 if *jose set, else nonzero for failure
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_gencrypto_jwe_enc_to_definition(const char *enc,
+				    const struct lws_jose_jwe_alg **jose);
+
+/**
+ * lws_jws_parse_jose() - parse a JWS JOSE header
+ *
+ * \param jose: the jose struct to set to parsing results
+ * \param buf: the raw JOSE header
+ * \param len: the length of the raw JOSE header
+ * \param temp: parent-owned buffer to "allocate" elements into
+ * \param temp_len: amount of space available in temp
+ *
+ * returns 0 for success, or -1 for error
+ * *\p temp_len is updated to reflect the amount of \p temp used if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_parse_jose(struct lws_jose *jose,
+		   const char *buf, int len, char *temp, int *temp_len);
+
+/**
+ * lws_jwe_parse_jose() - parse a JWE JOSE header
+ *
+ * \param jose: the jose struct to set to parsing results
+ * \param buf: the raw JOSE header
+ * \param len: the length of the raw JOSE header
+ * \param temp: parent-owned buffer to "allocate" elements into
+ * \param temp_len: amount of space available in temp
+ *
+ * returns 0 for success, or -1 for error
+ * *\p temp_len is updated to reflect the amount of \p temp used if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_parse_jose(struct lws_jose *jose,
+		   const char *buf, int len, char *temp, int *temp_len);
+

include/libwebsockets/lws-jwe.h

@@ -0,0 +1,164 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * JWE Compact Serialization consists of
+ *
+ *     BASE64URL(UTF8(JWE Protected Header)) || '.' ||
+ *     BASE64URL(JWE Encrypted Key)	     || '.' ||
+ *     BASE64URL(JWE Initialization Vector)  || '.' ||
+ *     BASE64URL(JWE Ciphertext)	     || '.' ||
+ *     BASE64URL(JWE Authentication Tag)
+ */
+
+#define LWS_JWE_RFC3394_OVERHEAD_BYTES 8
+#define LWS_JWE_AES_IV_BYTES 16
+
+#define LWS_JWE_LIMIT_RSA_KEY_BITS 4096
+#define LWS_JWE_LIMIT_AES_KEY_BITS (512 + 64) /* RFC3394 Key Wrap adds 64b */
+#define LWS_JWE_LIMIT_EC_KEY_BITS  528 /* 521 rounded to byte boundary */
+#define LWS_JWE_LIMIT_HASH_BITS    (LWS_GENHASH_LARGEST * 8)
+
+/* the largest key element for any cipher */
+#define LWS_JWE_LIMIT_KEY_ELEMENT_BYTES (LWS_JWE_LIMIT_RSA_KEY_BITS / 8)
+
+
+struct lws_jwe {
+	struct lws_jose jose;
+	struct lws_jws jws;
+	struct lws_jwk jwk;
+
+	/*
+	 * We have to keep a copy of the CEK so we can reuse it with later
+	 * key encryptions for the multiple recipient case.
+	 */
+	uint8_t cek[LWS_JWE_LIMIT_KEY_ELEMENT_BYTES];
+	unsigned int cek_valid:1;
+
+	int recip;
+};
+
+LWS_VISIBLE LWS_EXTERN void
+lws_jwe_init(struct lws_jwe *jwe, struct lws_context *context);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_jwe_destroy(struct lws_jwe *jwe);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_jwe_be64(uint64_t c, uint8_t *p8);
+
+/*
+ * JWE Compact Serialization consists of
+ *
+ *     BASE64URL(UTF8(JWE Protected Header)) || '.' ||
+ *     BASE64URL(JWE Encrypted Key)	     || '.' ||
+ *     BASE64URL(JWE Initialization Vector)  || '.' ||
+ *     BASE64URL(JWE Ciphertext)	     || '.' ||
+ *     BASE64URL(JWE Authentication Tag)
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_render_compact(struct lws_jwe *jwe, char *out, size_t out_len);
+
+LWS_VISIBLE int
+lws_jwe_render_flattened(struct lws_jwe *jwe, char *out, size_t out_len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_json_parse(struct lws_jwe *jwe, const uint8_t *buf, int len,
+		   char *temp, int *temp_len);
+
+/**
+ * lws_jwe_auth_and_decrypt() - confirm and decrypt JWE
+ *
+ * \param jose: jose context
+ * \param jws: jws / jwe context... .map and .map_b64 must be filled already
+ *
+ * This is a high level JWE decrypt api that takes a jws with the maps
+ * already processed, and if the authentication passes, returns the decrypted
+ * plaintext in jws.map.buf[LJWE_CTXT] and its length in jws.map.len[LJWE_CTXT].
+ *
+ * In the jws, the following fields must have been set by the caller
+ *
+ * .context
+ * .jwk (the key encryption key)
+ * .map
+ * .map_b64
+ *
+ * Having the b64 and decoded maps filled externally makes it flexible where
+ * the data was picked from, eg, from a Complete JWE JSON serialization, a
+ * flattened one, or a Compact Serialization.
+ *
+ * Returns decrypt length, or -1 for failure.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_auth_and_decrypt(struct lws_jwe *jwe, char *temp, int *temp_len);
+
+/**
+ * lws_jwe_encrypt() - perform JWE encryption
+ *
+ * \param jose: the JOSE header information (encryption types, etc)
+ * \param jws: the JWE elements, pointer to jwk etc
+ * \param temp: parent-owned buffer to "allocate" elements into
+ * \param temp_len: amount of space available in temp
+ *
+ * May be called up to LWS_JWS_MAX_RECIPIENTS times to encrypt the same CEK
+ * multiple ways on the same JWE payload.
+ *
+ * returns the amount of temp used, or -1 for error.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_encrypt(struct lws_jwe *jwe, char *temp, int *temp_len);
+
+/**
+ * lws_jwe_create_packet() - add b64 sig to b64 hdr + payload
+ *
+ * \param jwe: the struct lws_jwe we are trying to render
+ * \param payload: unencoded payload JSON
+ * \param len: length of unencoded payload JSON
+ * \param nonce: Nonse string to include in protected header
+ * \param out: buffer to take signed packet
+ * \param out_len: size of \p out buffer
+ * \param conext: lws_context to get random from
+ *
+ * This creates a "flattened" JWS packet from the jwk and the plaintext
+ * payload, and signs it.  The packet is written into \p out.
+ *
+ * This does the whole packet assembly and signing, calling through to
+ * lws_jws_sign_from_b64() as part of the process.
+ *
+ * Returns the length written to \p out, or -1.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_create_packet(struct lws_jwe *jwe,
+		      const char *payload, size_t len, const char *nonce,
+		      char *out, size_t out_len, struct lws_context *context);
+
+
+/* only exposed because we have test vectors that need it */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwe_auth_and_decrypt_cbc_hs(struct lws_jwe *jwe, uint8_t *enc_cek,
+					uint8_t *aad, int aad_len);
+
+/* only exposed because we have test vectors that need it */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwa_concat_kdf(struct lws_jwe *jwe, int direct,
+		   uint8_t *out, const uint8_t *shared_secret, int sslen);

include/libwebsockets/lws-jwk.h

@@ -0,0 +1,220 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup jwk JSON Web Keys
+ * ## JSON Web Keys API
+ *
+ * Lws provides an API to parse JSON Web Keys into a struct lws_gencrypto_keyelem.
+ *
+ * "oct" and "RSA" type keys are supported.  For "oct" keys, they are held in
+ * the "e" member of the struct lws_gencrypto_keyelem.
+ *
+ * Keys elements are allocated on the heap.  You must destroy the allocations
+ * in the struct lws_gencrypto_keyelem by calling
+ * lws_genrsa_destroy_elements() when you are finished with it.
+ */
+///@{
+
+enum enum_jwk_meta_tok {
+	JWK_META_KTY,
+	JWK_META_KID,
+	JWK_META_USE,
+	JWK_META_KEY_OPS,
+	JWK_META_X5C,
+	JWK_META_ALG,
+
+	LWS_COUNT_JWK_ELEMENTS
+};
+
+struct lws_jwk {
+	/* key data elements */
+	struct lws_gencrypto_keyelem e[LWS_GENCRYPTO_MAX_KEYEL_COUNT];
+	/* generic meta key elements, like KID */
+	struct lws_gencrypto_keyelem meta[LWS_COUNT_JWK_ELEMENTS];
+	int kty;			/**< one of LWS_GENCRYPTO_KTY_ */
+	char private_key; /* nonzero = has private key elements */
+};
+
+typedef int (*lws_jwk_key_import_callback)(struct lws_jwk *s, void *user);
+
+struct lws_jwk_parse_state {
+	struct lws_jwk *jwk;
+	char b64[(((8192 / 8) * 4) / 3) + 1]; /* enough for 8Kb key */
+	lws_jwk_key_import_callback per_key_cb;
+	void *user;
+	int pos;
+	int cose_state;
+	int seen;
+	unsigned short possible;
+};
+
+/** lws_jwk_import() - Create a JSON Web key from the textual representation
+ *
+ * \param jwk: the JWK object to create
+ * \param cb: callback for each jwk-processed key, or NULL if importing a single
+ *	      key with no parent "keys" JSON
+ * \param user: pointer to be passed to the callback, otherwise ignored by lws.
+ *		NULL if importing a single key with no parent "keys" JSON
+ * \param in: a single JWK JSON stanza in utf-8
+ * \param len: the length of the JWK JSON stanza in bytes
+ *
+ * Creates an lws_jwk struct filled with data from the JSON representation.
+ *
+ * There are two ways to use this... with some protocols a single jwk is
+ * delivered with no parent "keys": [] array.  If you call this with cb and
+ * user as NULL, then the input will be interpreted like that and the results
+ * placed in s.
+ *
+ * The second case is that you are dealing with a "keys":[] array with one or
+ * more keys in it.  In this case, the function iterates through the keys using
+ * s as a temporary jwk, and calls the user-provided callback for each key in
+ * turn while it return 0 (nonzero return from the callback terminates the
+ * iteration through any further keys).
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_import(struct lws_jwk *jwk, lws_jwk_key_import_callback cb, void *user,
+	       const char *in, size_t len);
+
+/** lws_jwk_destroy() - Destroy a JSON Web key
+ *
+ * \param jwk: the JWK object to destroy
+ *
+ * All allocations in the lws_jwk are destroyed
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_jwk_destroy(struct lws_jwk *jwk);
+
+/** lws_jwk_dup_oct() - Set a jwk to a dup'd binary OCT key
+ *
+ * \param jwk: the JWK object to set
+ * \param key: the JWK object to destroy
+ * \param len: the JWK object to destroy
+ *
+ * Sets the kty to OCT, allocates len bytes for K and copies len bytes of key
+ * into the allocation.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_dup_oct(struct lws_jwk *jwk, const void *key, int len);
+
+#define LWSJWKF_EXPORT_PRIVATE				(1 << 0)
+#define LWSJWKF_EXPORT_NOCRLF				(1 << 1)
+
+/** lws_jwk_export() - Export a JSON Web key to a textual representation
+ *
+ * \param jwk: the JWK object to export
+ * \param flags: control export options
+ * \param p: the buffer to write the exported JWK to
+ * \param len: the length of the buffer \p p in bytes... reduced by used amount
+ *
+ * Returns length of the used part of the buffer if OK, or -1 for error.
+ *
+ * \p flags can be OR-ed together
+ *
+ * LWSJWKF_EXPORT_PRIVATE: default is only public part, set this to also export
+ *			   the private part
+ *
+ * LWSJWKF_EXPORT_NOCRLF: normally adds a CRLF at the end of the export, if
+ *			  you need to suppress it, set this flag
+ *
+ * Serializes the content of the JWK into a char buffer.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_export(struct lws_jwk *jwk, int flags, char *p, int *len);
+
+/** lws_jwk_load() - Import a JSON Web key from a file
+ *
+ * \param jwk: the JWK object to load into
+ * \param filename: filename to load from
+ * \param cb: optional callback for each key
+ * \param user: opaque user pointer passed to cb if given
+ *
+ * Returns 0 for OK or -1 for failure
+ *
+ * There are two ways to use this... with some protocols a single jwk is
+ * delivered with no parent "keys": [] array.  If you call this with cb and
+ * user as NULL, then the input will be interpreted like that and the results
+ * placed in s.
+ *
+ * The second case is that you are dealing with a "keys":[] array with one or
+ * more keys in it.  In this case, the function iterates through the keys using
+ * s as a temporary jwk, and calls the user-provided callback for each key in
+ * turn while it return 0 (nonzero return from the callback terminates the
+ * iteration through any further keys, leaving the last one in s).
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_load(struct lws_jwk *jwk, const char *filename,
+	     lws_jwk_key_import_callback cb, void *user);
+
+/** lws_jwk_save() - Export a JSON Web key to a file
+ *
+ * \param jwk: the JWK object to save from
+ * \param filename: filename to save to
+ *
+ * Returns 0 for OK or -1 for failure
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_save(struct lws_jwk *jwk, const char *filename);
+
+/** lws_jwk_rfc7638_fingerprint() - jwk to RFC7638 compliant fingerprint
+ *
+ * \param jwk: the JWK object to fingerprint
+ * \param digest32: buffer to take 32-byte digest
+ *
+ * Returns 0 for OK or -1 for failure
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_rfc7638_fingerprint(struct lws_jwk *jwk, char *digest32);
+
+/** lws_jwk_strdup_meta() - allocate a duplicated string meta element
+ *
+ * \param jwk: the JWK object to fingerprint
+ * \param idx: JWK_META_ element index
+ * \param in: string to copy
+ * \param len: length of string to copy
+ *
+ * Returns 0 for OK or nonzero for failure
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_strdup_meta(struct lws_jwk *jwk, enum enum_jwk_meta_tok idx,
+		    const char *in, int len);
+
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jwk_dump(struct lws_jwk *jwk);
+
+/** lws_jwk_generate() - create a new key of given type and characteristics
+ *
+ * \param context: the struct lws_context used for RNG
+ * \param jwk: the JWK object to fingerprint
+ * \param kty: One of the LWS_GENCRYPTO_KTY_ key types
+ * \param bits: for OCT and RSA keys, the number of bits
+ * \param curve: for EC keys, the name of the curve
+ *
+ * Returns 0 for OK or nonzero for failure
+ */
+LWS_VISIBLE int
+lws_jwk_generate(struct lws_context *context, struct lws_jwk *jwk,
+	         enum lws_gencrypto_kty kty, int bits, const char *curve);
+
+///@}

include/libwebsockets/lws-jws.h

@@ -0,0 +1,601 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup jws JSON Web Signature
+ * ## JSON Web Signature API
+ *
+ * Lws provides an API to check and create RFC7515 JSON Web Signatures
+ *
+ * SHA256/384/512 HMAC, and RSA 256/384/512 are supported.
+ *
+ * The API uses your TLS library crypto, but works exactly the same no matter
+ * what your TLS backend is.
+ */
+///@{
+
+/*
+ * The maps are built to work with both JWS (LJWS_) and JWE (LJWE_), and are
+ * sized to the slightly larger JWE case.
+ */
+
+enum enum_jws_sig_elements {
+
+	/* JWS block namespace */
+	LJWS_JOSE,
+	LJWS_PYLD,
+	LJWS_SIG,
+	LJWS_UHDR,
+
+	/* JWE block namespace */
+	LJWE_JOSE = 0,
+	LJWE_EKEY,
+	LJWE_IV,
+	LJWE_CTXT,
+	LJWE_ATAG,
+	LJWE_AAD,
+
+	LWS_JWS_MAX_COMPACT_BLOCKS
+};
+
+struct lws_jws_map {
+	const char *buf[LWS_JWS_MAX_COMPACT_BLOCKS];
+	uint32_t len[LWS_JWS_MAX_COMPACT_BLOCKS];
+};
+
+#define LWS_JWS_MAX_SIGS 3
+
+struct lws_jws {
+	struct lws_jwk *jwk; /* the struct lws_jwk containing the signing key */
+	struct lws_context *context; /* the lws context (used to get random) */
+	struct lws_jws_map map, map_b64;
+};
+
+/* jws EC signatures do not have ASN.1 in them, meaning they're incompatible
+ * with generic signatures.
+ */
+
+/**
+ * lws_jws_init() - initialize a jws for use
+ *
+ * \param jws: pointer to the jws to initialize
+ * \param jwk: the jwk to use with this jws
+ * \param context: the lws_context to use
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_jws_init(struct lws_jws *jws, struct lws_jwk *jwk,
+	     struct lws_context *context);
+
+/**
+ * lws_jws_destroy() - scrub a jws
+ *
+ * \param jws: pointer to the jws to destroy
+ *
+ * Call before the jws goes out of scope.
+ *
+ * Elements defined in the jws are zeroed.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_jws_destroy(struct lws_jws *jws);
+
+/**
+ * lws_jws_sig_confirm_compact() - check signature
+ *
+ * \param map: pointers and lengths for each of the unencoded JWS elements
+ * \param jwk: public key
+ * \param context: lws_context
+ * \param temp: scratchpad
+ * \param temp_len: length of scratchpad
+ *
+ * Confirms the signature on a JWS.  Use if you have non-b64 plain JWS elements
+ * in a map... it'll make a temp b64 version needed for comparison.  See below
+ * for other variants.
+ *
+ * Returns 0 on match, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_sig_confirm_compact(struct lws_jws_map *map, struct lws_jwk *jwk,
+			    struct lws_context *context,
+			    char *temp, int *temp_len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_sig_confirm_compact_b64_map(struct lws_jws_map *map_b64,
+				    struct lws_jwk *jwk,
+			            struct lws_context *context,
+			            char *temp, int *temp_len);
+
+/**
+ * lws_jws_sig_confirm_compact_b64() - check signature on b64 compact JWS
+ *
+ * \param in: pointer to b64 jose.payload[.hdr].sig
+ * \param len: bytes available at \p in
+ * \param map: map to take decoded non-b64 content
+ * \param jwk: public key
+ * \param context: lws_context
+ * \param temp: scratchpad
+ * \param temp_len: size of scratchpad
+ *
+ * Confirms the signature on a JWS.  Use if you have you have b64 compact layout
+ * (jose.payload.hdr.sig) as an aggregated string... it'll make a temp plain
+ * version needed for comparison.
+ *
+ * Returns 0 on match, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_sig_confirm_compact_b64(const char *in, size_t len,
+				struct lws_jws_map *map,
+				struct lws_jwk *jwk,
+				struct lws_context *context,
+				char *temp, int *temp_len);
+
+/**
+ * lws_jws_sig_confirm() - check signature on plain + b64 JWS elements
+ *
+ * \param map_b64: pointers and lengths for each of the b64-encoded JWS elements
+ * \param map: pointers and lengths for each of the unencoded JWS elements
+ * \param jwk: public key
+ * \param context: lws_context
+ *
+ * Confirms the signature on a JWS.  Use if you have you already have both b64
+ * compact layout (jose.payload.hdr.sig) and decoded JWS elements in maps.
+ *
+ * If you had the b64 string and called lws_jws_compact_decode() on it, you
+ * will end up with both maps, and can use this api version, saving needlessly
+ * regenerating any temp map.
+ *
+ * Returns 0 on match, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_sig_confirm(struct lws_jws_map *map_b64, /* b64-encoded */
+		    struct lws_jws_map *map,	/* non-b64 */
+		    struct lws_jwk *jwk, struct lws_context *context);
+
+/**
+ * lws_jws_sign_from_b64() - add b64 sig to b64 hdr + payload
+ *
+ * \param jose: jose header information
+ * \param jws: information to include in the signature
+ * \param b64_sig: output buffer for b64 signature
+ * \param sig_len: size of \p b64_sig output buffer
+ *
+ * This adds a b64-coded JWS signature of the b64-encoded protected header
+ * and b64-encoded payload, at \p b64_sig.  The signature will be as large
+ * as the N element of the RSA key when the RSA key is used, eg, 512 bytes for
+ * a 4096-bit key, and then b64-encoding on top.
+ *
+ * In some special cases, there is only payload to sign and no header, in that
+ * case \p b64_hdr may be NULL, and only the payload will be hashed before
+ * signing.
+ *
+ * If successful, returns the length of the encoded signature written to
+ * \p b64_sig.  If the jose signing type is unknown, 0 is returned.  Otherwise
+ * -1 indicates failure.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_sign_from_b64(struct lws_jose *jose, struct lws_jws *jws, char *b64_sig,
+			size_t sig_len);
+
+/**
+ * lws_jws_compact_decode() - converts and maps compact serialization b64 sections
+ *
+ * \param in: the incoming compact serialized b64
+ * \param len: the length of the incoming compact serialized b64
+ * \param map: pointer to the results structure
+ * \param map_b64: NULL, or pointer to a second results structure taking block
+ *		   information about the undecoded b64
+ * \param out: buffer to hold decoded results
+ * \param out_len: size of out in bytes
+ *
+ * Returns number of sections (2 if "none", else 3), or -1 if illegal.
+ *
+ * map is set to point to the start and hold the length of each decoded block.
+ * If map_b64 is non-NULL, then it's set with information about the input b64
+ * blocks.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_compact_decode(const char *in, int len, struct lws_jws_map *map,
+		struct lws_jws_map *map_b64, char *out, int *out_len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_compact_encode(struct lws_jws_map *map_b64, /* b64-encoded */
+		       const struct lws_jws_map *map,	/* non-b64 */
+		       char *buf, int *out_len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_sig_confirm_json(const char *in, size_t len,
+			 struct lws_jws *jws, struct lws_jwk *jwk,
+			 struct lws_context *context,
+			 char *temp, int *temp_len);
+
+/**
+ * lws_jws_write_flattened_json() - create flattened JSON sig
+ *
+ * \param jws: information to include in the signature
+ * \param flattened: output buffer for JSON
+ * \param len: size of \p flattened output buffer
+ *
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_write_flattened_json(struct lws_jws *jws, char *flattened, size_t len);
+
+/**
+ * lws_jws_write_compact() - create flattened JSON sig
+ *
+ * \param jws: information to include in the signature
+ * \param compact: output buffer for compact format
+ * \param len: size of \p flattened output buffer
+ *
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_write_compact(struct lws_jws *jws, char *compact, size_t len);
+
+
+
+/*
+ * below apis are not normally needed if dealing with whole JWS... they're
+ * useful for creating from scratch
+ */
+
+
+/**
+ * lws_jws_dup_element() - allocate space for an element and copy data into it
+ *
+ * \param map: map to create the element in
+ * \param idx: index of element in the map to create
+ * \param temp: space to allocate in
+ * \param temp_len: available space at temp
+ * \param in: data to duplicate into element
+ * \param in_len: length of data to duplicate
+ * \param actual_alloc: 0 for same as in_len, else actual allocation size
+ *
+ * Copies in_len from in to temp, if temp_len is sufficient.
+ *
+ * Returns 0 or -1 if not enough space in temp / temp_len.
+ *
+ * Over-allocation can be acheived by setting actual_alloc to the real
+ * allocation desired... in_len will be copied into it.
+ *
+ * *temp_len is reduced by actual_alloc if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_dup_element(struct lws_jws_map *map, int idx,
+		    char *temp, int *temp_len, const void *in, size_t in_len,
+		    size_t actual_alloc);
+
+/**
+ * lws_jws_randomize_element() - create an element and fill with random
+ *
+ * \param context: lws_context used for random
+ * \param map: map to create the element in
+ * \param idx: index of element in the map to create
+ * \param temp: space to allocate in
+ * \param temp_len: available space at temp
+ * \param random_len: length of data to fill with random
+ * \param actual_alloc: 0 for same as random_len, else actual allocation size
+ *
+ * Randomize random_len bytes at temp, if temp_len is sufficient.
+ *
+ * Returns 0 or -1 if not enough space in temp / temp_len.
+ *
+ * Over-allocation can be acheived by setting actual_alloc to the real
+ * allocation desired... the first random_len will be filled with random.
+ *
+ * *temp_len is reduced by actual_alloc if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_randomize_element(struct lws_context *context,
+			  struct lws_jws_map *map,
+			  int idx, char *temp, int *temp_len, size_t random_len,
+			  size_t actual_alloc);
+
+/**
+ * lws_jws_alloc_element() - create an element and reserve space for content
+ *
+ * \param map: map to create the element in
+ * \param idx: index of element in the map to create
+ * \param temp: space to allocate in
+ * \param temp_len: available space at temp
+ * \param len: logical length of element
+ * \param actual_alloc: 0 for same as len, else actual allocation size
+ *
+ * Allocate len bytes at temp, if temp_len is sufficient.
+ *
+ * Returns 0 or -1 if not enough space in temp / temp_len.
+ *
+ * Over-allocation can be acheived by setting actual_alloc to the real
+ * allocation desired... the element logical length will be set to len.
+ *
+ * *temp_len is reduced by actual_alloc if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_alloc_element(struct lws_jws_map *map, int idx, char *temp,
+		      int *temp_len, size_t len, size_t actual_alloc);
+
+/**
+ * lws_jws_encode_b64_element() - create an b64-encoded element
+ *
+ * \param map: map to create the element in
+ * \param idx: index of element in the map to create
+ * \param temp: space to allocate in
+ * \param temp_len: available space at temp
+ * \param in: pointer to unencoded input
+ * \param in_len: length of unencoded input
+ *
+ * Allocate len bytes at temp, if temp_len is sufficient.
+ *
+ * Returns 0 or -1 if not enough space in temp / temp_len.
+ *
+ * Over-allocation can be acheived by setting actual_alloc to the real
+ * allocation desired... the element logical length will be set to len.
+ *
+ * *temp_len is reduced by actual_alloc if successful.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_encode_b64_element(struct lws_jws_map *map, int idx,
+			   char *temp, int *temp_len, const void *in,
+			   size_t in_len);
+
+
+/**
+ * lws_jws_b64_compact_map() - find block starts and lengths in compact b64
+ *
+ * \param in: pointer to b64 jose.payload[.hdr].sig
+ * \param len: bytes available at \p in
+ * \param map: output struct with pointers and lengths for each JWS element
+ *
+ * Scans a jose.payload[.hdr].sig b64 string and notes where the blocks start
+ * and their length into \p map.
+ *
+ * Returns number of blocks if OK.  May return <0 if malformed.
+ * May not fill all map entries.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_b64_compact_map(const char *in, int len, struct lws_jws_map *map);
+
+
+/**
+ * lws_jws_base64_enc() - encode input data into b64url data
+ *
+ * \param in: the incoming plaintext
+ * \param in_len: the length of the incoming plaintext in bytes
+ * \param out: the buffer to store the b64url encoded data to
+ * \param out_max: the length of \p out in bytes
+ *
+ * Returns either -1 if problems, or the number of bytes written to \p out.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_base64_enc(const char *in, size_t in_len, char *out, size_t out_max);
+
+/**
+ * lws_jws_encode_section() - encode input data into b64url data,
+ *				prepending . if not first
+ *
+ * \param in: the incoming plaintext
+ * \param in_len: the length of the incoming plaintext in bytes
+ * \param first: nonzero if the first section
+ * \param p: the buffer to store the b64url encoded data to
+ * \param end: just past the end of p
+ *
+ * Returns either -1 if problems, or the number of bytes written to \p out.
+ * If the section is not the first one, '.' is prepended.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jws_encode_section(const char *in, size_t in_len, int first, char **p,
+		       char *end);
+
+/**
+ * lws_jwt_signed_validate() - check a compact JWT against a key and alg
+ *
+ * \param ctx: the lws_context
+ * \param jwk: the key for checking the signature
+ * \param alg_list: the expected alg name, like "ES512"
+ * \param com: the compact JWT
+ * \param len: the length of com
+ * \param temp: a temp scratchpad
+ * \param tl: available length of temp scratchpad
+ * \param out: the output buffer to hold the validated plaintext
+ * \param out_len: on entry, max length of out; on exit, used length of out
+ *
+ * Returns nonzero if the JWT cannot be validated or the plaintext can't fit the
+ * provided output buffer, or 0 if it is validated as being signed by the
+ * provided jwk.
+ *
+ * If validated, the plaintext in the JWT is copied into out and out_len set to
+ * the used length.
+ *
+ * temp can be discarded or reused after the call returned, it's used to hold
+ * transformations of the B64 JWS in the JWT.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwt_signed_validate(struct lws_context *ctx, struct lws_jwk *jwk,
+			const char *alg_list, const char *com, size_t len,
+			char *temp, int tl, char *out, size_t *out_len);
+
+/**
+ * lws_jwt_sign_compact() - generate a compact JWT using a key and alg
+ *
+ * \param ctx: the lws_context
+ * \param jwk: the signing key
+ * \param alg: the signing alg name, like "ES512"
+ * \param out: the output buffer to hold the signed JWT in compact form
+ * \param out_len: on entry, the length of out; on exit, the used amount of out
+ * \param temp: a temp scratchpad
+ * \param tl: available length of temp scratchpad
+ * \param format: a printf style format specification
+ * \param ...: zero or more args for the format specification
+ *
+ * Creates a JWT in a single step, from the format string and args through to
+ * outputting a well-formed compact JWT representation in out.
+ *
+ * Returns 0 if all is well and *out_len is the amount of data in out, else
+ * nonzero if failed.  Temp must be large enough to hold various intermediate
+ * representations.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwt_sign_compact(struct lws_context *ctx, struct lws_jwk *jwk,
+		     const char *alg, char *out, size_t *out_len, char *temp,
+		     int tl, const char *format, ...) LWS_FORMAT(8);
+
+struct lws_jwt_sign_info {
+	const char *alg;
+	/**< entry: signing alg name, like "RS256" */
+	const char *jose_hdr;
+	/**< entry: optional JOSE hdr; if present, alg field is ignored; instead the
+	 *          whole claim object has to be provided in this parameter */
+	size_t jose_hdr_len;
+	/**< entry: if jose_hdr is not NULL, JOSE header length without terminating '\0' */
+	char *out;
+	/**< exit: signed JWT in compact form*/
+	size_t *out_len;
+	/**< entry,exit: buffer size of out; actual size of JWT on exit */
+	char *temp;
+	/**< exit undefined content, used by the function as a temporary scratchpad; MUST
+	 * be large enogh to store various intermediate representations */
+	int tl;
+	/**< entry: size of temp buffer */
+};
+
+/**
+ * lws_jwt_sign_compact() - generate a compact JWT using a key and JOSE header
+ *
+ * \param ctx: the lws_context
+ * \param jwk: the signing key
+ * \param info: info describing the JWT's content and output/temp buffers
+ * \param format: a printf style format specification of the claims object
+ * \param ...: zero or more args for the format specification
+ *
+ * Creates a JWT in a single step, from the format string and args through to
+ * outputting a well-formed compact JWT representation in out. The provided
+ * JOSE header's syntax is checked before it is added to the JWT.
+ *
+ * Returns 0 if all is well and *out_len is the amount of data in out, else
+ * nonzero if failed.  Temp must be large enough to hold various intermediate
+ * representations.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwt_sign_via_info(struct lws_context *ctx, struct lws_jwk *jwk,
+         const struct lws_jwt_sign_info *info, const char *format, ...) LWS_FORMAT(4);
+
+/**
+ * lws_jwt_token_sanity() - check a validated jwt payload for sanity
+ *
+ * \param in: the JWT payload
+ * \param in_len: the length of the JWT payload
+ * \param iss: the expected issuer of the token
+ * \param aud: the expected audience of the token
+ * \param csrf_in: NULL, or the csrf token that came in on a URL
+ * \param sub: a buffer to hold the subject name in the JWT (eg, account name)
+ * \param sub_len: the max length of the sub buffer
+ * \param secs_left: set to the number of seconds of valid auth left if valid
+ *
+ * This performs some generic sanity tests on validated JWT payload...
+ *
+ *  - the issuer is as expected
+ *  - the audience is us
+ *  - current time is OK for nbf ("not before") in the token
+ *  - current time is OK for exp ("expiry") in the token
+ *  - if csrf_in is not NULL, that the JWK has a csrf and it matches it
+ *  - if sub is not NULL, that the JWK provides a subject (and copies it to sub)
+ *
+ * If the tests pass, *secs_left is set to the number of remaining seconds the
+ * auth is valid.
+ *
+ * Returns 0 if no inconsistency, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwt_token_sanity(const char *in, size_t in_len,
+		     const char *iss, const char *aud, const char *csrf_in,
+		     char *sub, size_t sub_len, unsigned long *exp_unix_time);
+
+#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2)
+
+struct lws_jwt_sign_set_cookie {
+	struct lws_jwk			*jwk;
+	/**< entry: required signing key */
+	const char			*alg;
+	/**< entry: required signing alg, eg, "ES512" */
+	const char 			*iss;
+	/**< entry: issuer name to use */
+	const char			*aud;
+	/**< entry: audience */
+	const char			*cookie_name;
+	/**< entry: the name of the cookie */
+	char				sub[33];
+	/**< sign-entry, validate-exit: subject */
+	const char			*extra_json;
+	/**< sign-entry, validate-exit:
+	 * optional "ext" JSON object contents for the JWT */
+	size_t				extra_json_len;
+	/**< validate-exit:
+	 * length of optional "ext" JSON object contents for the JWT */
+	const char			*csrf_in;
+	/**< validate-entry:
+	 * NULL, or an external CSRF token to check against what is in the JWT */
+	unsigned long			expiry_unix_time;
+	/**< sign-entry: seconds the JWT and cookie may live,
+	 * validate-exit: expiry unix time */
+};
+
+/**
+ * lws_jwt_sign_token_set_http_cookie() - creates sets a JWT in a wsi cookie
+ *
+ * \param wsi: the wsi to create the cookie header on
+ * \param i: structure describing what should be in the JWT
+ * \param p: wsi headers area
+ * \param end: end of wsi headers area
+ *
+ * Creates a JWT specified \p i, and attaches it to the outgoing headers on
+ * wsi.  Returns 0 if successful.
+ *
+ * Best-practice security restrictions are applied to the cookie set action,
+ * including forcing httponly, and __Host- prefix.  As required by __Host-, the
+ * cookie Path is set to /.  __Host- is applied by the function, the cookie_name
+ * should just be "xyz" for "__Host-xyz".
+ *
+ * \p extra_json should just be the bare JSON, a { } is provided around it by
+ * the function if it's non-NULL.  For example, "\"authorization\": 1".
+ *
+ * It's recommended the secs parameter is kept as small as consistent with one
+ * user session on the site if possible, eg, 10 minutes or 20 minutes.  At the
+ * server, it can determine how much time is left in the auth and inform the
+ * client; if the JWT validity expires, the page should reload so the UI always
+ * reflects what's possible to do with the authorization state correctly.  If
+ * the JWT expires, the user can log back in using credentials usually stored in
+ * the browser and auto-filled-in, so this is not very inconvenient.
+ *
+ * This is a helper on top of the other JOSE and JWT apis that somewhat crosses
+ * over between JWT and HTTP, since it knows about cookies.  So it is only built
+ * if both LWS_WITH_JOSE and one of the http-related roles enabled.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_jwt_sign_token_set_http_cookie(struct lws *wsi,
+				   const struct lws_jwt_sign_set_cookie *i,
+				   uint8_t **p, uint8_t *end);
+LWS_VISIBLE LWS_EXTERN int
+lws_jwt_get_http_cookie_validate_jwt(struct lws *wsi,
+				     struct lws_jwt_sign_set_cookie *i,
+				     char *out, size_t *out_len);
+#endif
+
+///@}

include/libwebsockets/lws-lecp.h

@@ -0,0 +1,539 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup lecp CBOR parser
+ * ##CBOR parsing related functions
+ * \ingroup lwsapi
+ *
+ * LECP is an extremely lightweight CBOR stream parser included in lws.  It
+ * is aligned in approach with the LEJP JSON stream parser, with some additional
+ * things needed for CBOR.
+ */
+//@{
+
+#ifndef LECP_MAX_PARSING_STACK_DEPTH
+#define LECP_MAX_PARSING_STACK_DEPTH	5
+#endif
+#ifndef LECP_MAX_DEPTH
+#define LECP_MAX_DEPTH			12
+#endif
+#ifndef LECP_MAX_INDEX_DEPTH
+#define LECP_MAX_INDEX_DEPTH		8
+#endif
+#ifndef LECP_MAX_PATH
+#define LECP_MAX_PATH			128
+#endif
+#ifndef LECP_STRING_CHUNK
+/* must be >= 30 to assemble floats */
+#define LECP_STRING_CHUNK		254
+#endif
+
+#define LECP_FLAG_CB_IS_VALUE 64
+
+/*
+ * CBOR initial byte 3 x MSB bits are these
+ */
+
+enum {
+	LWS_CBOR_MAJTYP_UINT		= 0 << 5,
+	LWS_CBOR_MAJTYP_INT_NEG		= 1 << 5,
+	LWS_CBOR_MAJTYP_BSTR		= 2 << 5,
+	LWS_CBOR_MAJTYP_TSTR		= 3 << 5,
+	LWS_CBOR_MAJTYP_ARRAY		= 4 << 5,
+	LWS_CBOR_MAJTYP_MAP		= 5 << 5,
+	LWS_CBOR_MAJTYP_TAG		= 6 << 5,
+	LWS_CBOR_MAJTYP_FLOAT		= 7 << 5,  /* also BREAK */
+
+	LWS_CBOR_MAJTYP_MASK		= 7 << 5,
+
+	/*
+	 * For the low 5 bits of the opcode, 0-23 are literals, unless it's
+	 * FLOAT.
+	 *
+	 * 24 = 1 byte; 25 = 2..., 26 = 4... and 27 = 8 bytes following literal.
+	 */
+	LWS_CBOR_1			= 24,
+	LWS_CBOR_2			= 25,
+	LWS_CBOR_4			= 26,
+	LWS_CBOR_8			= 27,
+
+	LWS_CBOR_RESERVED		= 28,
+
+	LWS_CBOR_SUBMASK		= 0x1f,
+
+	/*
+	 * Major type 7 discriminators in low 5 bits
+	 * 0 - 23 is SIMPLE implicit value (like, eg, LWS_CBOR_SWK_TRUE)
+	 */
+	LWS_CBOR_SWK_FALSE		= 20,
+	LWS_CBOR_SWK_TRUE		= 21,
+	LWS_CBOR_SWK_NULL		= 22,
+	LWS_CBOR_SWK_UNDEFINED		= 23,
+
+	LWS_CBOR_M7_SUBTYP_SIMPLE_X8	= 24, /* simple with additional byte */
+	LWS_CBOR_M7_SUBTYP_FLOAT16	= 25,
+	LWS_CBOR_M7_SUBTYP_FLOAT32	= 26,
+	LWS_CBOR_M7_SUBTYP_FLOAT64	= 27,
+	LWS_CBOR_M7_BREAK		= 31,
+
+/* 28, 29, 30 are illegal.
+ *
+ * 31 is illegal for UINT, INT_NEG, and TAG;
+ *               for BSTR, TSTR, ARRAY and MAP it means "indefinite length", ie,
+ *               it's made up of an endless amount of determinite-length
+ *               fragments terminated with a BREAK (FLOAT | 31) instead of the
+ *               next determinite-length fragment.  The second framing level
+ *               means no need for escapes for BREAK in the data.
+ */
+
+	LWS_CBOR_INDETERMINITE		= 31,
+
+/*
+ * Well-known tags
+ */
+
+	LWS_CBOR_WKTAG_DATETIME_STD	= 0, /* text */
+	LWS_CBOR_WKTAG_DATETIME_EPOCH	= 1, /* int or float */
+	LWS_CBOR_WKTAG_BIGNUM_UNSIGNED	= 2, /* byte string */
+	LWS_CBOR_WKTAG_BIGNUM_NEGATIVE	= 3, /* byte string */
+	LWS_CBOR_WKTAG_DECIMAL_FRAC	= 4, /* array */
+	LWS_CBOR_WKTAG_BIGFLOAT		= 5, /* array */
+
+	LWS_CBOR_WKTAG_COSE_ENC0	= 16,
+	LWS_CBOR_WKTAG_COSE_MAC0	= 17,
+	LWS_CBOR_WKTAG_COSE_SIGN1	= 18,
+
+	LWS_CBOR_WKTAG_TO_B64U		= 21, /* any */
+	LWS_CBOR_WKTAG_TO_B64		= 22, /* any */
+	LWS_CBOR_WKTAG_TO_B16		= 23, /* any */
+	LWS_CBOR_WKTAG_CBOR		= 24, /* byte string */
+
+	LWS_CBOR_WKTAG_URI		= 32, /* text string */
+	LWS_CBOR_WKTAG_B64U		= 33, /* text string */
+	LWS_CBOR_WKTAG_B64		= 34, /* text string */
+	LWS_CBOR_WKTAG_MIME		= 36, /* text string */
+
+	LWS_CBOR_WKTAG_COSE_ENC		= 96,
+	LWS_CBOR_WKTAG_COSE_MAC		= 97,
+	LWS_CBOR_WKTAG_COSE_SIGN	= 98,
+
+	LWS_CBOR_WKTAG_SELFDESCCBOR	= 55799
+};
+
+enum lecp_callbacks {
+	LECPCB_CONSTRUCTED		= 0,
+	LECPCB_DESTRUCTED		= 1,
+
+	LECPCB_COMPLETE			= 3,
+	LECPCB_FAILED			= 4,
+
+	LECPCB_PAIR_NAME		= 5,
+
+	LECPCB_VAL_TRUE			= LECP_FLAG_CB_IS_VALUE | 6,
+	LECPCB_VAL_FALSE		= LECP_FLAG_CB_IS_VALUE | 7,
+	LECPCB_VAL_NULL			= LECP_FLAG_CB_IS_VALUE | 8,
+	LECPCB_VAL_NUM_INT		= LECP_FLAG_CB_IS_VALUE | 9,
+	LECPCB_VAL_RESERVED		= LECP_FLAG_CB_IS_VALUE | 10,
+	LECPCB_VAL_STR_START		= 11, /* notice handle separately */
+	LECPCB_VAL_STR_CHUNK		= LECP_FLAG_CB_IS_VALUE | 12,
+	LECPCB_VAL_STR_END		= LECP_FLAG_CB_IS_VALUE | 13,
+
+	LECPCB_ARRAY_START		= 14,
+	LECPCB_ARRAY_END		= 15,
+
+	LECPCB_OBJECT_START		= 16,
+	LECPCB_OBJECT_END		= 17,
+
+	LECPCB_TAG_START		= 18,
+	LECPCB_TAG_END			= 19,
+
+	LECPCB_VAL_NUM_UINT		= LECP_FLAG_CB_IS_VALUE | 20,
+	LECPCB_VAL_UNDEFINED		= LECP_FLAG_CB_IS_VALUE | 21,
+	LECPCB_VAL_FLOAT16		= LECP_FLAG_CB_IS_VALUE | 22,
+	LECPCB_VAL_FLOAT32		= LECP_FLAG_CB_IS_VALUE | 23,
+	LECPCB_VAL_FLOAT64		= LECP_FLAG_CB_IS_VALUE | 24,
+
+	LECPCB_VAL_SIMPLE		= LECP_FLAG_CB_IS_VALUE | 25,
+
+	LECPCB_VAL_BLOB_START		= 26, /* notice handle separately */
+	LECPCB_VAL_BLOB_CHUNK		= LECP_FLAG_CB_IS_VALUE | 27,
+	LECPCB_VAL_BLOB_END		= LECP_FLAG_CB_IS_VALUE | 28,
+
+	LECPCB_ARRAY_ITEM_START		= 29,
+	LECPCB_ARRAY_ITEM_END		= 30,
+
+	LECPCB_LITERAL_CBOR		= 31,
+};
+
+enum lecp_reasons {
+	LECP_CONTINUE			= -1,
+	LECP_REJECT_BAD_CODING		= -2,
+	LECP_REJECT_UNKNOWN		= -3,
+	LECP_REJECT_CALLBACK		= -4,
+	LECP_STACK_OVERFLOW		= -5,
+};
+
+
+struct lecp_item {
+	union {
+		uint64_t	u64;
+		int64_t		i64;
+
+		uint64_t	u32;
+
+		uint16_t	hf;
+#if defined(LWS_WITH_CBOR_FLOAT)
+		float		f;
+		double		d;
+#else
+		uint32_t	f;
+		uint64_t	d;
+#endif
+	} u;
+	uint8_t			opcode;
+};
+
+struct lecp_ctx;
+typedef signed char (*lecp_callback)(struct lecp_ctx *ctx, char reason);
+
+struct _lecp_stack {
+	char			s; /* lejp_state stack*/
+	uint8_t			p; /* path length */
+	char			i; /* index array length */
+	char			indet; /* indeterminite */
+	char			intermediate; /* in middle of string */
+
+	char			pop_iss;
+	uint64_t		tag;
+	uint64_t		collect_rem;
+	uint32_t		ordinal;
+	uint8_t			opcode;
+	uint8_t			send_new_array_item;
+	uint8_t			barrier;
+};
+
+struct _lecp_parsing_stack {
+	void			*user;	/* private to the stack level */
+	lecp_callback		cb;
+	const char * const	*paths;
+	uint8_t			count_paths;
+	uint8_t			ppos;
+	uint8_t			path_match;
+};
+
+struct lecp_ctx {
+
+	/* sorted by type for most compact alignment
+	 *
+	 * pointers
+	 */
+	void *user;
+	uint8_t			*collect_tgt;
+
+	/* arrays */
+
+	struct _lecp_parsing_stack pst[LECP_MAX_PARSING_STACK_DEPTH];
+	struct _lecp_stack	st[LECP_MAX_DEPTH];
+	uint16_t		i[LECP_MAX_INDEX_DEPTH]; /* index array */
+	uint16_t		wild[LECP_MAX_INDEX_DEPTH]; /* index array */
+	char			path[LECP_MAX_PATH];
+	uint8_t			cbor[64]; /* literal cbor capture */
+
+	struct lecp_item	item;
+
+
+	/* size_t */
+
+	size_t			path_stride; /* 0 means default ptr size, else
+					      * stride...  allows paths to be
+					      * provided composed inside a
+					      * larger user struct instead of a
+					      * duplicated array */
+	size_t			used_in;     /* bytes of input consumed */
+
+	/* short */
+
+	uint16_t 		uni;
+
+	/* char */
+
+	uint8_t			npos;
+	uint8_t			dcount;
+	uint8_t			f;
+	uint8_t			sp; /* stack head */
+	uint8_t			ipos; /* index stack depth */
+	uint8_t			count_paths;
+	uint8_t			path_match;
+	uint8_t			path_match_len;
+	uint8_t			wildcount;
+	uint8_t			pst_sp; /* parsing stack head */
+	uint8_t			outer_array;
+	uint8_t			cbor_pos;
+	uint8_t			literal_cbor_report;
+	char			present; /* temp for cb reason to use */
+
+	uint8_t			be; /* big endian */
+
+	/* at end so we can memset the rest of it */
+
+	char buf[LECP_STRING_CHUNK + 1];
+};
+
+enum lws_lec_pctx_ret {
+	LWS_LECPCTX_RET_FINISHED		= 0,
+	LWS_LECPCTX_RET_AGAIN, /* call again to continue writing buffer */
+	LWS_LECPCTX_RET_FAIL /* something broken, eg, format string */
+};
+
+enum cbp_state {
+	CBPS_IDLE,
+	CBPS_PC1,
+	CBPS_PC2,
+	CBPS_PC3,
+
+	CBPS_STRING_BODY,
+
+	CBPS_NUM_LIT,
+
+	CBPS_STRING_LIT,
+
+	CBPS_CONTYPE,
+};
+
+typedef struct lws_lec_pctx {
+	uint8_t			stack[16];
+	uint8_t			vaa[16];
+	uint8_t			indet[16];
+	uint8_t			scratch[24];
+	uint8_t			*start;	   /* the beginning of the out buf */
+	uint8_t			*buf;	   /* cur pos in output buf */
+	uint8_t			*end;	   /* the end of the output buf */
+
+	const uint8_t		*ongoing_src;
+	uint64_t		ongoing_len;
+	uint64_t		ongoing_done;
+
+	struct lecp_item	item;
+
+	size_t			used;	   /* number of bytes valid from start */
+
+	int			opaque[4]; /* ignored by lws, caller may use */
+
+	enum cbp_state		state;
+	unsigned int		fmt_pos;
+	uint8_t			sp;
+	uint8_t			scratch_len;
+	uint8_t			escflag;
+	uint8_t			_long;
+	uint8_t			vaa_pos;
+	uint8_t			dotstar;
+} lws_lec_pctx_t;
+
+LWS_VISIBLE LWS_EXTERN void
+lws_lec_int(lws_lec_pctx_t *ctx, uint8_t opcode, uint8_t indet, uint64_t num);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_lec_scratch(lws_lec_pctx_t *ctx);
+
+/*
+ * lws_lec_init() - prepare a cbor writing context
+ *
+ * \param ctx: the cbor writing context to prepare
+ * \param buf: the output buffer start
+ * \param len: the amount of the output buffer we can use
+ *
+ * Prepares a cbor writing context so that les_lec_printf can be used to
+ * write into it.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_lec_init(lws_lec_pctx_t *ctx, uint8_t *buf, size_t len);
+
+/*
+ * lws_lec_setbuf() - update the output buffer for an initialized cbor writing ctx
+ *
+ * \param ctx: the cbor writing context to prepare
+ * \param buf: the output buffer start
+ * \param len: the amount of the output buffer we can use
+ *
+ * Leaves the cbor writing context state as it is, but resets the output buffer
+ * it writes into as given in \p buf and \p len
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_lec_setbuf(lws_lec_pctx_t *ctx, uint8_t *buf, size_t len);
+
+/*
+ * lws_lec_vsprintf() - write into a cbor writing context
+ *
+ * \param ctx: the cbor writing context to prepare
+ * \param format: a printf style argument map
+ * \param args: the va args
+ *
+ * CBOR-aware vsprintf which pauses output when it fills the output buffer.  You
+ * can call it again with the same args and same lws_lex_pctx to resume filling
+ *
+ * Returns either LWS_LECPCTX_RET_FINISHED if we have nothing left over that we
+ * want to put in the buffer, or LWS_LECPCTX_RET_AGAIN if the function should
+ * be called again with the same arguments (perhaps into a different output
+ * buffer) to continue emitting output from where it left off.
+ *
+ * If LWS_LECPCTX_RET_AGAIN is returned, lws_lec_setbuf() must be used on the
+ * context to reset or change the output buffer before calling again.
+ *
+ * The number of bytes placed in the output buffer is available in ctx->used.
+ *
+ * \p format is a printf-type format string that is specialized for CBOR
+ * generation.  It understands the following specifiers
+ *
+ * |`123`||unsigned literal number|
+ * |`-123`||signed literal number|
+ * |`%u`|`unsigned int`|number|
+ * |`%lu`|`unsigned long int`|number|
+ * |`%llu`|`unsigned long long int`|number|
+ * |`%d`|`signed int`|number|
+ * |`%ld`|`signed long int`|number|
+ * |`%lld`|`signed long long int`|number|
+ * |`%f`|`double`|floating point number|
+ * |`123(...)`||literal tag and scope|
+ * |`%t(...)`|`unsigned int`|tag and scope|
+ * |`%lt(...)`|`unsigned long int`|tag and scope|
+ * |`%llt(...)`|`unsigned long long int`|tag and scope|
+ * |`[...]`||Array (fixed len if `]` in same format string)|
+ * |`{...}`||Map (fixed len if `}` in same format string)|
+ * |`<t...>`||Container for indeterminite text string frags|
+ * |`<b...>`||Container for indeterminite binary string frags|
+ * |`'string'`||Literal text of known length|
+ * |`%s`|`const char *`|NUL-terminated string|
+ * |`%.*s`|`int`, `const char *`|length-specified string|
+ * |`%.*b`|`int`, `const uint8_t *`|length-specified binary|
+ * |`:`||separator between Map items (a:b)|
+ * |`,`||separator between Map pairs or array items|
+ *
+ * See READMEs/README.cbor-lecp.md for more details.
+ */
+LWS_VISIBLE LWS_EXTERN enum lws_lec_pctx_ret
+lws_lec_vsprintf(lws_lec_pctx_t *ctx, const char *format, va_list args);
+
+/*
+ * lws_lec_printf() - write into a cbor writing context
+ *
+ * \param ctx: the cbor writing context to prepare
+ * \param format: a printf style argument map
+ * \param ...: format args
+ *
+ * See lws_lec_vsprintf() for format details.  This is the most common way
+ * to format the CBOR output.
+ *
+ * See READMEs/README.cbor-lecp.md for more details.
+ */
+LWS_VISIBLE LWS_EXTERN enum lws_lec_pctx_ret
+lws_lec_printf(lws_lec_pctx_t *ctx, const char *format, ...);
+
+/**
+ * lecp_construct() - Construct an LECP parser context
+ *
+ * \param ctx: the parser context object to be initialized
+ * \param cb: the user callback to receive the parsing events
+ * \param user: an opaque user pointer available at \p cb
+ * \param paths: an optional array of parsing paths
+ * \param paths_count: how many paths in \p paths
+ *
+ * Prepares an LECP parser context for parsing.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lecp_construct(struct lecp_ctx *ctx, lecp_callback cb, void *user,
+	       const char * const *paths, unsigned char paths_count);
+
+/**
+ * lecp_destruct() - Destroys an LECP parser context
+ *
+ * \param ctx: the parser context object to be destroyed
+ */
+LWS_VISIBLE LWS_EXTERN void
+lecp_destruct(struct lecp_ctx *ctx);
+
+/**
+ * lecp_parse() - parses a chunk of input CBOR
+ *
+ * \p ctx: the parsing context
+ * \p cbor: the start of the chunk of CBOR
+ * \p len: the number of bytes of CBOR available at \p cbor
+ *
+ * Returns LECP_CONTINUE if more input needed, one of enum lecp_reasons for a
+ * fatal error, else 0 for successful parsing completion.
+ *
+ * On success or _CONTINUE, ctx->used_in is set to the number of input bytes
+ * consumed.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lecp_parse(struct lecp_ctx *ctx, const uint8_t *cbor, size_t len);
+
+LWS_VISIBLE LWS_EXTERN void
+lecp_change_callback(struct lecp_ctx *ctx, lecp_callback cb);
+
+LWS_VISIBLE LWS_EXTERN const char *
+lecp_error_to_string(int e);
+
+/**
+ * lecp_parse_report_raw() - turn cbor raw reporting on and off
+ *
+ * \param ctx: the lecp context
+ * \param on: 0 to disable (defaults disabled), 1 to enable
+ *
+ * For cose_sign, it needs access to raw cbor subtrees for the hash input.
+ * This api causes LECPCB_LITERAL_CBOR parse callbacks when there are
+ * ctx->cbor_pos bytes of raw cbor available in ctx->cbor[]. the callbacks
+ * occur when the ctx->cbor[] buffer fills or if it holds anything when this
+ * spi is used to stop the reports.
+ *
+ * The same CBOR that is being captured continues to be passed for parsing.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lecp_parse_report_raw(struct lecp_ctx *ctx, int on);
+
+/**
+ * lecp_parse_map_is_key() - return nonzero if we're in a map and this is a key
+ *
+ * \param ctx: the lwcp context
+ *
+ * Checks if the current value is a key in a map, ie, that you are on a "key" in
+ * a list of "{key: value}" pairs.  Zero means you're either not in a map or not
+ * on the key part, and nonzero means you are in a map and on a key part.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lecp_parse_map_is_key(struct lecp_ctx *ctx);
+
+LWS_VISIBLE LWS_EXTERN int
+lecp_parse_subtree(struct lecp_ctx *ctx, const uint8_t *in, size_t len);
+
+/*
+ * Helpers for half-float
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_singles2halfp(uint16_t *hp, uint32_t x);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_halfp2singles(uint32_t *xp, uint16_t h);
+
+//@}

include/libwebsockets/lws-led.h

@@ -0,0 +1,146 @@
+/*
+ * Generic LED controller ops
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is like an abstract class for leds, a real implementation provides
+ * functions for the ops that use the underlying, eg, OS gpio arrangements.
+ */
+
+/* only b15 significant for GPIO */
+typedef uint16_t lws_led_intensity_t;
+typedef uint16_t lws_led_seq_phase_t;
+
+/* the normalized max intensity */
+#define LWS_LED_MAX_INTENSITY			(0xffff)
+
+/* the normalized 360 degree phase count for intensity functions */
+#define LWS_LED_FUNC_PHASE			65536
+/* used when the sequence doesn't stop by itself and goes around forever */
+#define LWS_SEQ_LEDPHASE_TOTAL_ENDLESS		(-1)
+
+#define LWS_LED_SEQUENCER_UPDATE_INTERVAL_MS	33
+
+struct lws_led_state; /* opaque */
+struct lws_pwm_ops; /* forward ref */
+
+typedef lws_led_intensity_t (*lws_led_lookup_t)(lws_led_seq_phase_t ph);
+
+typedef struct lws_led_sequence_def_t {
+	lws_led_lookup_t		func;
+	lws_led_seq_phase_t		ledphase_offset;
+	int				ledphase_total; /* 65536= one cycle */
+	uint16_t			ms;
+	uint8_t				flags;
+} lws_led_sequence_def_t;
+
+enum {
+	LLSI_CURR,
+	LLSI_NEXT,
+	LLSI_TRANS
+};
+
+typedef struct lws_led_state_ch
+{
+	const lws_led_sequence_def_t		*seq; /* NULL = inactive */
+	lws_led_seq_phase_t			ph;
+	lws_led_seq_phase_t			step;
+	int					phase_budget;
+	lws_led_intensity_t			last;
+	/**< at the end of the sequence we decouple the sequencer, but leave
+	 * the last computed sample behind for further transitions to base off
+	 */
+} lws_led_state_ch_t;
+
+typedef struct lws_led_state_chs
+{
+	lws_led_state_ch_t			seqs[3];
+} lws_led_state_chs_t;
+
+/* this should always be first in the subclassed implementation types */
+
+typedef struct lws_led_ops {
+	void (*intensity)(const struct lws_led_ops *lo, const char *name,
+			  lws_led_intensity_t inten);
+	/**< for BOOL led control like GPIO, only inten b15 is significant */
+	struct lws_led_state * (*create)(const struct lws_led_ops *led_ops);
+	void (*destroy)(struct lws_led_state *);
+} lws_led_ops_t;
+
+typedef struct lws_led_gpio_map {
+	const char			*name;
+	_lws_plat_gpio_t		gpio;
+	lws_led_lookup_t		intensity_correction;
+	/**< May be NULL.  If GPIO-based LED, ignored.  If pwm_ops provided,
+	 * NULL means use default CIE 100% correction function.  If non-NULL,
+	 * use the pointed-to correction function.  This is useful to provide
+	 * LED-specific intensity correction / scaling so different types of
+	 * LED can "look the same". */
+	const struct lws_pwm_ops	*pwm_ops;
+	/**< if NULL, gpio controls the led directly.  If set to a pwm_ops,
+	 * the led control is outsourced to the pwm controller. */
+	uint8_t				active_level;
+} lws_led_gpio_map_t;
+
+typedef struct lws_led_gpio_controller {
+	const lws_led_ops_t		led_ops;
+
+	const lws_gpio_ops_t		*gpio_ops;
+	const lws_led_gpio_map_t	*led_map;
+	uint8_t				count_leds;
+} lws_led_gpio_controller_t;
+
+/* ops */
+
+LWS_VISIBLE LWS_EXTERN struct lws_led_state *
+lws_led_gpio_create(const lws_led_ops_t *led_ops);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_led_gpio_destroy(struct lws_led_state *lcs);
+
+/**
+ * lws_led_gpio_intensity() - set the static intensity of an led
+ *
+ * \param lo: the base class of the led controller
+ * \param index: which led in the controller set
+ * \param inten: 16-bit unsigned intensity
+ *
+ * For LEDs controlled by a BOOL like GPIO, only inten b15 is significant.
+ * For PWM type LED control, as many bits as the hardware can support from b15
+ * down are significant.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_led_gpio_intensity(const struct lws_led_ops *lo, const char *name,
+		       lws_led_intensity_t inten);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_led_transition(struct lws_led_state *lcs, const char *name,
+		   const lws_led_sequence_def_t *next,
+		   const lws_led_sequence_def_t *trans);
+
+
+#define lws_led_gpio_ops \
+	{ \
+		.create		= lws_led_gpio_create, \
+		.destroy	= lws_led_gpio_destroy, \
+		.intensity	= lws_led_gpio_intensity, \
+	}
+

include/libwebsockets/lws-lejp.h

@@ -0,0 +1,301 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup lejp JSON parser
+ * ##JSON parsing related functions
+ * \ingroup lwsapi
+ *
+ * LEJP is an extremely lightweight JSON stream parser included in lws.
+ */
+//@{
+struct lejp_ctx;
+
+#if !defined(LWS_ARRAY_SIZE)
+#define LWS_ARRAY_SIZE(_x) (sizeof(_x) / sizeof(_x[0]))
+#endif
+#define LEJP_FLAG_WS_KEEP 64
+#define LEJP_FLAG_WS_COMMENTLINE 32
+
+enum lejp_states {
+	LEJP_IDLE = 0,
+	LEJP_MEMBERS = 1,
+	LEJP_M_P = 2,
+	LEJP_MP_STRING = LEJP_FLAG_WS_KEEP | 3,
+	LEJP_MP_STRING_ESC = LEJP_FLAG_WS_KEEP | 4,
+	LEJP_MP_STRING_ESC_U1 = LEJP_FLAG_WS_KEEP | 5,
+	LEJP_MP_STRING_ESC_U2 = LEJP_FLAG_WS_KEEP | 6,
+	LEJP_MP_STRING_ESC_U3 = LEJP_FLAG_WS_KEEP | 7,
+	LEJP_MP_STRING_ESC_U4 = LEJP_FLAG_WS_KEEP | 8,
+	LEJP_MP_DELIM = 9,
+	LEJP_MP_VALUE = 10,
+	LEJP_MP_VALUE_NUM_INT = LEJP_FLAG_WS_KEEP | 11,
+	LEJP_MP_VALUE_NUM_EXP = LEJP_FLAG_WS_KEEP | 12,
+	LEJP_MP_VALUE_TOK = LEJP_FLAG_WS_KEEP | 13,
+	LEJP_MP_COMMA_OR_END = 14,
+	LEJP_MP_ARRAY_END = 15,
+};
+
+enum lejp_reasons {
+	LEJP_CONTINUE = -1,
+	LEJP_REJECT_IDLE_NO_BRACE = -2,
+	LEJP_REJECT_MEMBERS_NO_CLOSE = -3,
+	LEJP_REJECT_MP_NO_OPEN_QUOTE = -4,
+	LEJP_REJECT_MP_STRING_UNDERRUN = -5,
+	LEJP_REJECT_MP_ILLEGAL_CTRL = -6,
+	LEJP_REJECT_MP_STRING_ESC_ILLEGAL_ESC = -7,
+	LEJP_REJECT_ILLEGAL_HEX = -8,
+	LEJP_REJECT_MP_DELIM_MISSING_COLON = -9,
+	LEJP_REJECT_MP_DELIM_BAD_VALUE_START = -10,
+	LEJP_REJECT_MP_VAL_NUM_INT_NO_FRAC = -11,
+	LEJP_REJECT_MP_VAL_NUM_FORMAT = -12,
+	LEJP_REJECT_MP_VAL_NUM_EXP_BAD_EXP = -13,
+	LEJP_REJECT_MP_VAL_TOK_UNKNOWN = -14,
+	LEJP_REJECT_MP_C_OR_E_UNDERF = -15,
+	LEJP_REJECT_MP_C_OR_E_NOTARRAY = -16,
+	LEJP_REJECT_MP_ARRAY_END_MISSING = -17,
+	LEJP_REJECT_STACK_OVERFLOW = -18,
+	LEJP_REJECT_MP_DELIM_ISTACK = -19,
+	LEJP_REJECT_NUM_TOO_LONG = -20,
+	LEJP_REJECT_MP_C_OR_E_NEITHER = -21,
+	LEJP_REJECT_UNKNOWN = -22,
+	LEJP_REJECT_CALLBACK = -23
+};
+
+#define LEJP_FLAG_CB_IS_VALUE 64
+
+enum lejp_callbacks {
+	LEJPCB_CONSTRUCTED	= 0,
+	LEJPCB_DESTRUCTED	= 1,
+
+	LEJPCB_START		= 2,
+	LEJPCB_COMPLETE		= 3,
+	LEJPCB_FAILED		= 4,
+
+	LEJPCB_PAIR_NAME	= 5,
+
+	LEJPCB_VAL_TRUE		= LEJP_FLAG_CB_IS_VALUE | 6,
+	LEJPCB_VAL_FALSE	= LEJP_FLAG_CB_IS_VALUE | 7,
+	LEJPCB_VAL_NULL		= LEJP_FLAG_CB_IS_VALUE | 8,
+	LEJPCB_VAL_NUM_INT	= LEJP_FLAG_CB_IS_VALUE | 9,
+	LEJPCB_VAL_NUM_FLOAT	= LEJP_FLAG_CB_IS_VALUE | 10,
+	LEJPCB_VAL_STR_START	= 11, /* notice handle separately */
+	LEJPCB_VAL_STR_CHUNK	= LEJP_FLAG_CB_IS_VALUE | 12,
+	LEJPCB_VAL_STR_END	= LEJP_FLAG_CB_IS_VALUE | 13,
+
+	LEJPCB_ARRAY_START	= 14,
+	LEJPCB_ARRAY_END	= 15,
+
+	LEJPCB_OBJECT_START	= 16,
+	LEJPCB_OBJECT_END	= 17,
+};
+
+/**
+ * _lejp_callback() - User parser actions
+ * \param ctx:	LEJP context
+ * \param reason:	Callback reason
+ *
+ *	Your user callback is associated with the context at construction time,
+ *	and receives calls as the parsing progresses.
+ *
+ *	All of the callbacks may be ignored and just return 0.
+ *
+ *	The reasons it might get called, found in @reason, are:
+ *
+ *  LEJPCB_CONSTRUCTED:  The context was just constructed... you might want to
+ *		perform one-time allocation for the life of the context.
+ *
+ *  LEJPCB_DESTRUCTED:	The context is being destructed... if you made any
+ *		allocations at construction-time, you can free them now
+ *
+ *  LEJPCB_START:	Parsing is beginning at the first byte of input
+ *
+ *  LEJPCB_COMPLETE:	Parsing has completed successfully.  You'll get a 0 or
+ *			positive return code from lejp_parse indicating the
+ *			amount of unused bytes left in the input buffer
+ *
+ *  LEJPCB_FAILED:	Parsing failed.  You'll get a negative error code
+ *  			returned from lejp_parse
+ *
+ *  LEJPCB_PAIR_NAME:	When a "name":"value" pair has had the name parsed,
+ *			this callback occurs.  You can find the new name at
+ *			the end of ctx->path[]
+ *
+ *  LEJPCB_VAL_TRUE:	The "true" value appeared
+ *
+ *  LEJPCB_VAL_FALSE:	The "false" value appeared
+ *
+ *  LEJPCB_VAL_NULL:	The "null" value appeared
+ *
+ *  LEJPCB_VAL_NUM_INT:	A string representing an integer is in ctx->buf
+ *
+ *  LEJPCB_VAL_NUM_FLOAT: A string representing a float is in ctx->buf
+ *
+ *  LEJPCB_VAL_STR_START: We are starting to parse a string, no data yet
+ *
+ *  LEJPCB_VAL_STR_CHUNK: We filled the string buffer in the ctx, but it's not
+ *			  the end of the string.  We produce this to spill the
+ *			  intermediate buffer to the user code, so we can handle
+ *			  huge JSON strings using only the small buffer in the
+ *			  ctx.  If the whole JSON string fits in the ctx buffer,
+ *			  you won't get these callbacks.
+ *
+ *  LEJPCB_VAL_STR_END:	String parsing has completed, the last chunk of the
+ *			string is in ctx->buf.
+ *
+ *  LEJPCB_ARRAY_START:	An array started
+ *
+ *  LEJPCB_ARRAY_END:	An array ended
+ *
+ *  LEJPCB_OBJECT_START: An object started
+ *
+ *  LEJPCB_OBJECT_END:	An object ended
+ */
+LWS_EXTERN signed char _lejp_callback(struct lejp_ctx *ctx, char reason);
+
+typedef signed char (*lejp_callback)(struct lejp_ctx *ctx, char reason);
+
+#ifndef LEJP_MAX_PARSING_STACK_DEPTH
+#define LEJP_MAX_PARSING_STACK_DEPTH 5
+#endif
+#ifndef LEJP_MAX_DEPTH
+#define LEJP_MAX_DEPTH 12
+#endif
+#ifndef LEJP_MAX_INDEX_DEPTH
+#define LEJP_MAX_INDEX_DEPTH 8
+#endif
+#ifndef LEJP_MAX_PATH
+#define LEJP_MAX_PATH 128
+#endif
+#ifndef LEJP_STRING_CHUNK
+/* must be >= 30 to assemble floats */
+#define LEJP_STRING_CHUNK 254
+#endif
+
+enum num_flags {
+	LEJP_SEEN_MINUS		= (1 << 0),
+	LEJP_SEEN_POINT		= (1 << 1),
+	LEJP_SEEN_POST_POINT	= (1 << 2),
+	LEJP_SEEN_EXP		= (1 << 3)
+};
+
+struct _lejp_stack {
+	char			s; /* lejp_state stack*/
+	char			p;	/* path length */
+	char			i; /* index array length */
+	char			b; /* user bitfield */
+};
+
+struct _lejp_parsing_stack {
+	void			*user;	/* private to the stack level */
+	signed char 		(*callback)(struct lejp_ctx *ctx, char reason);
+	const char * const	*paths;
+	uint8_t			count_paths;
+	uint8_t			ppos;
+	uint8_t			path_match;
+};
+
+struct lejp_ctx {
+
+	/* sorted by type for most compact alignment
+	 *
+	 * pointers
+	 */
+	void *user;
+
+	/* arrays */
+
+	struct _lejp_parsing_stack pst[LEJP_MAX_PARSING_STACK_DEPTH];
+	struct _lejp_stack st[LEJP_MAX_DEPTH];
+	uint16_t i[LEJP_MAX_INDEX_DEPTH]; /* index array */
+	uint16_t wild[LEJP_MAX_INDEX_DEPTH]; /* index array */
+	char path[LEJP_MAX_PATH];
+	char buf[LEJP_STRING_CHUNK + 1];
+
+	/* size_t */
+
+	size_t path_stride; /* 0 means default ptr size, else stride */
+
+	/* int */
+
+	uint32_t line;
+
+	/* short */
+
+	uint16_t uni;
+
+	/* char */
+
+	uint8_t npos;
+	uint8_t dcount;
+	uint8_t f;
+	uint8_t sp; /* stack head */
+	uint8_t ipos; /* index stack depth */
+	uint8_t count_paths;
+	uint8_t path_match;
+	uint8_t path_match_len;
+	uint8_t wildcount;
+	uint8_t pst_sp; /* parsing stack head */
+	uint8_t outer_array;
+};
+
+LWS_VISIBLE LWS_EXTERN void
+lejp_construct(struct lejp_ctx *ctx,
+	       signed char (*callback)(struct lejp_ctx *ctx, char reason),
+	       void *user, const char * const *paths, unsigned char paths_count);
+
+LWS_VISIBLE LWS_EXTERN void
+lejp_destruct(struct lejp_ctx *ctx);
+
+LWS_VISIBLE LWS_EXTERN int
+lejp_parse(struct lejp_ctx *ctx, const unsigned char *json, int len);
+
+LWS_VISIBLE LWS_EXTERN void
+lejp_change_callback(struct lejp_ctx *ctx,
+		     signed char (*callback)(struct lejp_ctx *ctx, char reason));
+
+/*
+ * push the current paths / paths_count and lejp_cb to a stack in the ctx, and
+ * start using the new ones
+ */
+LWS_VISIBLE LWS_EXTERN int
+lejp_parser_push(struct lejp_ctx *ctx, void *user, const char * const *paths,
+		 unsigned char paths_count, lejp_callback lejp_cb);
+
+/*
+ * pop the previously used paths / paths_count and lejp_cb, and continue
+ * parsing using those as before
+ */
+LWS_VISIBLE LWS_EXTERN int
+lejp_parser_pop(struct lejp_ctx *ctx);
+
+/* exported for use when reevaluating a path for use with a subcontext */
+LWS_VISIBLE LWS_EXTERN void
+lejp_check_path_match(struct lejp_ctx *ctx);
+
+LWS_VISIBLE LWS_EXTERN int
+lejp_get_wildcard(struct lejp_ctx *ctx, int wildcard, char *dest, int len);
+
+LWS_VISIBLE LWS_EXTERN const char *
+lejp_error_to_string(int e);
+//@}

include/libwebsockets/lws-logs.h

@@ -0,0 +1,794 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup log Logging
+ *
+ * ##Logging
+ *
+ * Lws provides flexible and filterable logging facilities, which can be
+ * used inside lws and in user code.
+ *
+ * Log categories may be individually filtered bitwise, and directed to built-in
+ * sinks for syslog-compatible logging, or a user-defined function.
+ *
+ * Traditional logs use a single, processwide logging context.  New style log
+ * apis (lws_xxx_cx()) can pass the logging context to use in.
+ */
+///@{
+
+#define LLL_ERR			(1 << 0)
+#define	LLL_WARN		(1 << 1)
+#define	LLL_NOTICE		(1 << 2)
+#define	LLL_INFO		(1 << 3)
+#define	LLL_DEBUG		(1 << 4)
+#define	LLL_PARSER		(1 << 5)
+#define	LLL_HEADER		(1 << 6)
+#define	LLL_EXT			(1 << 7)
+#define	LLL_CLIENT		(1 << 8)
+#define	LLL_LATENCY		(1 << 9)
+#define	LLL_USER		(1 << 10)
+#define	LLL_THREAD		(1 << 11)
+
+#define	LLL_COUNT		(12) /* set to count of valid flags */
+
+#define	LLLF_SECRECY_PII	(1 << 16)
+	/**< contains Personally Identifiable Information */
+#define LLLF_SECRECY_BEARER	(1 << 17)
+	/**< possession of this data allows impersonation */
+
+#define	LLLF_LOG_TIMESTAMP	(1 << 18)
+	/**< set to prepend logs with timestamp */
+
+#define	LLLF_LOG_CONTEXT_AWARE	(1 << 30)
+/**< set if the context uses an emit function that takes the logctx, auto-
+ * applied when setting emit using lws_set_log_level_cx() api */
+
+struct lws_log_cx;
+
+typedef void (*lws_log_emit_t)(int level, const char *line);
+typedef void (*lws_log_emit_cx_t)(struct lws_log_cx *cx, int level,
+				  const char *line, size_t len);
+typedef void (*lws_log_prepend_cx_t)(struct lws_log_cx *cx, void *obj,
+				     char **p, char *e);
+typedef void (*lws_log_use_cx_t)(struct lws_log_cx *cx, int _new);
+
+/*
+ * This is the logging context
+ */
+
+typedef struct lws_log_cx {
+	union {
+		lws_log_emit_t		emit; /* legacy emit function */
+		lws_log_emit_cx_t	emit_cx; /* LLLF_LOG_CONTEXT_AWARE */
+	} u;
+
+#if LWS_MAX_SMP > 1
+	pthread_mutex_t			refcount_lock;
+#endif
+
+	lws_log_use_cx_t		refcount_cb;
+	/**< NULL, or a function called after each change to .refcount below,
+	 * this enables implementing side-effects like opening and closing
+	 * log files when the first and last object binds / unbinds */
+	lws_log_prepend_cx_t		prepend;
+	/**< NULL, or a cb to optionally prepend a string to logs we are a
+	 * parent of */
+	struct lws_log_cx		*parent;
+	/**< NULL, or points to log ctx we are a child of */
+	void				*opaque;
+	/**< ignored by lws, used to pass config to emit_cx, eg, filepath */
+	void				*stg;
+	/**< ignored by lws, may be used a storage by refcount_cb / emit_cx */
+	uint32_t			lll_flags;
+	/**< mask of log levels we want to emit in this context */
+	int32_t				refcount;
+	/**< refcount of objects bound to this log context */
+#if LWS_MAX_SMP > 1
+	char				inited;
+#endif
+} lws_log_cx_t;
+
+/**
+ * lwsl_timestamp: generate logging timestamp string
+ *
+ * \param level:	logging level
+ * \param p:		char * buffer to take timestamp
+ * \param len:	length of p
+ *
+ * returns length written in p
+ */
+LWS_VISIBLE LWS_EXTERN int
+lwsl_timestamp(int level, char *p, size_t len);
+
+#if defined(LWS_PLAT_OPTEE) && !defined(LWS_WITH_NETWORK)
+#define _lws_log(aaa, ...) SMSG(__VA_ARGS__)
+#else
+LWS_VISIBLE LWS_EXTERN void
+_lws_log(int filter, const char *format, ...) LWS_FORMAT(2);
+LWS_VISIBLE LWS_EXTERN void
+_lws_logv(int filter, const char *format, va_list vl);
+#endif
+
+struct lws_vhost;
+struct lws;
+
+LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
+lwsl_context_get_cx(struct lws_context *cx);
+LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
+lwsl_vhost_get_cx(struct lws_vhost *vh);
+LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
+lwsl_wsi_get_cx(struct lws *wsi);
+#if defined(LWS_WITH_SECURE_STREAMS)
+struct lws_ss_handle;
+struct lws_sspc_handle;
+LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
+lwsl_ss_get_cx(struct lws_ss_handle *ss);
+LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
+lwsl_sspc_get_cx(struct lws_sspc_handle *ss);
+#endif
+
+LWS_VISIBLE LWS_EXTERN void
+lws_log_emit_cx_file(struct lws_log_cx *cx, int level, const char *line,
+			size_t len);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_log_use_cx_file(struct lws_log_cx *cx, int _new);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_log_prepend_context(struct lws_log_cx *cx, void *obj, char **p, char *e);
+LWS_VISIBLE LWS_EXTERN void
+lws_log_prepend_vhost(struct lws_log_cx *cx, void *obj, char **p, char *e);
+LWS_VISIBLE LWS_EXTERN void
+lws_log_prepend_wsi(struct lws_log_cx *cx, void *obj, char **p, char *e);
+#if defined(LWS_WITH_SECURE_STREAMS)
+LWS_VISIBLE LWS_EXTERN void
+lws_log_prepend_ss(struct lws_log_cx *cx, void *obj, char **p, char *e);
+LWS_VISIBLE LWS_EXTERN void
+lws_log_prepend_sspc(struct lws_log_cx *cx, void *obj, char **p, char *e);
+#endif
+
+LWS_VISIBLE LWS_EXTERN void
+_lws_log_cx(lws_log_cx_t *cx, lws_log_prepend_cx_t prep, void *obj,
+	    int filter, const char *_fun, const char *format, ...) LWS_FORMAT(6);
+
+#define lwsl_cx(_c, _fil, ...) \
+		 _lws_log_cx(lwsl_context_get_cx(_c), lws_log_prepend_context, \
+					_c, _fil, __func__, __VA_ARGS__)
+#define lwsl_vhost(_v, _fil, ...) \
+		 _lws_log_cx(lwsl_vhost_get_cx(_v), lws_log_prepend_vhost, _v, \
+					_fil, __func__, __VA_ARGS__)
+#define lwsl_wsi(_w, _fil, ...) \
+		 _lws_log_cx(lwsl_wsi_get_cx(_w), lws_log_prepend_wsi, _w, \
+					_fil, __func__, __VA_ARGS__)
+#define lwsl_ss(_h, _fil, ...) \
+		 _lws_log_cx(lwsl_ss_get_cx(_h), lws_log_prepend_ss, _h, \
+					_fil, __func__, __VA_ARGS__)
+
+#define lwsl_hexdump_context(_c, _fil, _buf, _len) \
+		lwsl_hexdump_level_cx(lwsl_context_get_cx(_c), \
+				      lws_log_prepend_context, \
+				      _c, _fil, _buf, _len)
+#define lwsl_hexdump_vhost(_v, _fil, _buf, _len) \
+		lwsl_hexdump_level_cx(lwsl_vhost_get_cx(_v), \
+				      lws_log_prepend_vhost, \
+				      _v, _fil, _buf, _len)
+#define lwsl_hexdump_wsi(_w, _fil, _buf, _len) \
+		lwsl_hexdump_level_cx(lwsl_wsi_get_cx(_w), \
+				      lws_log_prepend_wsi, \
+				      _w, _fil, _buf, _len)
+#define lwsl_hexdump_ss(_h, _fil, _buf, _len) \
+		lwsl_hexdump_level_cx(lwsl_ss_get_cx(_h), \
+				      lws_log_prepend_ss, \
+				      _h, _fil, _buf, _len)
+
+/*
+ * Figure out which logs to build in or not
+ */
+
+#if defined(_DEBUG)
+ /*
+  * In DEBUG build, select all logs unless NO_LOGS
+  */
+ #if defined(LWS_WITH_NO_LOGS)
+  #define _LWS_LINIT (LLL_ERR | LLL_USER)
+ #else
+   #define _LWS_LINIT ((1 << LLL_COUNT) - 1)
+ #endif
+#else /* not _DEBUG */
+#if defined(LWS_WITH_NO_LOGS)
+#define _LWS_LINIT (LLL_ERR | LLL_USER)
+#else
+ #define _LWS_LINIT (LLL_ERR | LLL_USER | LLL_WARN | LLL_NOTICE)
+#endif
+#endif /* _DEBUG */
+
+/*
+ * Create either empty overrides or the ones forced at build-time.
+ * These overrides have the final say... any bits set in
+ * LWS_LOGGING_BITFIELD_SET force the build of those logs, any bits
+ * set in LWS_LOGGING_BITFIELD_CLEAR disable the build of those logs.
+ *
+ * If not defined lws decides based on CMAKE_BUILD_TYPE=DEBUG or not
+ */
+
+#if defined(LWS_LOGGING_BITFIELD_SET)
+ #define _LWS_LBS (LWS_LOGGING_BITFIELD_SET)
+#else
+ #define _LWS_LBS 0
+#endif
+
+#if defined(LWS_LOGGING_BITFIELD_CLEAR)
+ #define _LWS_LBC (LWS_LOGGING_BITFIELD_CLEAR)
+#else
+ #define _LWS_LBC 0
+#endif
+
+/*
+ * Compute the final active logging bitfield for build
+ */
+#define _LWS_ENABLED_LOGS (((_LWS_LINIT) | (_LWS_LBS)) & ~(_LWS_LBC))
+
+/*
+ * Individually enable or disable log levels for build
+ * depending on what was computed
+ */
+
+/*
+ * Process scope logs
+ */
+
+#if (_LWS_ENABLED_LOGS & LLL_ERR)
+#define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
+#else
+#define lwsl_err(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_WARN)
+#define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
+#else
+#define lwsl_warn(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_NOTICE)
+#define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
+#else
+#define lwsl_notice(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_INFO)
+#define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
+#else
+#define lwsl_info(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_DEBUG)
+#define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
+#else
+#define lwsl_debug(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_PARSER)
+#define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
+#else
+#define lwsl_parser(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_HEADER)
+#define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)
+#else
+#define lwsl_header(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_EXT)
+#define lwsl_ext(...) _lws_log(LLL_EXT, __VA_ARGS__)
+#else
+#define lwsl_ext(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_CLIENT)
+#define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
+#else
+#define lwsl_client(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_LATENCY)
+#define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
+#else
+#define lwsl_latency(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_THREAD)
+#define lwsl_thread(...) _lws_log(LLL_THREAD, __VA_ARGS__)
+#else
+#define lwsl_thread(...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_USER)
+#define lwsl_user(...) _lws_log(LLL_USER, __VA_ARGS__)
+#else
+#define lwsl_user(...) do {} while(0)
+#endif
+
+#define lwsl_hexdump_err(...) lwsl_hexdump_level(LLL_ERR, __VA_ARGS__)
+#define lwsl_hexdump_warn(...) lwsl_hexdump_level(LLL_WARN, __VA_ARGS__)
+#define lwsl_hexdump_notice(...) lwsl_hexdump_level(LLL_NOTICE, __VA_ARGS__)
+#define lwsl_hexdump_info(...) lwsl_hexdump_level(LLL_INFO, __VA_ARGS__)
+#define lwsl_hexdump_debug(...) lwsl_hexdump_level(LLL_DEBUG, __VA_ARGS__)
+
+/*
+ * lws_context scope logs
+ */
+
+#if (_LWS_ENABLED_LOGS & LLL_ERR)
+#define lwsl_cx_err(_c, ...) lwsl_cx(_c, LLL_ERR, __VA_ARGS__)
+#else
+#define lwsl_cx_err(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_WARN)
+#define lwsl_cx_warn(_c, ...) lwsl_cx(_c, LLL_WARN, __VA_ARGS__)
+#else
+#define lwsl_cx_warn(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_NOTICE)
+#define lwsl_cx_notice(_c, ...) lwsl_cx(_c, LLL_NOTICE, __VA_ARGS__)
+#else
+#define lwsl_cx_notice(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_INFO)
+#define lwsl_cx_info(_c, ...) lwsl_cx(_c, LLL_INFO, __VA_ARGS__)
+#else
+#define lwsl_cx_info(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_DEBUG)
+#define lwsl_cx_debug(_c, ...) lwsl_cx(_c, LLL_DEBUG, __VA_ARGS__)
+#else
+#define lwsl_cx_debug(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_PARSER)
+#define lwsl_cx_parser(_c, ...) lwsl_cx(_c, LLL_PARSER, __VA_ARGS__)
+#else
+#define lwsl_cx_parser(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_HEADER)
+#define lwsl_cx_header(_c, ...) lwsl_cx(_c, LLL_HEADER, __VA_ARGS__)
+#else
+#define lwsl_cx_header(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_EXT)
+#define lwsl_cx_ext(_c, ...) lwsl_cx(_c, LLL_EXT, __VA_ARGS__)
+#else
+#define lwsl_cx_ext(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_CLIENT)
+#define lwsl_cx_client(_c, ...) lwsl_cx(_c, LLL_CLIENT, __VA_ARGS__)
+#else
+#define lwsl_cx_client(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_LATENCY)
+#define lwsl_cx_latency(_c, ...) lwsl_cx(_c, LLL_LATENCY, __VA_ARGS__)
+#else
+#define lwsl_cx_latency(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_THREAD)
+#define lwsl_cx_thread(_c, ...) lwsl_cx(_c, LLL_THREAD, __VA_ARGS__)
+#else
+#define lwsl_cx_thread(_c, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_USER)
+#define lwsl_cx_user(_c, ...) lwsl_cx(_c, LLL_USER, __VA_ARGS__)
+#else
+#define lwsl_cx_user(_c, ...) do {} while(0)
+#endif
+
+#define lwsl_hexdump_cx_err(_c, ...)    lwsl_hexdump_context(_c, LLL_ERR, __VA_ARGS__)
+#define lwsl_hexdump_cx_warn(_c, ...)   lwsl_hexdump_context(_c, LLL_WARN, __VA_ARGS__)
+#define lwsl_hexdump_cx_notice(_c, ...) lwsl_hexdump_context(_c, LLL_NOTICE, __VA_ARGS__)
+#define lwsl_hexdump_cx_info(_c, ...)   lwsl_hexdump_context(_c, LLL_INFO, __VA_ARGS__)
+#define lwsl_hexdump_cx_debug(_c, ...)  lwsl_hexdump_context(_c, LLL_DEBUG, __VA_ARGS__)
+
+/*
+ * lws_vhost
+ */
+
+#if (_LWS_ENABLED_LOGS & LLL_ERR)
+#define lwsl_vhost_err(_v, ...) lwsl_vhost(_v, LLL_ERR, __VA_ARGS__)
+#else
+#define lwsl_vhost_err(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_WARN)
+#define lwsl_vhost_warn(_v, ...) lwsl_vhost(_v, LLL_WARN, __VA_ARGS__)
+#else
+#define lwsl_vhost_warn(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_NOTICE)
+#define lwsl_vhost_notice(_v, ...) lwsl_vhost(_v, LLL_NOTICE, __VA_ARGS__)
+#else
+#define lwsl_vhost_notice(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_INFO)
+#define lwsl_vhost_info(_v, ...) lwsl_vhost(_v, LLL_INFO, __VA_ARGS__)
+#else
+#define lwsl_vhost_info(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_DEBUG)
+#define lwsl_vhost_debug(_v, ...) lwsl_vhost(_v, LLL_DEBUG, __VA_ARGS__)
+#else
+#define lwsl_vhost_debug(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_PARSER)
+#define lwsl_vhost_parser(_v, ...) lwsl_vhost(_v, LLL_PARSER, __VA_ARGS__)
+#else
+#define lwsl_vhost_parser(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_HEADER)
+#define lwsl_vhost_header(_v, ...) lwsl_vhost(_v, LLL_HEADER, __VA_ARGS__)
+#else
+#define lwsl_vhost_header(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_EXT)
+#define lwsl_vhost_ext(_v, ...) lwsl_vhost(_v, LLL_EXT, __VA_ARGS__)
+#else
+#define lwsl_vhost_ext(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_CLIENT)
+#define lwsl_vhost_client(_v, ...) lwsl_vhost(_v, LLL_CLIENT, __VA_ARGS__)
+#else
+#define lwsl_vhost_client(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_LATENCY)
+#define lwsl_vhost_latency(_v, ...) lwsl_vhost(_v, LLL_LATENCY, __VA_ARGS__)
+#else
+#define lwsl_vhost_latency(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_THREAD)
+#define lwsl_vhost_thread(_v, ...) lwsl_vhost(_v, LLL_THREAD, __VA_ARGS__)
+#else
+#define lwsl_vhost_thread(_v, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_USER)
+#define lwsl_vhost_user(_v, ...) lwsl_vhost(_v, LLL_USER, __VA_ARGS__)
+#else
+#define lwsl_vhost_user(_v, ...) do {} while(0)
+#endif
+
+#define lwsl_hexdump_vhost_err(_v, ...)    lwsl_hexdump_vhost(_v, LLL_ERR, __VA_ARGS__)
+#define lwsl_hexdump_vhost_warn(_v, ...)   lwsl_hexdump_vhost(_v, LLL_WARN, __VA_ARGS__)
+#define lwsl_hexdump_vhost_notice(_v, ...) lwsl_hexdump_vhost(_v, LLL_NOTICE, __VA_ARGS__)
+#define lwsl_hexdump_vhost_info(_v, ...)   lwsl_hexdump_vhost(_v, LLL_INFO, __VA_ARGS__)
+#define lwsl_hexdump_vhost_debug(_v, ...)  lwsl_hexdump_vhost(_v, LLL_DEBUG, __VA_ARGS__)
+
+
+/*
+ * lws_wsi
+ */
+
+#if (_LWS_ENABLED_LOGS & LLL_ERR)
+#define lwsl_wsi_err(_w, ...) lwsl_wsi(_w, LLL_ERR, __VA_ARGS__)
+#else
+#define lwsl_wsi_err(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_WARN)
+#define lwsl_wsi_warn(_w, ...) lwsl_wsi(_w, LLL_WARN, __VA_ARGS__)
+#else
+#define lwsl_wsi_warn(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_NOTICE)
+#define lwsl_wsi_notice(_w, ...) lwsl_wsi(_w, LLL_NOTICE, __VA_ARGS__)
+#else
+#define lwsl_wsi_notice(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_INFO)
+#define lwsl_wsi_info(_w, ...) lwsl_wsi(_w, LLL_INFO, __VA_ARGS__)
+#else
+#define lwsl_wsi_info(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_DEBUG)
+#define lwsl_wsi_debug(_w, ...) lwsl_wsi(_w, LLL_DEBUG, __VA_ARGS__)
+#else
+#define lwsl_wsi_debug(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_PARSER)
+#define lwsl_wsi_parser(_w, ...) lwsl_wsi(_w, LLL_PARSER, __VA_ARGS__)
+#else
+#define lwsl_wsi_parser(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_HEADER)
+#define lwsl_wsi_header(_w, ...) lwsl_wsi(_w, LLL_HEADER, __VA_ARGS__)
+#else
+#define lwsl_wsi_header(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_EXT)
+#define lwsl_wsi_ext(_w, ...) lwsl_wsi(_w, LLL_EXT, __VA_ARGS__)
+#else
+#define lwsl_wsi_ext(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_CLIENT)
+#define lwsl_wsi_client(_w, ...) lwsl_wsi(_w, LLL_CLIENT, __VA_ARGS__)
+#else
+#define lwsl_wsi_client(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_LATENCY)
+#define lwsl_wsi_latency(_w, ...) lwsl_wsi(_w, LLL_LATENCY, __VA_ARGS__)
+#else
+#define lwsl_wsi_latency(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_THREAD)
+#define lwsl_wsi_thread(_w, ...) lwsl_wsi(_w, LLL_THREAD, __VA_ARGS__)
+#else
+#define lwsl_wsi_thread(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_USER)
+#define lwsl_wsi_user(_w, ...) lwsl_wsi(_w, LLL_USER, __VA_ARGS__)
+#else
+#define lwsl_wsi_user(_w, ...) do {} while(0)
+#endif
+
+#define lwsl_hexdump_wsi_err(_v, ...)    lwsl_hexdump_wsi(_v, LLL_ERR, __VA_ARGS__)
+#define lwsl_hexdump_wsi_warn(_v, ...)   lwsl_hexdump_wsi(_v, LLL_WARN, __VA_ARGS__)
+#define lwsl_hexdump_wsi_notice(_v, ...) lwsl_hexdump_wsi(_v, LLL_NOTICE, __VA_ARGS__)
+#define lwsl_hexdump_wsi_info(_v, ...)   lwsl_hexdump_wsi(_v, LLL_INFO, __VA_ARGS__)
+#define lwsl_hexdump_wsi_debug(_v, ...)  lwsl_hexdump_wsi(_v, LLL_DEBUG, __VA_ARGS__)
+
+
+/*
+ * lwsl_ss
+ */
+
+#if (_LWS_ENABLED_LOGS & LLL_ERR)
+#define lwsl_ss_err(_w, ...) lwsl_ss(_w, LLL_ERR, __VA_ARGS__)
+#else
+#define lwsl_ss_err(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_WARN)
+#define lwsl_ss_warn(_w, ...) lwsl_ss(_w, LLL_WARN, __VA_ARGS__)
+#else
+#define lwsl_ss_warn(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_NOTICE)
+#define lwsl_ss_notice(_w, ...) lwsl_ss(_w, LLL_NOTICE, __VA_ARGS__)
+#else
+#define lwsl_ss_notice(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_INFO)
+#define lwsl_ss_info(_w, ...) lwsl_ss(_w, LLL_INFO, __VA_ARGS__)
+#else
+#define lwsl_ss_info(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_DEBUG)
+#define lwsl_ss_debug(_w, ...) lwsl_ss(_w, LLL_DEBUG, __VA_ARGS__)
+#else
+#define lwsl_ss_debug(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_PARSER)
+#define lwsl_ss_parser(_w, ...) lwsl_ss(_w, LLL_PARSER, __VA_ARGS__)
+#else
+#define lwsl_ss_parser(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_HEADER)
+#define lwsl_ss_header(_w, ...) lwsl_ss(_w, LLL_HEADER, __VA_ARGS__)
+#else
+#define lwsl_ss_header(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_EXT)
+#define lwsl_ss_ext(_w, ...) lwsl_ss(_w, LLL_EXT, __VA_ARGS__)
+#else
+#define lwsl_ss_ext(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_CLIENT)
+#define lwsl_ss_client(_w, ...) lwsl_ss(_w, LLL_CLIENT, __VA_ARGS__)
+#else
+#define lwsl_ss_client(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_LATENCY)
+#define lwsl_ss_latency(_w, ...) lwsl_ss(_w, LLL_LATENCY, __VA_ARGS__)
+#else
+#define lwsl_ss_latency(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_THREAD)
+#define lwsl_ss_thread(_w, ...) lwsl_ss(_w, LLL_THREAD, __VA_ARGS__)
+#else
+#define lwsl_ss_thread(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_USER)
+#define lwsl_ss_user(_w, ...) lwsl_ss(_w, LLL_USER, __VA_ARGS__)
+#else
+#define lwsl_ss_user(_w, ...) do {} while(0)
+#endif
+
+#define lwsl_hexdump_ss_err(_v, ...)    lwsl_hexdump_ss(_v, LLL_ERR, __VA_ARGS__)
+#define lwsl_hexdump_ss_warn(_v, ...)   lwsl_hexdump_ss(_v, LLL_WARN, __VA_ARGS__)
+#define lwsl_hexdump_ss_notice(_v, ...) lwsl_hexdump_ss(_v, LLL_NOTICE, __VA_ARGS__)
+#define lwsl_hexdump_ss_info(_v, ...)   lwsl_hexdump_ss(_v, LLL_INFO, __VA_ARGS__)
+#define lwsl_hexdump_ss_debug(_v, ...)  lwsl_hexdump_ss(_v, LLL_DEBUG, __VA_ARGS__)
+
+
+
+/**
+ * lwsl_hexdump_level() - helper to hexdump a buffer at a selected debug level
+ *
+ * \param level: one of LLL_ constants
+ * \param vbuf: buffer start to dump
+ * \param len: length of buffer to dump
+ *
+ * If \p level is visible, does a nice hexdump -C style dump of \p vbuf for
+ * \p len bytes.  This can be extremely convenient while debugging.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsl_hexdump_level(int level, const void *vbuf, size_t len);
+
+LWS_VISIBLE LWS_EXTERN void
+lwsl_hexdump_level_cx(lws_log_cx_t *cx, lws_log_prepend_cx_t prep, void *obj,
+		      int hexdump_level, const void *vbuf, size_t len);
+
+/**
+ * lwsl_hexdump() - helper to hexdump a buffer (DEBUG builds only)
+ *
+ * \param buf: buffer start to dump
+ * \param len: length of buffer to dump
+ *
+ * Calls through to lwsl_hexdump_level(LLL_DEBUG, ... for compatability.
+ * It's better to use lwsl_hexdump_level(level, ... directly so you can control
+ * the visibility.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsl_hexdump(const void *buf, size_t len);
+
+/**
+ * lws_is_be() - returns nonzero if the platform is Big Endian
+ */
+static LWS_INLINE int lws_is_be(void) {
+	const int probe = ~0xff;
+
+	return *(const char *)&probe;
+}
+
+/**
+ * lws_set_log_level() - Set the logging bitfield
+ * \param level:	OR together the LLL_ debug contexts you want output from
+ * \param log_emit_function:	NULL to leave it as it is, or a user-supplied
+ *			function to perform log string emission instead of
+ *			the default stderr one.
+ *
+ * log level defaults to "err", "warn" and "notice" contexts enabled and
+ * emission on stderr.  If stderr is a tty (according to isatty()) then
+ * the output is coloured according to the log level using ANSI escapes.
+ *
+ * You can set the default security level for logging using the
+ * secrecy_and_log_level() macro to set the \p level parameter, eg
+ *
+ * lws_set_log_level(secrecy_and_log_level(LWS_SECRECY_PII, LLL_ERR | LLL_WARN),
+ *		     my_emit_function);
+ *
+ * Normally you can just leave it at the default.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_set_log_level(int level, lws_log_emit_t log_emit_function);
+
+/**
+ * lwsl_emit_syslog() - helper log emit function writes to system log
+ *
+ * \param level: one of LLL_ log level indexes
+ * \param line: log string
+ *
+ * You use this by passing the function pointer to lws_set_log_level(), to set
+ * it as the log emit function, it is not called directly.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsl_emit_syslog(int level, const char *line);
+
+/**
+ * lwsl_emit_stderr() - helper log emit function writes to stderr
+ *
+ * \param level: one of LLL_ log level indexes
+ * \param line: log string
+ *
+ * You use this by passing the function pointer to lws_set_log_level(), to set
+ * it as the log emit function, it is not called directly.
+ *
+ * It prepends a system timestamp like [2018/11/13 07:41:57:3989]
+ *
+ * If stderr is a tty, then ansi colour codes are added.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsl_emit_stderr(int level, const char *line);
+
+/**
+ * lwsl_emit_stderr_notimestamp() - helper log emit function writes to stderr
+ *
+ * \param level: one of LLL_ log level indexes
+ * \param line: log string
+ *
+ * You use this by passing the function pointer to lws_set_log_level(), to set
+ * it as the log emit function, it is not called directly.
+ *
+ * If stderr is a tty, then ansi colour codes are added.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsl_emit_stderr_notimestamp(int level, const char *line);
+
+/**
+ * lwsl_visible() - returns true if the log level should be printed
+ *
+ * \param level: one of LLL_ log level indexes
+ *
+ * This is useful if you have to do work to generate the log content, you
+ * can skip the work if the log level used to print it is not actually
+ * enabled at runtime.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lwsl_visible(int level);
+
+struct lws;
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_wsi_tag(struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lwsl_refcount_cx(lws_log_cx_t *cx, int _new);
+
+///@}

include/libwebsockets/lws-lwsac.h

@@ -0,0 +1,290 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup lwsac lwsac
+ *
+ * ##Allocated Chunks
+ *
+ * If you know you will be allocating a large, unknown number of same or
+ * differently sized objects, it's certainly possible to do it with libc
+ * malloc.  However the allocation cost in time and memory overhead can
+ * add up, and deallocation means walking the structure of every object and
+ * freeing them in turn.
+ *
+ * lwsac (LWS Allocated Chunks) allocates chunks intended to be larger
+ * than your objects (4000 bytes by default) which you linearly allocate from
+ * using lwsac_use().
+ *
+ * If your next request won't fit in the current chunk, a new chunk is added
+ * to the chain of chunks and the allocaton done from there.  If the request
+ * is larger than the chunk size, an oversize chunk is created to satisfy it.
+ *
+ * When you are finished with the allocations, you call lwsac_free() and
+ * free all the *chunks*.  So you may have thousands of objects in the chunks,
+ * but they are all destroyed with the chunks without having to deallocate them
+ * one by one pointlessly.
+ */
+///@{
+
+struct lwsac;
+typedef unsigned char * lwsac_cached_file_t;
+
+
+#define lws_list_ptr_container(P,T,M) ((T *)((char *)(P) - offsetof(T, M)))
+
+/*
+ * linked-list helper that's commonly useful to manage lists of things
+ * allocated using lwsac.
+ *
+ * These lists point to their corresponding "next" member in the target, NOT
+ * the original containing struct.  To get the containing struct, you must use
+ * lws_list_ptr_container() to convert.
+ *
+ * It's like that because it means we no longer have to have the next pointer
+ * at the start of the struct, and we can have the same struct on multiple
+ * linked-lists with everything held in the struct itself.
+ */
+typedef void * lws_list_ptr;
+
+/*
+ * optional sorting callback called by lws_list_ptr_insert() to sort the right
+ * things inside the opqaue struct being sorted / inserted on the list.
+ */
+typedef int (*lws_list_ptr_sort_func_t)(lws_list_ptr a, lws_list_ptr b);
+
+#define lws_list_ptr_advance(_lp) _lp = *((void **)_lp)
+
+/* sort may be NULL if you don't care about order */
+LWS_VISIBLE LWS_EXTERN void
+lws_list_ptr_insert(lws_list_ptr *phead, lws_list_ptr *add,
+		    lws_list_ptr_sort_func_t sort);
+
+
+/**
+ * lwsac_use - allocate / use some memory from a lwsac
+ *
+ * \param head: pointer to the lwsac list object
+ * \param ensure: the number of bytes we want to use
+ * \param chunk_size: 0, or the size of the chunk to (over)allocate if
+ *			what we want won't fit in the current tail chunk.  If
+ *			0, the default value of 4000 is used. If ensure is
+ *			larger, it is used instead.
+ *
+ * This also serves to init the lwsac if *head is NULL.  Basically it does
+ * whatever is necessary to return you a pointer to ensure bytes of memory
+ * reserved for the caller.
+ *
+ * This always allocates in the current chunk or a new chunk... see the
+ * lwsac_use_backfill() variant to try first to find space in earlier chunks.
+ *
+ * Returns NULL if OOM.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lwsac_use(struct lwsac **head, size_t ensure, size_t chunk_size);
+
+/**
+ * lwsac_use_backfill - allocate / use some memory from a lwsac
+ *
+ * \param head: pointer to the lwsac list object
+ * \param ensure: the number of bytes we want to use
+ * \param chunk_size: 0, or the size of the chunk to (over)allocate if
+ *			what we want won't fit in the current tail chunk.  If
+ *			0, the default value of 4000 is used. If ensure is
+ *			larger, it is used instead.
+ *
+ * This also serves to init the lwsac if *head is NULL.  Basically it does
+ * whatever is necessary to return you a pointer to ensure bytes of memory
+ * reserved for the caller.
+ *
+ * Also checks if earlier blocks have enough remaining space to take the
+ * allocation before making a new allocation.
+ *
+ * Returns NULL if OOM.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lwsac_use_backfill(struct lwsac **head, size_t ensure, size_t chunk_size);
+
+/**
+ * lwsac_use - allocate / use some memory from a lwsac
+ *
+ * \param head: pointer to the lwsac list object
+ * \param ensure: the number of bytes we want to use, which must be zeroed
+ * \param chunk_size: 0, or the size of the chunk to (over)allocate if
+ *			what we want won't fit in the current tail chunk.  If
+ *			0, the default value of 4000 is used. If ensure is
+ *			larger, it is used instead.
+ *
+ * Same as lwsac_use(), but \p ensure bytes of memory at the return address
+ * are zero'd before returning.
+ *
+ * Returns NULL if OOM.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lwsac_use_zero(struct lwsac **head, size_t ensure, size_t chunk_size);
+
+#define lwsac_use_zeroed lwsac_use_zero
+
+/**
+ * lwsac_free - deallocate all chunks in the lwsac and set head NULL
+ *
+ * \param head: pointer to the lwsac list object
+ *
+ * This deallocates all chunks in the lwsac, then sets *head to NULL.  All
+ * lwsac_use() pointers are invalidated in one hit without individual frees.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsac_free(struct lwsac **head);
+
+/*
+ * Optional helpers useful for where consumers may need to defer destruction
+ * until all consumers are finished with the lwsac
+ */
+
+/**
+ * lwsac_detach() - destroy an lwsac unless somebody else is referencing it
+ *
+ * \param head: pointer to the lwsac list object
+ *
+ * The creator of the lwsac can all this instead of lwsac_free() when it itself
+ * has finished with the lwsac, but other code may be consuming it.
+ *
+ * If there are no other references, the lwsac is destroyed, *head is set to
+ * NULL and that's the end; however if something else has called
+ * lwsac_reference() on the lwsac, it simply returns.  When lws_unreference()
+ * is called and no references are left, it will be destroyed then.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsac_detach(struct lwsac **head);
+
+/**
+ * lwsac_reference() - increase the lwsac reference count
+ *
+ * \param head: pointer to the lwsac list object
+ *
+ * Increment the reference count on the lwsac to defer destruction.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsac_reference(struct lwsac *head);
+
+/**
+ * lwsac_unreference() - decrease the lwsac reference count
+ *
+ * \param head: pointer to the lwsac list object
+ *
+ * Decrement the reference count on the lwsac... if it reached 0 on a detached
+ * lwsac then the lwsac is immediately destroyed and *head set to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lwsac_unreference(struct lwsac **head);
+
+/**
+ * lwsac_extend() - try to increase the size of the last block
+ *
+ * \param head: pointer to the lwsac list object
+ * \param amount: amount to try to increase usage for
+ *
+ * This will either increase the usage reservation of the last allocated block
+ * by amount and return 0, or fail and return 1.
+ *
+ * This is very cheap to call and is designed to optimize usage after a static
+ * struct for vari-sized additional content which may flow into an additional
+ * block in a new chunk if necessary, but wants to make the most of the space
+ * in front of it first to try to avoid gaps and the new chunk if it can.
+ *
+ * The additional area if the call succeeds will have been memset to 0.
+ *
+ * To use it, the following must be true:
+ *
+ * - only the last lwsac use can be extended
+ *
+ * - if another use happens inbetween the use and extend, it will break
+ *
+ * - the use cannot have been using backfill
+ *
+ * - a user object must be tracking the current allocated size of the last use
+ *   (lwsac doesn't know it) and increment by amount if the extend call succeeds
+ *
+ * Despite these restrictions this can be an important optimization for some
+ * cases
+ */
+LWS_VISIBLE LWS_EXTERN int
+lwsac_extend(struct lwsac *head, size_t amount);
+
+/* helpers to keep a file cached in memory */
+
+LWS_VISIBLE LWS_EXTERN void
+lwsac_use_cached_file_start(lwsac_cached_file_t cache);
+
+LWS_VISIBLE LWS_EXTERN void
+lwsac_use_cached_file_end(lwsac_cached_file_t *cache);
+
+LWS_VISIBLE LWS_EXTERN void
+lwsac_use_cached_file_detach(lwsac_cached_file_t *cache);
+
+LWS_VISIBLE LWS_EXTERN int
+lwsac_cached_file(const char *filepath, lwsac_cached_file_t *cache,
+		  size_t *len);
+
+/* more advanced helpers */
+
+/* offset from lac to start of payload, first = 1 = first lac in chain */
+LWS_VISIBLE LWS_EXTERN size_t
+lwsac_sizeof(int first);
+
+LWS_VISIBLE LWS_EXTERN size_t
+lwsac_get_tail_pos(struct lwsac *lac);
+
+LWS_VISIBLE LWS_EXTERN struct lwsac *
+lwsac_get_next(struct lwsac *lac);
+
+LWS_VISIBLE LWS_EXTERN size_t
+lwsac_align(size_t length);
+
+LWS_VISIBLE LWS_EXTERN void
+lwsac_info(struct lwsac *head);
+
+LWS_VISIBLE LWS_EXTERN uint64_t
+lwsac_total_alloc(struct lwsac *head);
+
+LWS_VISIBLE LWS_EXTERN uint64_t
+lwsac_total_overhead(struct lwsac *head);
+
+/**
+ * lwsac_scan_extant() - returns existing copy of blob, or NULL
+ *
+ * \param head: the lwsac to scan
+ * \param find: the blob to look for
+ * \param len: the length of the blob to look for
+ * \param nul: nonzero if the next byte must be NUL
+ *
+ * Helper that looks through a whole lwsac for a given binary blob already
+ * present.  Used in the case that lwsac contents are const once written, and
+ * strings or blobs may be repeated in the input: this allows the earlier
+ * copy to be pointed to by subsequent references without repeating the string
+ * or blob redundantly.
+ */
+LWS_VISIBLE LWS_EXTERN uint8_t *
+lwsac_scan_extant(struct lwsac *head, uint8_t *find, size_t len, int nul);
+
+///@}

include/libwebsockets/lws-map.h

@@ -0,0 +1,188 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup lws_map generic map apis
+ * ##Generic map structures and apis
+ * \ingroup lwsapi
+ *
+ * lws_map
+ *
+ * Discrete owner object represents the whole map, created with key-specific
+ * ops for hashing the key to a uint32_t and comparing two keys.  Owns a list
+ * of hash tables whose size / modulo it set at creation time.
+ *
+ * Items in the map are contained in a lws_map_item_t that is indexed in a
+ * hash table.
+ *
+ * It's difficult to make a single compact map abstraction that fits all cases,
+ * this is useful to the extent you have the memory to trade off the number of
+ * hashtables needed for the amount of items and the lookup latency limit for
+ * your application, typically for hundreds or low thousands of items.
+ */
+//@{
+
+typedef struct lws_map lws_map_t;
+struct lws_map_item;
+
+typedef void * lws_map_key_t;
+typedef void * lws_map_value_t;
+typedef uint32_t lws_map_hash_t;
+
+typedef lws_map_hash_t (*lws_map_hash_from_key_t)(const lws_map_key_t key,
+						  size_t kl);
+typedef int (*lws_map_compare_key_t)(const lws_map_key_t key1, size_t kl1,
+				     const lws_map_value_t key2, size_t kl2);
+typedef void * (*lws_map_alloc_t)(struct lws_map *mo, size_t x);
+typedef void (*lws_map_free_t)(void *);
+
+/*
+ * Creation parameters for the map, copied into the map owner
+ */
+
+typedef struct lws_map_info {
+	lws_map_hash_from_key_t		_hash;
+	lws_map_compare_key_t		_compare;
+	lws_map_alloc_t			_alloc;	/* NULL = lws_malloc */
+	lws_map_free_t			_free;	/* NULL = lws_free */
+
+	void				*opaque;
+	/**< &lwsac if using lwsac allocator */
+	void				*aux;
+	/**< chunk size if using lwsac allocator */
+	/**< this can be used by the alloc handler, eg for lws_ac */
+	size_t				modulo;
+	/**< number of hashed owner lists to create */
+} lws_map_info_t;
+
+LWS_VISIBLE LWS_EXTERN const void *
+lws_map_item_key(struct lws_map_item *_item);
+LWS_VISIBLE LWS_EXTERN const void *
+lws_map_item_value(struct lws_map_item *_item);
+LWS_VISIBLE LWS_EXTERN size_t
+lws_map_item_key_len(struct lws_map_item *_item);
+LWS_VISIBLE LWS_EXTERN size_t
+lws_map_item_value_len(struct lws_map_item *_item);
+
+/*
+ * Helpers for C string keys case
+ */
+
+#define lws_map_item_create_ks(_map, _str, _v, _vl) \
+		lws_map_item_create(_map, (const lws_map_key_t)_str, \
+				    strlen(_str), (const lws_map_value_t)_v, \
+						    _vl)
+#define lws_map_item_lookup_ks(_map, _str) \
+		lws_map_item_lookup(_map, (const lws_map_key_t)_str, strlen(_str))
+
+/**
+ * lws_map_create() - create a map object and hashtables on heap
+ *
+ * \param info: description of map to create
+ *
+ * Creates a map object on heap, using lws_malloc().
+ *
+ * \p info may be all zeros inside, if so, modulo defaults to 8, and the
+ * operation callbacks default to using lws_malloc() / _free() for item alloc,
+ * a default xor / shift based hash and simple linear memory key compare.
+ *
+ * For less typical use-cases, the provided \p info members can be tuned to
+ * control how the allocation of mapped items is done, lws provides two exports
+ * lws_map_alloc_lwsac() and lws_map_free_lwsac() that can be used for _alloc
+ * and _free to have items allocated inside an lwsac.
+ *
+ * The map itself is created on the heap directly, the info._alloc() op is only
+ * used when creating items.
+ *
+ * keys have individual memory sizes and do not need to all be the same length.
+ */
+LWS_VISIBLE LWS_EXTERN lws_map_t *
+lws_map_create(const lws_map_info_t *info);
+
+/*
+ * helpers that can be used for info._alloc and info._free if using lwsac
+ * allocation for items, set info.opaque to point to the lwsac pointer, and
+ * aux to (void *)chunksize, or leave zero / NULL for the default
+ */
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_map_alloc_lwsac(struct lws_map *map, size_t x);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_map_free_lwsac(void *v);
+
+/**
+ * lws_map_destroy() - deallocate all items and free map
+ *
+ * \param pmap: pointer to pointer map object to deallocate
+ *
+ * Frees all items in the map, using info._free(), and then frees the map
+ * from heap directly.  \p *pmap is set to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_map_destroy(lws_map_t **pmap);
+
+/**
+ * lws_map_item_create() - allocate and map an item into an existing map
+ *
+ * \param map: the map to add items into
+ * \param key: the key, may be any kind of object
+ * \param keylen: the length of the key in bytes
+ * \param value: the value, may be any kind of object
+ * \param valuelen: the length of value
+ *
+ * Allocates space for the item, key and value using the map allocator, and
+ * if non-NULL, copies the key and value into the item.
+ *
+ * If an item with the same key exists, it is removed and destroyed before
+ * creating and adding the new one.
+ */
+
+LWS_VISIBLE LWS_EXTERN struct lws_map_item *
+lws_map_item_create(lws_map_t *map,
+		    const lws_map_key_t key, size_t keylen,
+		    const lws_map_value_t value, size_t valuelen);
+
+/**
+ * lws_map_item_destroy() - remove item from map and free
+ *
+ * \param item: the item in the map to remove and free
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_map_item_destroy(struct lws_map_item *item);
+
+/**
+ * lws_map_item_lookup() - look for a item with the given key in the map
+ *
+ * \param map: the map
+ * \param key: the key to look for
+ * \param keylen: the length of the key to look for
+ *
+ * Searches for the key in the map, using the map's key hash and key compare
+ * functions.
+ */
+
+LWS_VISIBLE LWS_EXTERN struct lws_map_item *
+lws_map_item_lookup(lws_map_t *map, const lws_map_key_t key, size_t keylen);
+
+//@}

include/libwebsockets/lws-metrics.h

@@ -0,0 +1,329 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * Public apis related to metric collection and reporting
+ */
+
+/* lws_metrics public part */
+
+typedef uint64_t u_mt_t;
+
+enum {
+	LWSMTFL_REPORT_OUTLIERS				= (1 << 0),
+	/**< track outliers and report them internally */
+	LWSMTFL_REPORT_OOB				= (1 << 1),
+	/**< report events as they happen */
+	LWSMTFL_REPORT_INACTIVITY_AT_PERIODIC		= (1 << 2),
+	/**< explicitly externally report no activity at periodic cb, by
+	 * default no events in the period is just not reported */
+	LWSMTFL_REPORT_MEAN				= (1 << 3),
+	/**< average/min/max is meaningful, else only sum is meaningful */
+	LWSMTFL_REPORT_ONLY_GO				= (1 << 4),
+	/**< no-go pieces invalid */
+	LWSMTFL_REPORT_DUTY_WALLCLOCK_US		= (1 << 5),
+	/**< aggregate compares to wallclock us for duty cycle */
+	LWSMTFL_REPORT_HIST				= (1 << 6),
+	/**< our type is histogram (otherwise, sum / mean aggregation) */
+};
+
+/*
+ * lws_metrics_tag allows your object to accumulate OpenMetrics-style
+ * descriptive tags before accounting for it with a metrics object at the end.
+ *
+ * Tags should represent low entropy information that is likely to repeat
+ * identically, so, eg, http method name, not eg, latency in us which is
+ * unlikely to be seen the same twice.
+ *
+ * Tags are just a list of name=value pairs, used for qualifying the final
+ * metrics entry with decorations in additional dimensions.  For example,
+ * rather than keep individual metrics on methods, scheme, mountpoint, result
+ * code, you can keep metrics on http transactions only, and qualify the
+ * transaction metrics entries with tags that can be queried on the metrics
+ * backend to get the finer-grained information.
+ *
+ * http_srv{code="404",mount="/",method="GET",scheme="http"} 3
+ *
+ * For OpenMetrics the tags are converted to a { list } and appended to the base
+ * metrics name before using with actual metrics objects, the same set of tags
+ * on different transactions resolve to the same qualification string.
+ */
+
+typedef struct lws_metrics_tag {
+	lws_dll2_t	list;
+
+	const char	*name; /* tag, intended to be in .rodata, not copied */
+	/* overallocated value */
+} lws_metrics_tag_t;
+
+LWS_EXTERN LWS_VISIBLE int
+lws_metrics_tag_add(lws_dll2_owner_t *owner, const char *name, const char *val);
+
+#if defined(LWS_WITH_SYS_METRICS)
+/*
+ * wsi-specific version that also appends the tag value to the lifecycle tag
+ * used for logging the wsi identity
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_metrics_tag_wsi_add(struct lws *wsi, const char *name, const char *val);
+#else
+#define lws_metrics_tag_wsi_add(_a, _b, _c)
+#endif
+
+#if defined(LWS_WITH_SECURE_STREAMS)
+/*
+ * ss-specific version that also appends the tag value to the lifecycle tag
+ * used for logging the ss identity
+ */
+#if defined(LWS_WITH_SYS_METRICS)
+LWS_EXTERN LWS_VISIBLE int
+lws_metrics_tag_ss_add(struct lws_ss_handle *ss, const char *name, const char *val);
+#else
+#define lws_metrics_tag_ss_add(_a, _b, _c)
+#endif
+#endif
+
+LWS_EXTERN LWS_VISIBLE void
+lws_metrics_tags_destroy(lws_dll2_owner_t *owner);
+
+LWS_EXTERN LWS_VISIBLE size_t
+lws_metrics_tags_serialize(lws_dll2_owner_t *owner, char *buf, size_t len);
+
+LWS_EXTERN LWS_VISIBLE const char *
+lws_metrics_tag_get(lws_dll2_owner_t *owner, const char *name);
+
+/* histogram bucket */
+
+typedef struct lws_metric_bucket {
+	struct lws_metric_bucket	*next;
+	uint64_t			count;
+
+	/* name + NUL is overallocated */
+} lws_metric_bucket_t;
+
+/* get overallocated name of bucket from bucket pointer */
+#define lws_metric_bucket_name_len(_b) (*((uint8_t *)&(_b)[1]))
+#define lws_metric_bucket_name(_b) (((const char *)&(_b)[1]) + 1)
+
+/*
+ * These represent persistent local event measurements.  They may aggregate
+ * a large number of events inbetween external dumping of summaries of the
+ * period covered, in two different ways
+ *
+ * 1) aggregation by sum or mean, to absorb multiple scalar readings
+ *
+ *  - go / no-go ratio counting
+ *  - mean averaging for, eg, latencies
+ *  - min / max for averaged values
+ *  - period the stats covers
+ *
+ * 2) aggregation by histogram, to absorb a range of outcomes that may occur
+ *    multiple times
+ *
+ *  - add named buckets to histogram
+ *  - bucket has a 64-bit count
+ *  - bumping a bucket just increments the count if already exists, else adds
+ *    a new one with count set to 1
+ *
+ * The same type with a union covers both cases.
+ *
+ * The lws_system ops api that hooks lws_metrics up to a metrics backend is
+ * given a pointer to these according to the related policy, eg, hourly, or
+ * every event passed straight through.
+ */
+
+typedef struct lws_metric_pub {
+	const char		*name;
+	/**< eg, "n.cn.dns", "vh.myendpoint" */
+	void			*backend_opaque;
+	/**< ignored by lws, backend handler completely owns it */
+
+	lws_usec_t		us_first;
+	/**< us time metric started collecting, reset to us_dumped at dump */
+	lws_usec_t		us_last;
+	/**< 0, or us time last event, reset to 0 at last dump */
+	lws_usec_t		us_dumped;
+	/**< 0 if never, else us time of last dump to external api */
+
+	/* scope of data in .u is "since last dump" --> */
+
+	union {
+		/* aggregation, by sum or mean */
+
+		struct {
+			u_mt_t			sum[2];
+			/**< go, no-go summed for mean or plan sum */
+			u_mt_t			min;
+			/**< smallest individual measurement */
+			u_mt_t			max;
+			/**< largest individual measurement */
+
+			uint32_t		count[2];
+			/**< go, no-go count of measurements in sum */
+		} agg;
+
+		/* histogram with dynamic named buckets */
+
+		struct {
+			lws_metric_bucket_t	*head;
+			/**< first bucket in our bucket list */
+
+			uint64_t		total_count;
+			/**< total count in all of our buckets */
+			uint32_t		list_size;
+			/**< number of buckets in our bucket list */
+		} hist;
+	} u;
+
+	uint8_t			flags;
+
+} lws_metric_pub_t;
+
+LWS_EXTERN LWS_VISIBLE void
+lws_metrics_hist_bump_priv_tagged(lws_metric_pub_t *mt, lws_dll2_owner_t *tow,
+				  lws_dll2_owner_t *tow2);
+
+
+/*
+ * Calipers are a helper struct for implementing "hanging latency" detection,
+ * where setting the start time and finding the end time may happen in more than
+ * one place.
+ *
+ * There are convenience wrappers to eliminate caliper definitions and code
+ * cleanly if WITH_SYS_METRICS is disabled for the build.
+ */
+
+struct lws_metric;
+
+typedef struct lws_metric_caliper {
+	struct lws_dll2_owner	mtags_owner; /**< collect tags here during
+					      * caliper lifetime */
+	struct lws_metric	*mt; /**< NULL == inactive */
+	lws_usec_t		us_start;
+} lws_metric_caliper_t;
+
+#if defined(LWS_WITH_SYS_METRICS)
+#define lws_metrics_caliper_compose(_name) \
+		lws_metric_caliper_t _name;
+#define lws_metrics_caliper_bind(_name, _mt) \
+	{ if (_name.mt) { \
+		lwsl_err("caliper: overwrite %s\n", \
+				lws_metrics_priv_to_pub(_name.mt)->name); \
+		assert(0); } \
+	  _name.mt = _mt; _name.us_start = lws_now_usecs(); }
+#define lws_metrics_caliper_declare(_name, _mt) \
+	lws_metric_caliper_t _name = { .mt = _mt, .us_start = lws_now_usecs() }
+#define lws_metrics_caliper_report(_name, _go_nogo) \
+	{ if (_name.us_start) { lws_metric_event(_name.mt, _go_nogo, \
+			   (u_mt_t)(lws_now_usecs() - \
+					   _name.us_start)); \
+					  }  lws_metrics_caliper_done(_name);  }
+#define lws_metrics_caliper_report_hist(_name, pwsi) if (_name.mt) { \
+		lws_metrics_hist_bump_priv_tagged(lws_metrics_priv_to_pub(_name.mt), \
+						  &_name.mtags_owner, \
+						  pwsi ? &((pwsi)->cal_conn.mtags_owner) : NULL); \
+		lws_metrics_caliper_done(_name);  }
+
+#define lws_metrics_caliper_cancel(_name) { lws_metrics_caliper_done(_name); }
+#define lws_metrics_hist_bump(_mt, _name) \
+		lws_metrics_hist_bump_(_mt, _name)
+#define lws_metrics_hist_bump_priv(_mt, _name) \
+		lws_metrics_hist_bump_(lws_metrics_priv_to_pub(_mt), _name)
+#define lws_metrics_caliper_done(_name) { \
+		_name.us_start = 0; _name.mt = NULL; \
+		lws_metrics_tags_destroy(&_name.mtags_owner); }
+#else
+#define lws_metrics_caliper_compose(_name)
+#define lws_metrics_caliper_bind(_name, _mt)
+#define lws_metrics_caliper_declare(_name, _mp)
+#define lws_metrics_caliper_report(_name, _go_nogo)
+#define lws_metrics_caliper_report_hist(_name, pwsiconn)
+#define lws_metrics_caliper_cancel(_name)
+#define lws_metrics_hist_bump(_mt, _name)
+#define lws_metrics_hist_bump_priv(_mt, _name)
+#define lws_metrics_caliper_done(_name)
+#endif
+
+/**
+ * lws_metrics_format() - helper to format a metrics object for logging
+ *
+ * \param pub: public part of metrics object
+ * \param buf: output buffer to place string in
+ * \param len: available length of \p buf
+ *
+ * Helper for describing the state of a metrics object as a human-readable
+ * string, accounting for how its flags indicate what it contains.  This is not
+ * how you would report metrics, but during development it can be useful to
+ * log them inbetween possibily long report intervals.
+ *
+ * It uses the metric's flags to adapt the format shown appropriately, eg,
+ * as a histogram if LWSMTFL_REPORT_HIST etc
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_metrics_format(lws_metric_pub_t *pub, lws_metric_bucket_t **sub,
+		   char *buf, size_t len);
+
+/**
+ * lws_metrics_hist_bump() - add or increment histogram bucket
+ *
+ * \param pub: public part of metrics object
+ * \param name: bucket name to increment
+ *
+ * Either increment the count of an existing bucket of the right name in the
+ * metrics object, or add a new bucket of the given name and set its count to 1.
+ *
+ * The metrics object must have been created with flag LWSMTFL_REPORT_HIST
+ *
+ * Normally, you will actually use the preprocessor wrapper
+ * lws_metrics_hist_bump() defined above, since this automatically takes care of
+ * removing itself from the build if WITH_SYS_METRICS is not defined, without
+ * needing any preprocessor conditionals.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_metrics_hist_bump_(lws_metric_pub_t *pub, const char *name);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_metrics_foreach(struct lws_context *ctx, void *user,
+		    int (*cb)(lws_metric_pub_t *pub, void *user));
+
+LWS_VISIBLE LWS_EXTERN int
+lws_metrics_hist_bump_describe_wsi(struct lws *wsi, lws_metric_pub_t *pub,
+				   const char *name);
+
+enum {
+	LMT_NORMAL = 0,	/* related to successful events */
+	LMT_OUTLIER,	/* related to successful events outside of bounds */
+
+	LMT_FAIL,	/* related to failed events */
+
+	LMT_COUNT,
+};
+
+typedef enum lws_metric_rpt {
+	LMR_PERIODIC = 0,	/* we are reporting on a schedule */
+	LMR_OUTLIER,		/* we are reporting the last outlier */
+} lws_metric_rpt_kind_t;
+
+#define METRES_GO	0
+#define METRES_NOGO	1
+
+

include/libwebsockets/lws-misc.h

@@ -0,0 +1,1122 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#if defined(LWS_WITH_SPAWN)
+
+#if defined(WIN32) || defined(_WIN32)
+#else
+#include <sys/wait.h>
+#include <sys/times.h>
+#endif
+#endif
+
+#if defined(__OpenBSD__)
+#include <sys/siginfo.h>
+#endif
+
+/** \defgroup misc Miscellaneous APIs
+* ##Miscellaneous APIs
+*
+* Various APIs outside of other categories
+*/
+///@{
+
+struct lws_buflist;
+
+/**
+ * lws_buflist_append_segment(): add buffer to buflist at head
+ *
+ * \param head: list head
+ * \param buf: buffer to stash
+ * \param len: length of buffer to stash
+ *
+ * Returns -1 on OOM, 1 if this was the first segment on the list, and 0 if
+ * it was a subsequent segment.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_buflist_append_segment(struct lws_buflist **head, const uint8_t *buf,
+			   size_t len);
+/**
+ * lws_buflist_next_segment_len(): number of bytes left in current segment
+ *
+ * \param head: list head
+ * \param buf: if non-NULL, *buf is written with the address of the start of
+ *		the remaining data in the segment
+ *
+ * Returns the number of bytes left in the current segment.  0 indicates
+ * that the buflist is empty (there are no segments on the buflist).
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_buflist_next_segment_len(struct lws_buflist **head, uint8_t **buf);
+
+/**
+ * lws_buflist_use_segment(): remove len bytes from the current segment
+ *
+ * \param head: list head
+ * \param len: number of bytes to mark as used
+ *
+ * If len is less than the remaining length of the current segment, the position
+ * in the current segment is simply advanced and it returns.
+ *
+ * If len uses up the remaining length of the current segment, then the segment
+ * is deleted and the list head moves to the next segment if any.
+ *
+ * Returns the number of bytes left in the current segment.  0 indicates
+ * that the buflist is empty (there are no segments on the buflist).
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_buflist_use_segment(struct lws_buflist **head, size_t len);
+
+/**
+ * lws_buflist_total_len(): Get the total size of the buflist
+ *
+ * \param head: list head
+ *
+ * Returns the total number of bytes held on all segments of the buflist
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_buflist_total_len(struct lws_buflist **head);
+
+/**
+ * lws_buflist_linear_copy(): copy everything out as one without consuming
+ *
+ * \param head: list head
+ * \param ofs: start offset into buflist in bytes
+ * \param buf: buffer to copy linearly into
+ * \param len: length of buffer available
+ *
+ * Returns -1 if len is too small, or bytes copied.  Happy to do partial
+ * copies, returns 0 when there are no more bytes to copy.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_buflist_linear_copy(struct lws_buflist **head, size_t ofs, uint8_t *buf,
+			size_t len);
+
+/**
+ * lws_buflist_linear_use(): copy and consume from buflist head
+ *
+ * \param head: list head
+ * \param buf: buffer to copy linearly into
+ * \param len: length of buffer available
+ *
+ * Copies a possibly fragmented buflist from the head into the linear output
+ * buffer \p buf for up to length \p len, and consumes the buflist content that
+ * was copied out.
+ *
+ * Since it was consumed, calling again will resume copying out and consuming
+ * from as far as it got the first time.
+ *
+ * Returns the number of bytes written into \p buf.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_buflist_linear_use(struct lws_buflist **head, uint8_t *buf, size_t len);
+
+/**
+ * lws_buflist_fragment_use(): copy and consume <= 1 frag from buflist head
+ *
+ * \param head: list head
+ * \param buf: buffer to copy linearly into
+ * \param len: length of buffer available
+ * \param frag_first: pointer to char written on exit to if this is start of frag
+ * \param frag_fin: pointer to char written on exit to if this is end of frag
+ *
+ * Copies all or part of the fragment at the start of a buflist from the head
+ * into the output buffer \p buf for up to length \p len, and consumes the
+ * buflist content that was copied out.
+ *
+ * Since it was consumed, calling again will resume copying out and consuming
+ * from as far as it got the first time.
+ *
+ * Returns the number of bytes written into \p buf.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_buflist_fragment_use(struct lws_buflist **head, uint8_t *buf,
+			 size_t len, char *frag_first, char *frag_fin);
+
+/**
+ * lws_buflist_destroy_all_segments(): free all segments on the list
+ *
+ * \param head: list head
+ *
+ * This frees everything on the list unconditionally.  *head is always
+ * NULL after this.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_buflist_destroy_all_segments(struct lws_buflist **head);
+
+/**
+ * lws_buflist_describe(): debug helper logging buflist status
+ *
+ * \param head: list head
+ * \param id: pointer shown in debug list
+ * \param reason: reason string show in debug list
+ *
+ * Iterates through the buflist segments showing position and size.
+ * This only exists when lws was built in debug mode
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_buflist_describe(struct lws_buflist **head, void *id, const char *reason);
+
+/**
+ * lws_ptr_diff(): helper to report distance between pointers as an int
+ *
+ * \param head: the pointer with the larger address
+ * \param tail: the pointer with the smaller address
+ *
+ * This helper gives you an int representing the number of bytes further
+ * forward the first pointer is compared to the second pointer.
+ */
+#define lws_ptr_diff(head, tail) \
+			((int)((char *)(head) - (char *)(tail)))
+
+#define lws_ptr_diff_size_t(head, tail) \
+			((size_t)(ssize_t)((char *)(head) - (char *)(tail)))
+
+/**
+ * lws_snprintf(): snprintf that truncates the returned length too
+ *
+ * \param str: destination buffer
+ * \param size: bytes left in destination buffer
+ * \param format: format string
+ * \param ...: args for format
+ *
+ * This lets you correctly truncate buffers by concatenating lengths, if you
+ * reach the limit the reported length doesn't exceed the limit.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_snprintf(char *str, size_t size, const char *format, ...) LWS_FORMAT(3);
+
+/**
+ * lws_strncpy(): strncpy that guarantees NUL on truncated copy
+ *
+ * \param dest: destination buffer
+ * \param src: source buffer
+ * \param size: bytes left in destination buffer
+ *
+ * This lets you correctly truncate buffers by concatenating lengths, if you
+ * reach the limit the reported length doesn't exceed the limit.
+ */
+LWS_VISIBLE LWS_EXTERN char *
+lws_strncpy(char *dest, const char *src, size_t size);
+
+/*
+ * Variation where we want to use the smaller of two lengths, useful when the
+ * source string is not NUL terminated
+ */
+#define lws_strnncpy(dest, src, size1, destsize) \
+	lws_strncpy(dest, src, (size_t)(size1 + 1) < (size_t)(destsize) ? \
+				(size_t)(size1 + 1) : (size_t)(destsize))
+
+/**
+ * lws_nstrstr(): like strstr for length-based strings without terminating NUL
+ *
+ * \param buf: the string to search
+ * \param len: the length of the string to search
+ * \param name: the substring to search for
+ * \param nl: the length of name
+ *
+ * Returns NULL if \p name is not present in \p buf.  Otherwise returns the
+ * address of the first instance of \p name in \p buf.
+ *
+ * Neither buf nor name need to be NUL-terminated.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_nstrstr(const char *buf, size_t len, const char *name, size_t nl);
+
+/**
+ * lws_json_simple_find(): dumb JSON string parser
+ *
+ * \param buf: the JSON to search
+ * \param len: the length of the JSON to search
+ * \param name: the name field to search the JSON for, eg, "\"myname\":"
+ * \param alen: set to the length of the argument part if non-NULL return
+ *
+ * Either returns NULL if \p name is not present in buf, or returns a pointer
+ * to the argument body of the first instance of \p name, and sets *alen to the
+ * length of the argument body.
+ *
+ * This can cheaply handle fishing out, eg, myarg from {"myname": "myarg"} by
+ * searching for "\"myname\":".  It will return a pointer to myarg and set *alen
+ * to 5.  It equally handles args like "myname": true, or "myname":false, and
+ * null or numbers are all returned as delimited strings.
+ *
+ * Anything more complicated like the value is a subobject or array, you should
+ * parse it using a full parser like lejp.  This is suitable is the JSON is
+ * and will remain short and simple, and contains well-known names amongst other
+ * extensible JSON members.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_json_simple_find(const char *buf, size_t len, const char *name, size_t *alen);
+
+/**
+ * lws_json_simple_strcmp(): dumb JSON string comparison
+ *
+ * \param buf: the JSON to search
+ * \param len: the length of the JSON to search
+ * \param name: the name field to search the JSON for, eg, "\"myname\":"
+ * \param comp: return a strcmp of this and the discovered argument
+ *
+ * Helper that combines lws_json_simple_find() with strcmp() if it was found.
+ * If the \p name was not found, returns -1.  Otherwise returns a strcmp()
+ * between what was found and \p comp, ie, return 0 if they match or something
+ * else if they don't.
+ *
+ * If the JSON is relatively simple and you want to target constrained
+ * devices, this can be a good choice.  If the JSON may be complex, you
+ * should use a full JSON parser.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_json_simple_strcmp(const char *buf, size_t len, const char *name, const char *comp);
+
+
+/**
+ * lws_hex_to_byte_array(): convert hex string like 0123456789ab into byte data
+ *
+ * \param h: incoming NUL-terminated hex string
+ * \param dest: array to fill with binary decodes of hex pairs from h
+ * \param max: maximum number of bytes dest can hold, must be at least half
+ *		the size of strlen(h)
+ *
+ * This converts hex strings into an array of 8-bit representations, ie the
+ * input "abcd" produces two bytes of value 0xab and 0xcd.
+ *
+ * Returns number of bytes produced into \p dest, or -1 on error.
+ *
+ * Errors include non-hex chars and an odd count of hex chars in the input
+ * string.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hex_to_byte_array(const char *h, uint8_t *dest, int max);
+
+/**
+ * lws_hex_from_byte_array(): render byte array as hex char string
+ *
+ * \param src: incoming binary source array
+ * \param slen: length of src in bytes
+ * \param dest: array to fill with hex chars representing src
+ * \param len: max extent of dest
+ *
+ * This converts binary data of length slen at src, into a hex string at dest
+ * of maximum length len.  Even if truncated, the result will be NUL-terminated.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_hex_from_byte_array(const uint8_t *src, size_t slen, char *dest, size_t len);
+
+/**
+ * lws_hex_random(): generate len - 1 or - 2 characters of random ascii hex
+ *
+ * \param context: the lws_context used to get the random
+ * \param dest: destination for hex ascii chars
+ * \param len: the number of bytes the buffer dest points to can hold
+ *
+ * This creates random ascii-hex strings up to a given length, with a
+ * terminating NUL.
+ *
+ * There will not be any characters produced that are not 0-9, a-f, so it's
+ * safe to go straight into, eg, JSON.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_hex_random(struct lws_context *context, char *dest, size_t len);
+
+/*
+ * lws_timingsafe_bcmp(): constant time memcmp
+ *
+ * \param a: first buffer
+ * \param b: second buffer
+ * \param len: count of bytes to compare
+ *
+ * Return 0 if the two buffers are the same, else nonzero.
+ *
+ * Always compares all of the buffer before returning, so it can't be used as
+ * a timing oracle.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_timingsafe_bcmp(const void *a, const void *b, uint32_t len);
+
+/**
+ * lws_get_random(): fill a buffer with platform random data
+ *
+ * \param context: the lws context
+ * \param buf: buffer to fill
+ * \param len: how much to fill
+ *
+ * Fills buf with len bytes of random.  Returns the number of bytes set, if
+ * not equal to len, then getting the random failed.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_get_random(struct lws_context *context, void *buf, size_t len);
+/**
+ * lws_daemonize(): make current process run in the background
+ *
+ * \param _lock_path: the filepath to write the lock file
+ *
+ * Spawn lws as a background process, taking care of various things
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_daemonize(const char *_lock_path);
+/**
+ * lws_get_library_version(): return string describing the version of lws
+ *
+ * On unix, also includes the git describe
+ */
+LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
+lws_get_library_version(void);
+
+/**
+ * lws_wsi_user() - get the user data associated with the connection
+ * \param wsi: lws connection
+ *
+ * Not normally needed since it's passed into the callback
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_wsi_user(struct lws *wsi);
+
+/**
+ * lws_wsi_tsi() - get the service thread index the wsi is bound to
+ * \param wsi: lws connection
+ *
+ * Only useful is LWS_MAX_SMP > 1
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_wsi_tsi(struct lws *wsi);
+
+/**
+ * lws_set_wsi_user() - set the user data associated with the client connection
+ * \param wsi: lws connection
+ * \param user: user data
+ *
+ * By default lws allocates this and it's not legal to externally set it
+ * yourself.  However client connections may have it set externally when the
+ * connection is created... if so, this api can be used to modify it at
+ * runtime additionally.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_set_wsi_user(struct lws *wsi, void *user);
+
+/**
+ * lws_parse_uri:	cut up prot:/ads:port/path into pieces
+ *			Notice it does so by dropping '\0' into input string
+ *			and the leading / on the path is consequently lost
+ *
+ * \param p:			incoming uri string.. will get written to
+ * \param prot:		result pointer for protocol part (https://)
+ * \param ads:		result pointer for address part
+ * \param port:		result pointer for port part
+ * \param path:		result pointer for path part
+ *
+ * You may also refer to unix socket addresses, using a '+' at the start of
+ * the address.  In this case, the address should end with ':', which is
+ * treated as the separator between the address and path (the normal separator
+ * '/' is a valid part of the socket path).  Eg,
+ *
+ * http://+/var/run/mysocket:/my/path
+ *
+ * If the first character after the + is '@', it's interpreted by lws client
+ * processing as meaning to use linux abstract namespace sockets, the @ is
+ * replaced with a '\0' before use.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
+	      const char **path);
+/**
+ * lws_cmdline_option():	simple commandline parser
+ *
+ * \param argc:		count of argument strings
+ * \param argv:		argument strings
+ * \param val:		string to find
+ *
+ * Returns NULL if the string \p val is not found in the arguments.
+ *
+ * If it is found, then it returns a pointer to the next character after \p val.
+ * So if \p val is "-d", then for the commandlines "myapp -d15" and
+ * "myapp -d 15", in both cases the return will point to the "15".
+ *
+ * In the case there is no argument, like "myapp -d", the return will
+ * either point to the '\\0' at the end of -d, or to the start of the
+ * next argument, ie, will be non-NULL.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_cmdline_option(int argc, const char **argv, const char *val);
+
+/**
+ * lws_cmdline_option_handle_builtin(): apply standard cmdline options
+ *
+ * \param argc:		count of argument strings
+ * \param argv:		argument strings
+ * \param info:		context creation info
+ *
+ * Applies standard options to the context creation info to save them having
+ * to be (unevenly) copied into the minimal examples.
+ *
+ * Applies default log levels that can be overriden by -d
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_cmdline_option_handle_builtin(int argc, const char **argv,
+				  struct lws_context_creation_info *info);
+
+/**
+ * lws_now_secs(): return seconds since 1970-1-1
+ */
+LWS_VISIBLE LWS_EXTERN unsigned long
+lws_now_secs(void);
+
+/**
+ * lws_now_usecs(): return useconds since 1970-1-1
+ */
+LWS_VISIBLE LWS_EXTERN lws_usec_t
+lws_now_usecs(void);
+
+/**
+ * lws_get_context - Allow getting lws_context from a Websocket connection
+ * instance
+ *
+ * With this function, users can access context in the callback function.
+ * Otherwise users may have to declare context as a global variable.
+ *
+ * \param wsi:	Websocket connection instance
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
+lws_get_context(const struct lws *wsi);
+
+/**
+ * lws_get_vhost_listen_port - Find out the port number a vhost is listening on
+ *
+ * In the case you passed 0 for the port number at context creation time, you
+ * can discover the port number that was actually chosen for the vhost using
+ * this api.
+ *
+ * \param vhost:	Vhost to get listen port from
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_get_vhost_listen_port(struct lws_vhost *vhost);
+
+/**
+ * lws_get_count_threads(): how many service threads the context uses
+ *
+ * \param context: the lws context
+ *
+ * By default this is always 1, if you asked for more than lws can handle it
+ * will clip the number of threads.  So you can use this to find out how many
+ * threads are actually in use.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_get_count_threads(struct lws_context *context);
+
+/**
+ * lws_get_parent() - get parent wsi or NULL
+ * \param wsi: lws connection
+ *
+ * Specialized wsi like cgi stdin/out/err are associated to a parent wsi,
+ * this allows you to get their parent.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
+lws_get_parent(const struct lws *wsi);
+
+/**
+ * lws_get_child() - get child wsi or NULL
+ * \param wsi: lws connection
+ *
+ * Allows you to find a related wsi from the parent wsi.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
+lws_get_child(const struct lws *wsi);
+
+/**
+ * lws_get_effective_uid_gid() - find out eventual uid and gid while still root
+ *
+ * \param context: lws context
+ * \param uid: pointer to uid result
+ * \param gid: pointer to gid result
+ *
+ * This helper allows you to find out what the uid and gid for the process will
+ * be set to after the privileges are dropped, beforehand.  So while still root,
+ * eg in LWS_CALLBACK_PROTOCOL_INIT, you can arrange things like cache dir
+ * and subdir creation / permissions down /var/cache dynamically.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_get_effective_uid_gid(struct lws_context *context, uid_t *uid, gid_t *gid);
+
+/**
+ * lws_get_udp() - get wsi's udp struct
+ *
+ * \param wsi: lws connection
+ *
+ * Returns NULL or pointer to the wsi's UDP-specific information
+ */
+LWS_VISIBLE LWS_EXTERN const struct lws_udp * LWS_WARN_UNUSED_RESULT
+lws_get_udp(const struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_get_opaque_parent_data(const struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_set_opaque_parent_data(struct lws *wsi, void *data);
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_get_opaque_user_data(const struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_set_opaque_user_data(struct lws *wsi, void *data);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_get_child_pending_on_writable(const struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_clear_child_pending_on_writable(struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_get_close_length(struct lws *wsi);
+
+LWS_VISIBLE LWS_EXTERN unsigned char *
+lws_get_close_payload(struct lws *wsi);
+
+/**
+ * lws_get_network_wsi() - Returns wsi that has the tcp connection for this wsi
+ *
+ * \param wsi: wsi you have
+ *
+ * Returns wsi that has the tcp connection (which may be the incoming wsi)
+ *
+ * HTTP/1 connections will always return the incoming wsi
+ * HTTP/2 connections may return a different wsi that has the tcp connection
+ */
+LWS_VISIBLE LWS_EXTERN
+struct lws *lws_get_network_wsi(struct lws *wsi);
+
+/**
+ * lws_set_allocator() - custom allocator support
+ *
+ * \param realloc
+ *
+ * Allows you to replace the allocator (and deallocator) used by lws
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_set_allocator(void *(*realloc)(void *ptr, size_t size, const char *reason));
+
+enum {
+	/*
+	 * Flags for enable and disable rxflow with reason bitmap and with
+	 * backwards-compatible single bool
+	 */
+	LWS_RXFLOW_REASON_USER_BOOL		= (1 << 0),
+	LWS_RXFLOW_REASON_HTTP_RXBUFFER		= (1 << 6),
+	LWS_RXFLOW_REASON_H2_PPS_PENDING	= (1 << 7),
+
+	LWS_RXFLOW_REASON_APPLIES		= (1 << 14),
+	LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT	= (1 << 13),
+	LWS_RXFLOW_REASON_APPLIES_ENABLE	= LWS_RXFLOW_REASON_APPLIES |
+						  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT,
+	LWS_RXFLOW_REASON_APPLIES_DISABLE	= LWS_RXFLOW_REASON_APPLIES,
+	LWS_RXFLOW_REASON_FLAG_PROCESS_NOW	= (1 << 12),
+
+};
+
+/**
+ * lws_rx_flow_control() - Enable and disable socket servicing for
+ *				received packets.
+ *
+ * If the output side of a server process becomes choked, this allows flow
+ * control for the input side.
+ *
+ * \param wsi:	Websocket connection instance to get callback for
+ * \param enable:	0 = disable read servicing for this connection, 1 = enable
+ *
+ * If you need more than one additive reason for rxflow control, you can give
+ * iLWS_RXFLOW_REASON_APPLIES_ENABLE or _DISABLE together with one or more of
+ * b5..b0 set to idicate which bits to enable or disable.  If any bits are
+ * enabled, rx on the connection is suppressed.
+ *
+ * LWS_RXFLOW_REASON_FLAG_PROCESS_NOW  flag may also be given to force any change
+ * in rxflowbstatus to benapplied immediately, this should be used when you are
+ * changing a wsi flow control state from outside a callback on that wsi.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_rx_flow_control(struct lws *wsi, int enable);
+
+/**
+ * lws_rx_flow_allow_all_protocol() - Allow all connections with this protocol to receive
+ *
+ * When the user server code realizes it can accept more input, it can
+ * call this to have the RX flow restriction removed from all connections using
+ * the given protocol.
+ * \param context:	lws_context
+ * \param protocol:	all connections using this protocol will be allowed to receive
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_rx_flow_allow_all_protocol(const struct lws_context *context,
+			       const struct lws_protocols *protocol);
+
+/**
+ * lws_remaining_packet_payload() - Bytes to come before "overall"
+ *					      rx fragment is complete
+ * \param wsi:		Websocket instance (available from user callback)
+ *
+ * This tracks how many bytes are left in the current ws fragment, according
+ * to the ws length given in the fragment header.
+ *
+ * If the message was in a single fragment, and there is no compression, this
+ * is the same as "how much data is left to read for this message".
+ *
+ * However, if the message is being sent in multiple fragments, this will
+ * reflect the unread amount of the current **fragment**, not the message.  With
+ * ws, it is legal to not know the length of the message before it completes.
+ *
+ * Additionally if the message is sent via the negotiated permessage-deflate
+ * extension, this number only tells the amount of **compressed** data left to
+ * be read, since that is the only information available at the ws layer.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_remaining_packet_payload(struct lws *wsi);
+
+#if defined(LWS_WITH_DIR)
+
+typedef enum {
+	LDOT_UNKNOWN,
+	LDOT_FILE,
+	LDOT_DIR,
+	LDOT_LINK,
+	LDOT_FIFO,
+	LDOTT_SOCKET,
+	LDOT_CHAR,
+	LDOT_BLOCK
+} lws_dir_obj_type_t;
+
+struct lws_dir_entry {
+	const char *name;
+	lws_dir_obj_type_t type;
+};
+
+typedef int
+lws_dir_callback_function(const char *dirpath, void *user,
+			  struct lws_dir_entry *lde);
+
+/**
+ * lws_dir() - get a callback for everything in a directory
+ *
+ * \param dirpath: the directory to scan
+ * \param user: pointer to give to callback
+ * \param cb: callback to receive information on each file or dir
+ *
+ * Calls \p cb (with \p user) for every object in dirpath.
+ *
+ * This wraps whether it's using POSIX apis, or libuv (as needed for windows,
+ * since it refuses to support POSIX apis for this).
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_dir(const char *dirpath, void *user, lws_dir_callback_function cb);
+
+/**
+ * lws_dir_rm_rf_cb() - callback for lws_dir that performs recursive rm -rf
+ *
+ * \param dirpath: directory we are at in lws_dir
+ * \param user: ignored
+ * \param lde: lws_dir info on the file or directory we are at
+ *
+ * This is a readymade rm -rf callback for use with lws_dir.  It recursively
+ * removes everything below the starting dir and then the starting dir itself.
+ * Works on linux, OSX and Windows at least.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_dir_rm_rf_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);
+
+/*
+ * We pass every file in the base dir through a filter, and call back on the
+ * ones that match.  Directories are ignored.
+ *
+ * The original path filter string may look like, eg, "sai-*.deb" or "*.txt"
+ */
+
+typedef int (*lws_dir_glob_cb_t)(void *data, const char *path);
+
+typedef struct lws_dir_glob {
+	const char		*filter;
+	lws_dir_glob_cb_t	cb;
+	void			*user;
+} lws_dir_glob_t;
+
+/**
+ * lws_dir_glob_cb() - callback for lws_dir that performs filename globbing
+ *
+ * \param dirpath: directory we are at in lws_dir
+ * \param user: pointer to your prepared lws_dir_glob_cb_t
+ * \param lde: lws_dir info on the file or directory we are at
+ *
+ * \p user is prepared with an `lws_dir_glob_t` containing a callback for paths
+ * that pass the filtering, a user pointer to pass to that callback, and a
+ * glob string like "*.txt".  It may not contain directories, the lws_dir musr
+ * be started at the correct dir.
+ *
+ * Only the base path passed to lws_dir is scanned, it does not look in subdirs.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_dir_glob_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);
+
+#endif
+
+/**
+ * lws_get_allocated_heap() - if the platform supports it, returns amount of
+ *				heap allocated by lws itself
+ *
+ * On glibc currently, this reports the total amount of current logical heap
+ * allocation, found by tracking the amount allocated by lws_malloc() and
+ * friends and accounting for freed allocations via lws_free().
+ *
+ * This is useful for confirming where processwide heap allocations actually
+ * come from... this number represents all lws internal allocations, for
+ * fd tables, wsi allocations, ah, etc combined.  It doesn't include allocations
+ * from user code, since lws_malloc() etc are not exported from the library.
+ *
+ * On other platforms, it always returns 0.
+ */
+size_t lws_get_allocated_heap(void);
+
+/**
+ * lws_get_tsi() - Get thread service index wsi belong to
+ * \param wsi:  websocket connection to check
+ *
+ * Returns more than zero (or zero if only one service thread as is the default).
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_get_tsi(struct lws *wsi);
+
+/**
+ * lws_is_ssl() - Find out if connection is using SSL
+ * \param wsi:	websocket connection to check
+ *
+ * Returns nonzero if the wsi is inside a tls tunnel, else zero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_is_ssl(struct lws *wsi);
+/**
+ * lws_is_cgi() - find out if this wsi is running a cgi process
+ *
+ * \param wsi: lws connection
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_is_cgi(struct lws *wsi);
+
+/**
+ * lws_tls_jit_trust_blob_queury_skid() - walk jit trust blob for skid
+ *
+ * \param _blob: the start of the blob in memory
+ * \param blen: the length of the blob in memory
+ * \param skid: the SKID we are looking for
+ * \param skid_len: the length of the SKID we are looking for
+ * \param prpder: result pointer to receive a pointer to the matching DER
+ * \param prder_len: result pointer to receive matching DER length
+ *
+ * Helper to scan a JIT Trust blob in memory for a trusted CA cert matching
+ * a given SKID.  Returns 0 if found and *prpder and *prder_len are set, else
+ * nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_tls_jit_trust_blob_queury_skid(const void *_blob, size_t blen,
+				   const uint8_t *skid, size_t skid_len,
+				   const uint8_t **prpder, size_t *prder_len);
+
+/**
+ * lws_open() - platform-specific wrapper for open that prepares the fd
+ *
+ * \param __file: the filepath to open
+ * \param __oflag: option flags
+ *
+ * This is a wrapper around platform open() that sets options on the fd
+ * according to lws policy.  Currently that is FD_CLOEXEC to stop the opened
+ * fd being available to any child process forked by user code.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_open(const char *__file, int __oflag, ...);
+
+struct lws_wifi_scan { /* generic wlan scan item */
+	struct lws_wifi_scan *next;
+	char ssid[32];
+	int32_t rssi; /* divide by .count to get db */
+	uint8_t bssid[6];
+	uint8_t count;
+	uint8_t channel;
+	uint8_t authmode;
+};
+
+#if defined(LWS_WITH_TLS) && !defined(LWS_WITH_MBEDTLS)
+/**
+ * lws_get_ssl() - Return wsi's SSL context structure
+ * \param wsi:	websocket connection
+ *
+ * Returns pointer to the SSL library's context structure
+ */
+LWS_VISIBLE LWS_EXTERN SSL*
+lws_get_ssl(struct lws *wsi);
+#endif
+
+LWS_VISIBLE LWS_EXTERN void
+lws_explicit_bzero(void *p, size_t len);
+
+typedef struct lws_humanize_unit {
+	const char *name; /* array ends with NULL name */
+	uint64_t factor;
+} lws_humanize_unit_t;
+
+LWS_VISIBLE extern const lws_humanize_unit_t humanize_schema_si[7];
+LWS_VISIBLE extern const lws_humanize_unit_t humanize_schema_si_bytes[7];
+LWS_VISIBLE extern const lws_humanize_unit_t humanize_schema_us[8];
+
+/**
+ * lws_humanize() - Convert possibly large number to human-readable uints
+ *
+ * \param buf: result string buffer
+ * \param len: remaining length in \p buf
+ * \param value: the uint64_t value to represent
+ * \param schema: and array of scaling factors and units
+ *
+ * This produces a concise string representation of \p value, referencing the
+ * schema \p schema of scaling factors and units to find the smallest way to
+ * render it.
+ *
+ * Three schema are exported from lws for general use, humanize_schema_si, which
+ * represents as, eg, "  22.130Gi" or " 128      "; humanize_schema_si_bytes
+ * which is the same but shows, eg, "  22.130GiB", and humanize_schema_us,
+ * which represents a count of us as a human-readable time like "  14.350min",
+ * or "  1.500d".
+ *
+ * You can produce your own schema.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_humanize(char *buf, size_t len, uint64_t value,
+	     const lws_humanize_unit_t *schema);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_ser_wu16be(uint8_t *b, uint16_t u);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_ser_wu32be(uint8_t *b, uint32_t u32);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_ser_wu64be(uint8_t *b, uint64_t u64);
+
+LWS_VISIBLE LWS_EXTERN uint16_t
+lws_ser_ru16be(const uint8_t *b);
+
+LWS_VISIBLE LWS_EXTERN uint32_t
+lws_ser_ru32be(const uint8_t *b);
+
+LWS_VISIBLE LWS_EXTERN uint64_t
+lws_ser_ru64be(const uint8_t *b);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_vbi_encode(uint64_t value, void *buf);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_vbi_decode(const void *buf, uint64_t *value, size_t len);
+
+///@}
+
+#if defined(LWS_WITH_SPAWN)
+
+/* opaque internal struct */
+struct lws_spawn_piped;
+
+#if defined(WIN32)
+struct _lws_siginfo_t {
+	int retcode;
+};
+typedef struct _lws_siginfo_t siginfo_t;
+#endif
+
+typedef void (*lsp_cb_t)(void *opaque, lws_usec_t *accounting, siginfo_t *si,
+			 int we_killed_him);
+
+
+/**
+ * lws_spawn_piped_info - details given to create a spawned pipe
+ *
+ * \p owner: lws_dll2_owner_t that lists all active spawns, or NULL
+ * \p vh: vhost to bind stdwsi to... from opt_parent if given
+ * \p opt_parent: optional parent wsi for stdwsi
+ * \p exec_array: argv for process to spawn
+ * \p env_array: environment for spawned process, NULL ends env list
+ * \p protocol_name: NULL, or vhost protocol name to bind stdwsi to
+ * \p chroot_path: NULL, or chroot patch for child process
+ * \p wd: working directory to cd to after fork, NULL defaults to /tmp
+ * \p plsp: NULL, or pointer to the outer lsp pointer so it can be set NULL when destroyed
+ * \p opaque: pointer passed to the reap callback, if any
+ * \p timeout: optional us-resolution timeout, or zero
+ * \p reap_cb: callback when child process has been reaped and the lsp destroyed
+ * \p tsi: tsi to bind stdwsi to... from opt_parent if given
+ */
+struct lws_spawn_piped_info {
+	struct lws_dll2_owner		*owner;
+	struct lws_vhost		*vh;
+	struct lws			*opt_parent;
+
+	const char * const		*exec_array;
+	const char			**env_array;
+	const char			*protocol_name;
+	const char			*chroot_path;
+	const char			*wd;
+
+	struct lws_spawn_piped		**plsp;
+
+	void				*opaque;
+
+	lsp_cb_t			reap_cb;
+
+	lws_usec_t			timeout_us;
+	int				max_log_lines;
+	int				tsi;
+
+	const struct lws_role_ops	*ops; /* NULL is raw file */
+
+	uint8_t				disable_ctrlc;
+};
+
+/**
+ * lws_spawn_piped() - spawn a child process with stdxxx redirected
+ *
+ * \p lspi: info struct describing details of spawn to create
+ *
+ * This spawns a child process managed in the lsp object and with attributes
+ * set in the arguments.  The stdin/out/err streams are redirected to pipes
+ * which are instantiated into wsi that become child wsi of \p parent if non-
+ * NULL.  .opaque_user_data on the stdwsi created is set to point to the
+ * lsp object, so this can be recovered easily in the protocol handler.
+ *
+ * If \p owner is non-NULL, successful spawns join the given dll2 owner in the
+ * original process.
+ *
+ * If \p timeout is non-zero, successful spawns register a sul with the us-
+ * resolution timeout to callback \p timeout_cb, in the original process.
+ *
+ * Returns 0 if the spawn went OK or nonzero if it failed and was cleaned up.
+ * The spawned process continues asynchronously and this will return after
+ * starting it if all went well.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_spawn_piped *
+lws_spawn_piped(const struct lws_spawn_piped_info *lspi);
+
+/*
+ * lws_spawn_piped_kill_child_process() - attempt to kill child process
+ *
+ * \p lsp: child object to kill
+ *
+ * Attempts to signal the child process in \p lsp to terminate.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_spawn_piped_kill_child_process(struct lws_spawn_piped *lsp);
+
+/**
+ * lws_spawn_stdwsi_closed() - inform the spawn one of its stdxxx pipes closed
+ *
+ * \p lsp: the spawn object
+ * \p wsi: the wsi that is closing
+ *
+ * When you notice one of the spawn stdxxx pipes closed, inform the spawn
+ * instance using this api.  When it sees all three have closed, it will
+ * automatically try to reap the child process.
+ *
+ * This is the mechanism whereby the spawn object can understand its child
+ * has closed.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_spawn_stdwsi_closed(struct lws_spawn_piped *lsp, struct lws *wsi);
+
+/**
+ * lws_spawn_get_stdfd() - return std channel index for stdwsi
+ *
+ * \p wsi: the wsi
+ *
+ * If you know wsi is a stdwsi from a spawn, you can determine its original
+ * channel index / fd before the pipes replaced the default fds.  It will return
+ * one of 0 (STDIN), 1 (STDOUT) or 2 (STDERR).  You can handle all three in the
+ * same protocol handler and then disambiguate them using this api.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_spawn_get_stdfd(struct lws *wsi);
+
+#endif
+
+struct lws_fsmount {
+	const char	*layers_path;	/* where layers live */
+	const char	*overlay_path;	/* where overlay instantiations live */
+
+	char		mp[256];	/* mountpoint path */
+	char		ovname[64];	/* unique name for mount instance */
+	char		distro[64];	/* unique name for layer source */
+
+#if defined(__linux__)
+	const char	*layers[4];	/* distro layers, like "base", "env" */
+#endif
+};
+
+/**
+ * lws_fsmount_mount() - Mounts an overlayfs stack of layers
+ *
+ * \p fsm: struct lws_fsmount specifying the mount layout
+ *
+ * This api is able to assemble up to 4 layer directories on to a mountpoint
+ * using overlayfs mount (Linux only).
+ *
+ * Set fsm.layers_path to the base dir where the layers themselves live, the
+ * entries in fsm.layers[] specifies the relative path to the layer, comprising
+ * fsm.layers_path/fsm.distro/fsm.layers[], with [0] being the deepest, earliest
+ * layer and the rest being progressively on top of [0]; NULL indicates the
+ * layer is unused.
+ *
+ * fsm.overlay_path is the base path of the overlayfs instantiations... empty
+ * dirs must exist at
+ *
+ * fsm.overlay_path/overlays/fsm.ovname/work
+ * fsm.overlay_path/overlays/fsm.ovname/session
+ *
+ * Set fsm.mp to the path of an already-existing empty dir that will be the
+ * mountpoint, this can be whereever you like.
+ *
+ * Overlayfs merges the union of all the contributing layers at the mountpoint,
+ * the mount is writeable but the layer themselves are immutable, all additions
+ * and changes are stored in
+ *
+ * fsm.overlay_path/overlays/fsm.ovname/session
+ *
+ * Returns 0 if mounted OK, nonzero if errors.
+ *
+ * Retain fsm for use with unmounting.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fsmount_mount(struct lws_fsmount *fsm);
+
+/**
+ * lws_fsmount_unmount() - Unmounts an overlayfs dir
+ *
+ * \p fsm: struct lws_fsmount specifying the mount layout
+ *
+ * Unmounts the mountpoint in fsm.mp.
+ *
+ * Delete fsm.overlay_path/overlays/fsm.ovname/session to permanently eradicate
+ * all changes from the time the mountpoint was in use.
+ *
+ * Returns 0 if unmounted OK.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_fsmount_unmount(struct lws_fsmount *fsm);

include/libwebsockets/lws-mqtt.h

@@ -0,0 +1,381 @@
+/*
+ * libwebsockets - protocol - mqtt
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * included from libwebsockets.h
+ */
+
+#ifndef _LWS_MQTT_H
+#define _LWS_MQTT_H 1
+
+struct _lws_mqtt_related;
+typedef struct _lws_mqtt_related lws_mqtt_related_t;
+struct lws_mqtt_str_st;
+typedef struct lws_mqtt_str_st lws_mqtt_str_t;
+
+#define MQTT_VER_3_1_1 4
+
+#define LWS_MQTT_FINAL_PART 1
+
+#define LWS_MQTT_MAX_AWSIOT_TOPICLEN  256
+#define LWS_MQTT_MAX_TOPICLEN  65535
+#define LWS_MQTT_MAX_CIDLEN    128
+#define LWS_MQTT_RANDOM_CIDLEN 23 /* 3.1.3.1-5: Server MUST... between
+				     1 and 23 chars... */
+
+#define LWS_MQTT_SHADOW_MAX_THING_LEN 128
+#define LWS_MQTT_SHADOW_MAX_SHADOW_LEN 64
+#define LWS_MQTT_SHADOW_UPDATE_STR "/update"
+#define LWS_MQTT_SHADOW_DELETE_STR "/delete"
+#define LWS_MQTT_SHADOW_GET_STR "/get"
+#define LWS_MQTT_SHADOW_RESP_ACCEPTED_STR  "/accepted"
+#define LWS_MQTT_SHADOW_RESP_REJECTED_STR "/rejected"
+#define LWS_MQTT_SHADOW_RESP_DELTA_STR "/delta"
+#define LWS_MQTT_SHADOW_RESP_DOCUMENT_STR "/documents"
+#define LWS_MQTT_SHADOW_UPDATE_ACCEPTED_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_ACCEPTED_STR
+#define LWS_MQTT_SHADOW_UPDATE_REJECTED_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_REJECTED_STR
+#define LWS_MQTT_SHADOW_UPDATE_DELTA_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_DELTA_STR
+#define LWS_MQTT_SHADOW_UPDATE_DOCUMENT_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_DOCUMENT_STR
+#define LWS_MQTT_SHADOW_DELETE_ACCEPTED_STR LWS_MQTT_SHADOW_DELETE_STR LWS_MQTT_SHADOW_RESP_ACCEPTED_STR
+#define LWS_MQTT_SHADOW_DELETE_REJECTED_STR LWS_MQTT_SHADOW_DELETE_STR LWS_MQTT_SHADOW_RESP_REJECTED_STR
+#define LWS_MQTT_SHADOW_GET_ACCEPTED_STR LWS_MQTT_SHADOW_GET_STR LWS_MQTT_SHADOW_RESP_ACCEPTED_STR
+#define LWS_MQTT_SHADOW_GET_REJECTED_STR LWS_MQTT_SHADOW_GET_STR LWS_MQTT_SHADOW_RESP_REJECTED_STR
+#define LWS_MQTT_SHADOW_PREFIX_FORMAT "$aws/things/%s"
+#define LWS_MQTT_SHADOW_NAMED_SHADOW_TOPIC_FORMAT LWS_MQTT_SHADOW_PREFIX_FORMAT "/shadow/name/%s%s"
+#define LWS_MQTT_SHADOW_UNNAMED_SHADOW_TOPIC_FORMAT  LWS_MQTT_SHADOW_PREFIX_FORMAT "/shadow%s"
+#define LWS_MQTT_SHADOW_UNNAMED_TOPIC_MATCH	"$aws/things/+/shadow/+"
+#define LWS_MQTT_SHADOW_NAMED_TOPIC_MATCH	"$aws/things/+/shadow/name/+/+"
+
+typedef enum {
+	QOS0,
+	QOS1,
+	QOS2,				/* not supported */
+	RESERVED_QOS_LEVEL,
+	FAILURE_QOS_LEVEL = 0x80
+} lws_mqtt_qos_levels_t;
+
+typedef union {
+	struct {
+		uint8_t		retain:1;
+		uint8_t 	qos:2;
+		uint8_t 	dup:1;
+		uint8_t 	ctrl_pkt_type:4;
+	} flags;
+	uint8_t 		bits;
+} lws_mqtt_fixed_hdr_t;
+
+/*
+ * MQTT connection parameters, passed into struct
+ * lws_client_connect_info to establish a connection using
+ * lws_client_connect_via_info().
+*/
+typedef struct lws_mqtt_client_connect_param_s {
+	const char 			*client_id;	/* Client ID */
+	uint16_t 			keep_alive;	/* MQTT keep alive
+							   interval in
+							   seconds */
+	uint8_t 			clean_start:1;	/* MQTT clean
+							   session */
+	uint8_t				client_id_nofree:1;
+	/**< do not free the client id */
+	uint8_t				username_nofree:1;
+	/**< do not free the username */
+	uint8_t				password_nofree:1;
+	/**< do not free the password */
+	struct {
+		const char 		*topic;
+		const char 		*message;
+		lws_mqtt_qos_levels_t	qos;
+		uint8_t 		retain;
+	} will_param;				/* MQTT LWT
+						   parameters */
+	struct {
+		const char 		*topic;
+		const char 		*message;
+		lws_mqtt_qos_levels_t	qos;
+		uint8_t 		retain;
+	} birth_param;				/* MQTT Birth
+						   parameters */
+	const char 			*username;
+	const char 			*password;
+	uint8_t				aws_iot;
+} lws_mqtt_client_connect_param_t;
+
+/*
+ * MQTT publish parameters
+*/
+typedef struct lws_mqtt_publish_param_s {
+	char			*topic;		/* Topic Name */
+	uint16_t 		topic_len;
+	const void 		*payload;	/* Publish Payload */
+	uint32_t 		payload_len;	/* Size of the
+						   complete payload */
+	uint32_t		payload_pos;	/* where we are in payload */
+	lws_mqtt_qos_levels_t 	qos;
+
+	/*--v-Following will be used by LWS-v--*/
+	uint16_t 		packet_id;	/* Packet ID for QoS >
+						   0 */
+	uint8_t 		dup:1;		/* Retried PUBLISH,
+						   for QoS > 0 */
+	uint8_t			retain:1;	/* Retained message */
+} lws_mqtt_publish_param_t;
+
+typedef struct topic_elem {
+	const char		*name;		/* Topic Name */
+	lws_mqtt_qos_levels_t 	qos;		/* Requested QoS */
+
+	/*--v-Following will be used by LWS-v--*/
+	uint8_t 		acked;
+} lws_mqtt_topic_elem_t;
+
+/*
+ * MQTT publish parameters
+*/
+typedef struct lws_mqtt_subscribe_param_s {
+	uint32_t		num_topics;	/* Number of topics */
+	lws_mqtt_topic_elem_t	*topic;		/* Array of topic elements */
+
+	/*--v-Following will be used by LWS-v--*/
+	uint16_t		packet_id;
+} lws_mqtt_subscribe_param_t;
+
+typedef enum {
+	LMQCP_RESERVED,
+	LMQCP_CTOS_CONNECT,	/* Connection request */
+	LMQCP_STOC_CONNACK,	/* Connection acknowledgment */
+	LMQCP_PUBLISH,		/* Publish Message */
+	LMQCP_PUBACK,		/* QoS 1:   Publish acknowledgment */
+	LMQCP_PUBREC,		/* QoS 2.1: Publish received */
+	LMQCP_PUBREL,		/* QoS 2.2: Publish release */
+	LMQCP_PUBCOMP,		/* QoS 2.3: Publish complete */
+	LMQCP_CTOS_SUBSCRIBE,	/* Subscribe request */
+	LMQCP_STOC_SUBACK,	/* Subscribe acknowledgment */
+	LMQCP_CTOS_UNSUBSCRIBE, /* Unsubscribe request */
+	LMQCP_STOC_UNSUBACK,	/* Unsubscribe acknowledgment */
+	LMQCP_CTOS_PINGREQ,	/* PING request */
+	LMQCP_STOC_PINGRESP,	/* PONG response */
+	LMQCP_DISCONNECT,	/* Disconnect notification */
+	LMQCP_AUTH		/* Authentication exchange */
+} lws_mqtt_control_packet_t;
+
+/* flags from byte 8 of C_TO_S CONNECT */
+typedef enum {
+	LMQCFT_USERNAME_NOFREE					= (1 << 10),
+	LMQCFT_PASSWORD_NOFREE					= (1 << 9),
+	LMQCFT_CLIENT_ID_NOFREE					= (1 << 8),
+	/* only the low 8 are standardized and go out in the protocol */
+	LMQCFT_USERNAME						= (1 << 7),
+	LMQCFT_PASSWORD						= (1 << 6),
+	LMQCFT_WILL_RETAIN					= (1 << 5),
+	LMQCFT_WILL_QOS						= (1 << 3),
+	LMQCFT_WILL_FLAG					= (1 << 2),
+	LMQCFT_CLEAN_START					= (1 << 1),
+	LMQCFT_RESERVED						= (1 << 0),
+
+	LMQCFT_WILL_QOS_MASK					= (3 << 3),
+} lws_mqtt_connect_flags_t;
+
+/* flags for S_TO_C CONNACK */
+typedef enum {
+	LMQCFT_SESSION_PRESENT					= (1 << 0),
+} lws_mqtt_connack_flags_t;
+
+typedef enum {
+	LMQCP_REASON_SUCCESS					= 0x00,
+	LMQCP_REASON_NORMAL_DISCONNECTION			= 0x00,
+	LMQCP_REASON_GRANTED_QOS0				= 0x00,
+	LMQCP_REASON_GRANTED_QOS1				= 0x01,
+	LMQCP_REASON_GRANTED_QOS2				= 0x02,
+	LMQCP_REASON_DISCONNECT_WILL				= 0x04,
+	LMQCP_REASON_NO_MATCHING_SUBSCRIBER			= 0x10,
+	LMQCP_REASON_NO_SUBSCRIPTION_EXISTED			= 0x11,
+	LMQCP_REASON_CONTINUE_AUTHENTICATION			= 0x18,
+	LMQCP_REASON_RE_AUTHENTICATE				= 0x19,
+
+	LMQCP_REASON_UNSPECIFIED_ERROR				= 0x80,
+	LMQCP_REASON_MALFORMED_PACKET				= 0x81,
+	LMQCP_REASON_PROTOCOL_ERROR				= 0x82,
+	LMQCP_REASON_IMPLEMENTATION_SPECIFIC_ERROR		= 0x83,
+
+	/* Begin - Error codes for CONNACK */
+	LMQCP_REASON_UNSUPPORTED_PROTOCOL			= 0x84,
+	LMQCP_REASON_CLIENT_ID_INVALID				= 0x85,
+	LMQCP_REASON_BAD_CREDENTIALS				= 0x86,
+	LMQCP_REASON_NOT_AUTHORIZED				= 0x87,
+	/* End - Error codes for CONNACK */
+
+	LMQCP_REASON_SERVER_UNAVAILABLE				= 0x88,
+	LMQCP_REASON_SERVER_BUSY				= 0x89,
+	LMQCP_REASON_BANNED					= 0x8a,
+	LMQCP_REASON_SERVER_SHUTTING_DOWN			= 0x8b,
+	LMQCP_REASON_BAD_AUTHENTICATION_METHOD			= 0x8c,
+	LMQCP_REASON_KEEPALIVE_TIMEOUT				= 0x8d,
+	LMQCP_REASON_SESSION_TAKEN_OVER				= 0x8e,
+	LMQCP_REASON_TOPIC_FILTER_INVALID			= 0x8f,
+	LMQCP_REASON_TOPIC_NAME_INVALID				= 0x90,
+	LMQCP_REASON_PACKET_ID_IN_USE				= 0x91,
+	LMQCP_REASON_PACKET_ID_NOT_FOUND			= 0x92,
+	LMQCP_REASON_MAX_RX_EXCEEDED				= 0x93,
+	LMQCP_REASON_TOPIC_ALIAS_INVALID			= 0x94,
+	LMQCP_REASON_PACKET_TOO_LARGE				= 0x95,
+	LMQCP_REASON_RATELIMIT					= 0x96,
+	LMQCP_REASON_QUOTA_EXCEEDED				= 0x97,
+	LMQCP_REASON_ADMINISTRATIVE_ACTION			= 0x98,
+	LMQCP_REASON_PAYLOAD_FORMAT_INVALID			= 0x99,
+	LMQCP_REASON_RETAIN_NOT_SUPPORTED			= 0x9a,
+	LMQCP_REASON_QOS_NOT_SUPPORTED				= 0x9b,
+	LMQCP_REASON_USE_ANOTHER_SERVER				= 0x9c,
+	LMQCP_REASON_SERVER_MOVED				= 0x9d,
+	LMQCP_REASON_SHARED_SUBSCRIPTIONS_NOT_SUPPORTED		= 0x9e,
+	LMQCP_REASON_CONNECTION_RATE_EXCEEDED			= 0x9f,
+	LMQCP_REASON_MAXIMUM_CONNECT_TIME			= 0xa0,
+	LMQCP_REASON_SUBSCRIPTION_IDS_NOT_SUPPORTED		= 0xa1,
+	LMQCP_REASON_WILDCARD_SUBSCRIPTIONS_NOT_SUPPORTED	= 0xa2,
+} lws_mqtt_reason_t;
+
+typedef enum {
+	LMQPROP_INVALID,
+	LMQPROP_PAYLOAD_FORMAT_INDICATOR			= 0x01,
+	LMQPROP_MESSAGE_EXPIRY_INTERVAL				= 0x02,
+	LMQPROP_CONTENT_TYPE					= 0x03,
+	LMQPROP_RESPONSE_TOPIC					= 0x08,
+	LMQPROP_CORRELATION_DATA				= 0x09,
+	LMQPROP_SUBSCRIPTION_IDENTIFIER				= 0x0b,
+	LMQPROP_SESSION_EXPIRY_INTERVAL				= 0x11,
+	LMQPROP_ASSIGNED_CLIENT_IDENTIFIER			= 0x12,
+	LMQPROP_SERVER_KEEP_ALIVE				= 0x13,
+	LMQPROP_AUTHENTICATION_METHOD				= 0x15,
+	LMQPROP_AUTHENTICATION_DATA				= 0x16,
+	LMQPROP_REQUEST_PROBLEM_INFORMATION			= 0x17,
+	LMQPROP_WILL_DELAY_INTERVAL				= 0x18,
+	LMQPROP_REQUEST_RESPONSE_INFORMATION			= 0x19,
+	LMQPROP_RESPONSE_INFORMATION				= 0x1a,
+	LMQPROP_SERVER_REFERENCE				= 0x1c,
+	LMQPROP_REASON_STRING					= 0x1f,
+	LMQPROP_RECEIVE_MAXIMUM					= 0x21,
+	LMQPROP_TOPIC_ALIAS_MAXIMUM				= 0x22,
+	LMQPROP_TOPIC_ALIAS					= 0x23,
+	LMQPROP_MAXIMUM_QOS					= 0x24,
+	LMQPROP_RETAIN_AVAILABLE				= 0x25,
+	LMQPROP_USER_PROPERTY					= 0x26,
+	LMQPROP_MAXIMUM_PACKET_SIZE				= 0x27,
+	LMQPROP_WILDCARD_SUBSCRIPTION_AVAIL			= 0x28,
+	LMQPROP_SUBSCRIPTION_IDENTIFIER_AVAIL			= 0x29,
+	LMQPROP_SHARED_SUBSCRIPTION_AVAIL			= 0x2a
+} lws_mqtt_property;
+
+int
+lws_read_mqtt(struct lws *wsi, unsigned char *buf, lws_filepos_t len);
+
+/* returns 0 if bd1 and bd2 are "the same", that includes empty, else nonzero */
+LWS_VISIBLE LWS_EXTERN int
+lws_mqtt_bindata_cmp(const lws_mqtt_str_t *bd1, const lws_mqtt_str_t *bd2);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mqtt_str_init(lws_mqtt_str_t *s, uint8_t *buf, uint16_t lim, char nf);
+
+LWS_VISIBLE LWS_EXTERN lws_mqtt_str_t *
+lws_mqtt_str_create(uint16_t lim);
+
+LWS_VISIBLE LWS_EXTERN lws_mqtt_str_t *
+lws_mqtt_str_create_init(uint8_t *buf, uint16_t len, uint16_t lim);
+
+LWS_VISIBLE LWS_EXTERN lws_mqtt_str_t *
+lws_mqtt_str_create_cstr_dup(const char *buf, uint16_t lim);
+
+LWS_VISIBLE LWS_EXTERN uint8_t *
+lws_mqtt_str_next(lws_mqtt_str_t *s, uint16_t *budget);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_mqtt_str_advance(lws_mqtt_str_t *s, int n);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_mqtt_str_free(lws_mqtt_str_t **s);
+
+
+/**
+ * lws_mqtt_client_send_publish() - lws_write a publish packet
+ *
+ * \param wsi: the mqtt child wsi
+ * \param pub: additional information on what we're publishing
+ * \param buf: payload to send
+ * \param len: length of data in buf
+ * \param final: flag indicating this is the last part
+ *
+ * Issues part of, or the whole of, a PUBLISH frame.  The first part of the
+ * frame contains the header, and uses the .qos and .payload_len parts of \p pub
+ * since MQTT requires the frame to specify the PUBLISH message length at the
+ * start.  The \p len paramter may be less than \p pub.payload_len, in which
+ * case subsequent calls with more payload are needed to complete the frame.
+ *
+ * Although the connection is stuck waiting for the remainder, in that it can't
+ * issue any other frames until the current one is completed, lws returns to the
+ * event loop normally and can continue the calls with additional payload even
+ * for huge frames as the data becomes available, consistent with timeout needs
+ * and latency to start any new frame (even, eg, related to ping / pong).
+ *
+ * If you're sending large frames, the OS will typically not allow the data to
+ * be sent all at once to kernel side.  So you should ideally cut the payload
+ * up into 1 or 2- mtu sized chunks and send that.
+ *
+ * Final should be set when you're calling with the last part of the payload.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_mqtt_client_send_publish(struct lws *wsi, lws_mqtt_publish_param_t *pub,
+			     const void *buf, uint32_t len, int final);
+
+/**
+ * lws_mqtt_client_send_subcribe() - lws_write a subscribe packet
+ *
+ * \param wsi: the mqtt child wsi
+ * \param sub: which topic(s) we want to subscribe to
+ *
+ * For topics other child streams have not already subscribed to, send a packet
+ * to the server asking to subscribe to them.  If all topics listed are already
+ * subscribed to be the shared network connection, just trigger the
+ * LWS_CALLBACK_MQTT_SUBSCRIBED callback as if a SUBACK had come.
+ *
+ * \p sub doesn't need to exist after the return from this function.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_mqtt_client_send_subcribe(struct lws *wsi, lws_mqtt_subscribe_param_t *sub);
+
+/**
+ * lws_mqtt_client_send_unsubcribe() - lws_write a unsubscribe packet
+ *
+ * \param wsi: the mqtt child wsi
+ * \param sub: which topic(s) we want to unsubscribe from
+ *
+ * For topics other child streams are not subscribed to, send a packet
+ * to the server asking to unsubscribe from them.  If all topics
+ * listed are already subscribed by other child streams on the shared
+ * network connection, just trigger the LWS_CALLBACK_MQTT_UNSUBSCRIBED
+ * callback as if a UNSUBACK had come.
+ *
+ * \p unsub doesn't need to exist after the return from this function.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_mqtt_client_send_unsubcribe(struct lws *wsi,
+				const lws_mqtt_subscribe_param_t *unsub);
+
+#endif /* _LWS_MQTT_H */

include/libwebsockets/lws-netdev.h

@@ -0,0 +1,283 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#define LWS_WIFI_MAX_SCAN_TRACK 16
+#define LWS_ETH_ALEN 6
+
+typedef uint8_t	lws_wifi_ch_t;
+typedef int8_t lws_wifi_rssi_t;
+struct lws_netdev_instance;
+
+typedef enum {
+	LWSNDTYP_UNKNOWN,
+	LWSNDTYP_WIFI,
+	LWSNDTYP_ETH,
+} lws_netdev_type_t;
+
+/*
+ * Base class for netdev configuration
+ */
+
+typedef struct lws_netdev_config {
+	void				*plat_config;
+} lws_netdev_config_t;
+
+/*
+ * Const Logical generic network interface ops
+ */
+
+typedef struct lws_netdev_ops {
+	struct lws_netdev_instance * (*create)(struct lws_context *ctx,
+					       const struct lws_netdev_ops *ops,
+					       const char *name, void *platinfo);
+	int (*configure)(struct lws_netdev_instance *nd,
+			 lws_netdev_config_t *config);
+	int (*up)(struct lws_netdev_instance *nd);
+	int (*down)(struct lws_netdev_instance *nd);
+	int (*event)(struct lws_netdev_instance *nd, lws_usec_t timestamp,
+		     void *buf, size_t len);
+	/**< these are SMD events coming from lws event loop thread context */
+	void (*destroy)(struct lws_netdev_instance **pnd);
+	int (*connect)(struct lws_netdev_instance *wnd, const char *ssid,
+			    const char *passphrase, uint8_t *bssid);
+	void (*scan)(struct lws_netdev_instance *nd);
+} lws_netdev_ops_t;
+
+/*
+ * Network devices on this platform
+ *
+ * We also hold a list of all known network credentials (when they are needed
+ * because there is a network interface without anything to connect to) and
+ * the lws_settings instance they are stored in
+ */
+
+typedef struct lws_netdevs {
+	lws_dll2_owner_t		owner;
+	/**< list of netdevs / lws_netdev_instance_t -based objects */
+
+	lws_dll2_owner_t		owner_creds;
+	/**< list of known credentials */
+	struct lwsac			*ac_creds;
+	/**< lwsac holding retreived credentials settings, or NULL */
+	lws_settings_instance_t		*si;
+
+	lws_sockaddr46			sa46_dns_resolver;
+
+	uint8_t				refcount_creds;
+	/**< when there are multiple netdevs, must refcount creds in mem */
+} lws_netdevs_t;
+
+/*
+ * Base class for an allocated instantiated derived object using lws_netdev_ops,
+ * ie, a specific ethernet device
+ */
+
+typedef struct lws_netdev_instance {
+	const char			*name;
+	const lws_netdev_ops_t		*ops;
+	void				*platinfo;
+	lws_dll2_t			list;
+	uint8_t				mac[LWS_ETH_ALEN];
+	uint8_t				type; /* lws_netdev_type_t */
+} lws_netdev_instance_t;
+
+enum {
+	LNDIW_ALG_OPEN,
+	LNDIW_ALG_WPA2,
+
+	LNDIW_MODE_STA			= (1 << 0),
+	LNDIW_MODE_AP			= (1 << 1),
+	LNDIW_UP			= (1 << 7),
+
+	LNDIW_ACQ_IPv4			= (1 << 0),
+	LNDIW_ACQ_IPv6			= (1 << 1),
+};
+
+/*
+ * Group AP / Station State
+ */
+
+typedef enum {
+	LWSNDVWIFI_STATE_INITIAL,
+		/*
+		 * We should gratuitously try whatever last worked for us, then
+		 * if that fails, worry about the rest of the logic
+		 */
+	LWSNDVWIFI_STATE_SCAN,
+		/*
+		 * Unconnected, scanning: AP known in one of the config slots ->
+		 * configure it, start timeout + LWSNDVWIFI_STATE_STAT, if no AP
+		 * already up in same group with lower MAC, after a random
+		 * period start up our AP (LWSNDVWIFI_STATE_AP)
+		 */
+	LWSNDVWIFI_STATE_AP,
+		/* Trying to be the group AP... periodically do a scan
+		 * LWSNDVWIFI_STATE_AP_SCAN, faster and then slower
+       		 */
+	LWSNDVWIFI_STATE_AP_SCAN,
+		/*
+		 * doing a scan while trying to be the group AP... if we see a
+		 * lower MAC being the AP for the same group AP, abandon being
+		 * an AP and join that AP as a station
+		 */
+	LWSNDVWIFI_STATE_STAT_GRP_AP,
+		/*
+		 * We have decided to join another group member who is being the
+		 * AP, as its MAC is lower than ours.  This is a stable state,
+		 * but we still do periodic scans
+		 * LWSNDVWIFI_STATE_STAT_GRP_AP_SCAN and will always prefer an
+		 * AP configured in a slot.
+		 */
+	LWSNDVWIFI_STATE_STAT_GRP_AP_SCAN,
+		/*
+		 * We have joined a group member who is doing the AP job... we
+		 * want to check every now and then if a configured AP has
+		 * appeared that we should better use instead.  Otherwise stay
+		 * in LWSNDVWIFI_STATE_STAT_GRP_AP
+		 */
+	LWSNDVWIFI_STATE_STAT,
+		/*
+		 * trying to connect to another non-group AP. If we don't get an
+		 * IP within a timeout and retries, mark it as unusable it and go back
+		 */
+	LWSNDVWIFI_STATE_STAT_HAPPY,
+} lws_netdev_wifi_state_t;
+
+/*
+ * Generic WIFI credentials
+ */
+
+typedef struct lws_wifi_creds {
+	lws_dll2_t			list;
+
+	uint8_t				bssid[LWS_ETH_ALEN];
+	char				passphrase[64];
+	char				ssid[33];
+	uint8_t				alg;
+} lws_wifi_creds_t;
+
+/*
+ * Generic WIFI Network Device Instance
+ */
+
+typedef struct lws_netdev_instance_wifi {
+	lws_netdev_instance_t		inst;
+	lws_dll2_owner_t		scan; /* sorted scan results */
+	lws_sorted_usec_list_t		sul_scan;
+
+	lws_wifi_creds_t		*ap_cred;
+	const char			*ap_ip;
+
+	const char			*sta_ads;
+
+	char				current_attempt_ssid[33];
+	uint8_t				current_attempt_bssid[LWS_ETH_ALEN];
+
+	uint8_t				flags;
+	uint8_t				state; /* lws_netdev_wifi_state_t */
+} lws_netdev_instance_wifi_t;
+
+/*
+ * Logical scan results sorted list item
+ */
+
+typedef struct lws_wifi_sta {
+	lws_dll2_t			list;
+
+	uint32_t			last_seen; /* unix time */
+	uint32_t			last_tried; /* unix time */
+
+	uint8_t				bssid[LWS_ETH_ALEN];
+	char				*ssid; /* points to overallocation */
+	uint8_t				ssid_len;
+	lws_wifi_ch_t			ch;
+	lws_wifi_rssi_t			rssi[8];
+	int16_t				rssi_avg;
+	uint8_t				authmode;
+
+	uint8_t				rssi_count;
+	uint8_t				rssi_next;
+
+	/* ssid overallocated afterwards */
+} lws_wifi_sta_t;
+
+#define rssi_averaged(_x) (_x->rssi_count ? \
+		((int)_x->rssi_avg / (int)_x->rssi_count) : \
+			-200)
+
+LWS_VISIBLE LWS_EXTERN lws_netdevs_t *
+lws_netdevs_from_ctx(struct lws_context *ctx);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_credentials_settings_set(lws_netdevs_t *nds);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_credentials_settings_get(lws_netdevs_t *nds);
+
+LWS_VISIBLE LWS_EXTERN struct lws_netdev_instance *
+lws_netdev_wifi_create_plat(struct lws_context *ctx,
+			    const lws_netdev_ops_t *ops, const char *name,
+			    void *platinfo);
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_wifi_configure_plat(struct lws_netdev_instance *nd,
+			       lws_netdev_config_t *config);
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_wifi_event_plat(struct lws_netdev_instance *nd, lws_usec_t timestamp,
+			   void *buf, size_t len);
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_wifi_up_plat(struct lws_netdev_instance *nd);
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_wifi_down_plat(struct lws_netdev_instance *nd);
+LWS_VISIBLE LWS_EXTERN void
+lws_netdev_wifi_destroy_plat(struct lws_netdev_instance **pnd);
+LWS_VISIBLE LWS_EXTERN void
+lws_netdev_wifi_scan_plat(lws_netdev_instance_t *nd);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_wifi_connect_plat(lws_netdev_instance_t *wnd, const char *ssid,
+			     const char *passphrase, uint8_t *bssid);
+
+LWS_VISIBLE LWS_EXTERN lws_netdev_instance_t *
+lws_netdev_find(lws_netdevs_t *netdevs, const char *ifname);
+
+#define lws_netdev_wifi_plat_ops \
+	.create				= lws_netdev_wifi_create_plat, \
+	.configure			= lws_netdev_wifi_configure_plat, \
+	.event				= lws_netdev_wifi_event_plat, \
+	.up				= lws_netdev_wifi_up_plat, \
+	.down				= lws_netdev_wifi_down_plat, \
+	.connect			= lws_netdev_wifi_connect_plat, \
+	.scan				= lws_netdev_wifi_scan_plat, \
+	.destroy			= lws_netdev_wifi_destroy_plat
+
+/*
+ * This is for plat / OS level init that is necessary to be able to use
+ * networking or wifi at all, without mentioning any specific device
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_plat_init(void);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_netdev_plat_wifi_init(void);

include/libwebsockets/lws-network-helper.h

@@ -0,0 +1,249 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup net Network related helper APIs
+ * ##Network related helper APIs
+ *
+ * These wrap miscellaneous useful network-related functions
+ */
+///@{
+
+#if defined(LWS_ESP_PLATFORM)
+#include <lwip/sockets.h>
+#endif
+
+/* cope with large amounts of route information */
+typedef uint16_t lws_route_uidx_t;
+
+typedef struct lws_dns_score {
+	uint8_t precedence;
+	uint8_t label;
+} lws_dns_score_t;
+
+/*
+ * This represents an entry in the system routing table
+ */
+
+typedef struct lws_route {
+	lws_dll2_t		list;
+
+	lws_sockaddr46		src;
+	lws_sockaddr46		dest;
+	lws_sockaddr46		gateway;
+
+	struct lws_route	*source; /* when used as lws_dns_sort_t */
+	lws_dns_score_t		score; /* when used as lws_dns_sort_t */
+
+	int			if_idx;
+	int			priority;
+	int			ifa_flags; /* if source_ads */
+
+	lws_route_uidx_t	uidx; /* unique index for this route */
+
+	uint8_t			proto;
+	uint8_t			dest_len;
+	uint8_t			src_len;
+	uint8_t			scope; /* if source_ads */
+	uint8_t			af; /* if source_ads */
+
+	uint8_t			source_ads:1;
+} lws_route_t;
+
+/*
+ * We reuse the route object as the dns sort granule, so there's only one
+ * struct needs to know all the gnarly ipv6 details
+ */
+
+typedef lws_route_t lws_dns_sort_t;
+
+/**
+ * lws_canonical_hostname() - returns this host's hostname
+ *
+ * This is typically used by client code to fill in the host parameter
+ * when making a client connection.  You can only call it after the context
+ * has been created.
+ *
+ * \param context:	Websocket context
+ */
+LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
+lws_canonical_hostname(struct lws_context *context);
+
+/**
+ * lws_get_peer_addresses() - Get client address information
+ * \param wsi:	Local struct lws associated with
+ * \param fd:		Connection socket descriptor
+ * \param name:	Buffer to take client address name
+ * \param name_len:	Length of client address name buffer
+ * \param rip:	Buffer to take client address IP dotted quad
+ * \param rip_len:	Length of client address IP buffer
+ *
+ *	This function fills in name and rip with the name and IP of
+ *	the client connected with socket descriptor fd.  Names may be
+ *	truncated if there is not enough room.  If either cannot be
+ *	determined, they will be returned as valid zero-length strings.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_get_peer_addresses(struct lws *wsi, lws_sockfd_type fd, char *name,
+		       int name_len, char *rip, int rip_len);
+
+/**
+ * lws_get_peer_simple() - Get client address information without RDNS
+ *
+ * \param wsi:	Local struct lws associated with
+ * \param name:	Buffer to take client address name
+ * \param namelen:	Length of client address name buffer
+ *
+ * This provides a 123.123.123.123 type IP address in name from the
+ * peer that has connected to wsi
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_get_peer_simple(struct lws *wsi, char *name, size_t namelen);
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_get_peer_simple_fd(lws_sockfd_type fd, char *name, size_t namelen);
+
+#define LWS_ITOSA_USABLE	0
+#define LWS_ITOSA_NOT_EXIST	-1
+#define LWS_ITOSA_NOT_USABLE	-2
+#define LWS_ITOSA_BUSY		-3 /* only returned by lws_socket_bind() on
+					EADDRINUSE */
+
+#if !defined(LWS_PLAT_FREERTOS) && !defined(LWS_PLAT_OPTEE)
+/**
+ * lws_interface_to_sa() - Convert interface name or IP to sockaddr struct
+ *
+ * \param ipv6:		Allow IPV6 addresses
+ * \param ifname:	Interface name or IP
+ * \param addr:		struct sockaddr_in * to be written
+ * \param addrlen:	Length of addr
+ *
+ * This converts a textual network interface name to a sockaddr usable by
+ * other network functions.
+ *
+ * If the network interface doesn't exist, it will return LWS_ITOSA_NOT_EXIST.
+ *
+ * If the network interface is not usable, eg ethernet cable is removed, it
+ * may logically exist but not have any IP address.  As such it will return
+ * LWS_ITOSA_NOT_USABLE.
+ *
+ * If the network interface exists and is usable, it will return
+ * LWS_ITOSA_USABLE.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_interface_to_sa(int ipv6, const char *ifname, struct sockaddr_in *addr,
+		    size_t addrlen);
+#endif
+
+/**
+ * lws_sa46_compare_ads() - checks if two sa46 have the same address
+ *
+ * \param sa46a: first
+ * \param sa46b: second
+ *
+ * Returns 0 if the address family is INET or INET6 and the address is the same,
+ * or if the AF is the same but not INET or INET6, otherwise nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sa46_compare_ads(const lws_sockaddr46 *sa46a, const lws_sockaddr46 *sa46b);
+
+/**
+ * lws_sa46_on_net() - checks if an sa46 is on the subnet represented by another
+ *
+ * \param sa46a: first
+ * \param sa46_net: network
+ * \param net_len: length of network non-mask
+ *
+ * Returns 0 if sa46a belongs on network sa46_net/net_len
+ *
+ * If there is an ipv4 / v6 mismatch between the ip and the net, the ipv4
+ * address is promoted to ::ffff:x.x.x.x before the comparison.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sa46_on_net(const lws_sockaddr46 *sa46a, const lws_sockaddr46 *sa46_net,
+			int net_len);
+
+/*
+ * lws_parse_numeric_address() - converts numeric ipv4 or ipv6 to byte address
+ *
+ * \param ads: the numeric ipv4 or ipv6 address string
+ * \param result: result array
+ * \param max_len: max length of result array
+ *
+ * Converts a 1.2.3.4 or 2001:abcd:123:: or ::ffff:1.2.3.4 formatted numeric
+ * address into an array of network ordered byte address elements.
+ *
+ * Returns < 0 on error, else length of result set, either 4 or 16 for ipv4 /
+ * ipv6.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_parse_numeric_address(const char *ads, uint8_t *result, size_t max_len);
+
+/*
+ * lws_sa46_parse_numeric_address() - converts numeric ipv4 or ipv6 to sa46
+ *
+ * \param ads: the numeric ipv4 or ipv6 address string
+ * \param sa46: pointer to sa46 to set
+ *
+ * Converts a 1.2.3.4 or 2001:abcd:123:: or ::ffff:1.2.3.4 formatted numeric
+ * address into an sa46, a union of sockaddr_in or sockaddr_in6 depending on
+ * what kind of address was found.  sa46->sa4.sin_fmaily will be AF_INET if
+ * ipv4, or AF_INET6 if ipv6.
+ *
+ * Returns 0 if the sa46 was set, else < 0 on error.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sa46_parse_numeric_address(const char *ads, lws_sockaddr46 *sa46);
+
+/**
+ * lws_write_numeric_address() - convert network byte order ads to text
+ *
+ * \param ads: network byte order address array
+ * \param size: number of bytes valid in ads
+ * \param buf: result buffer to take text format
+ * \param len: max size of text buffer
+ *
+ * Converts an array of network-ordered byte address elements to a textual
+ * representation of the numeric address, like "1.2.3.4" or "::1".  Returns the
+ * number of chars written into buf, else < 0.  ipv6 only supported with
+ * LWS_IPV6=1 at cmake.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_write_numeric_address(const uint8_t *ads, int size, char *buf, size_t len);
+
+/**
+ * lws_sa46_write_numeric_address() - convert sa46 ads to textual numeric ads
+ *
+ * \param sa46: the sa46 whose address to show
+ * \param buf: result buffer to take text format
+ * \param len: max size of text buffer
+ *
+ * Converts the ipv4 or ipv6 address in an lws_sockaddr46 to a textual
+ * representation of the numeric address, like "1.2.3.4" or "::1".  Returns the
+ * number of chars written into buf, else < 0.  ipv6 only supported with
+ * LWS_IPV6=1 at cmake.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sa46_write_numeric_address(lws_sockaddr46 *sa46, char *buf, size_t len);
+
+///@}

include/libwebsockets/lws-optee.h

@@ -0,0 +1,77 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#ifndef __LWS_OPTEE_H
+#define __LWS_OPTEE_H
+
+/* 128-bit IP6 address */
+struct in6_addr {
+	union {
+		uint8_t	  u6_addr8[16];
+		uint16_t  u6_addr16[8];
+		uint32_t  u6_addr32[4];
+	};
+};
+
+#define		_SS_MAXSIZE	128U
+#define		_SS_ALIGNSIZE	(sizeof(int64_t))
+#define		_SS_PAD1SIZE	(_SS_ALIGNSIZE - \
+			sizeof(sa_family_t))
+#define		_SS_PAD2SIZE	(_SS_MAXSIZE - \
+			sizeof(sa_family_t) - _SS_PAD1SIZE - _SS_ALIGNSIZE)
+
+struct sockaddr_storage {
+	sa_family_t	ss_family;	/* address family */
+	char		__ss_pad1[_SS_PAD1SIZE];
+	int64_t		__ss_align;	/* force desired struct alignment */
+	char		__ss_pad2[_SS_PAD2SIZE];
+};
+
+#define __SOCK_SIZE__	16		/* sizeof(struct sockaddr)      */
+struct sockaddr {
+	sa_family_t	sa_family;	/* address family */
+	uint8_t		sa_data[__SOCK_SIZE__	/* address value */
+				- sizeof(sa_family_t)];
+};
+
+/* 16 bytes */
+struct sockaddr_in {
+	sa_family_t	sin_family;
+	in_port_t	sin_port;
+	struct in_addr	sin_addr;
+	uint8_t		sin_zero[__SOCK_SIZE__	/* padding until 16 bytes */
+				- sizeof(sa_family_t)
+				- sizeof(in_port_t)
+				- sizeof(struct  in_addr)];
+};
+
+struct sockaddr_in6 {
+	sa_family_t	sin6_family;	/* AF_INET6 */
+	in_port_t	sin6_port;	/* Transport layer port # */
+	uint32_t	sin6_flowinfo;	/* IP6 flow information */
+	struct in6_addr	sin6_addr;	/* IP6 address */
+	uint32_t	sin6_scope_id;	/* scope zone index */
+};
+
+#endif /* __LWS_OPTEE_H */

include/libwebsockets/lws-protocols-plugins.h

@@ -0,0 +1,383 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup Protocols-and-Plugins Protocols and Plugins
+ * \ingroup lwsapi
+ *
+ * ##Protocol and protocol plugin -related apis
+ *
+ * Protocols bind ws protocol names to a custom callback specific to that
+ * protocol implementaion.
+ *
+ * A list of protocols can be passed in at context creation time, but it is
+ * also legal to leave that NULL and add the protocols and their callback code
+ * using plugins.
+ *
+ * Plugins are much preferable compared to cut and pasting code into an
+ * application each time, since they can be used standalone.
+ */
+///@{
+/** struct lws_protocols -	List of protocols and handlers client or server
+ *					supports. */
+
+struct lws_protocols {
+	const char *name;
+	/**< Protocol name that must match the one given in the client
+	 * Javascript new WebSocket(url, 'protocol') name. */
+	lws_callback_function *callback;
+	/**< The service callback used for this protocol.  It allows the
+	 * service action for an entire protocol to be encapsulated in
+	 * the protocol-specific callback */
+	size_t per_session_data_size;
+	/**< Each new connection using this protocol gets
+	 * this much memory allocated on connection establishment and
+	 * freed on connection takedown.  A pointer to this per-connection
+	 * allocation is passed into the callback in the 'user' parameter */
+	size_t rx_buffer_size;
+	/**< lws allocates this much space for rx data and informs callback
+	 * when something came.  Due to rx flow control, the callback may not
+	 * be able to consume it all without having to return to the event
+	 * loop.  That is supported in lws.
+	 *
+	 * If .tx_packet_size is 0, this also controls how much may be sent at
+	 * once for backwards compatibility.
+	 */
+	unsigned int id;
+	/**< ignored by lws, but useful to contain user information bound
+	 * to the selected protocol.  For example if this protocol was
+	 * called "myprotocol-v2", you might set id to 2, and the user
+	 * code that acts differently according to the version can do so by
+	 * switch (wsi->a.protocol->id), user code might use some bits as
+	 * capability flags based on selected protocol version, etc. */
+	void *user; /**< ignored by lws, but user code can pass a pointer
+			here it can later access from the protocol callback */
+	size_t tx_packet_size;
+	/**< 0 indicates restrict send() size to .rx_buffer_size for backwards-
+	 * compatibility.
+	 * If greater than zero, a single send() is restricted to this amount
+	 * and any remainder is buffered by lws and sent afterwards also in
+	 * these size chunks.  Since that is expensive, it's preferable
+	 * to restrict one fragment you are trying to send to match this
+	 * size.
+	 */
+
+	/* Add new things just above here ---^
+	 * This is part of the ABI, don't needlessly break compatibility */
+};
+
+#define LWS_PROTOCOL_LIST_TERM { NULL, NULL, 0, 0, 0, NULL, 0 }
+
+/**
+ * lws_vhost_name_to_protocol() - get vhost's protocol object from its name
+ *
+ * \param vh: vhost to search
+ * \param name: protocol name
+ *
+ * Returns NULL or a pointer to the vhost's protocol of the requested name
+ */
+LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
+lws_vhost_name_to_protocol(struct lws_vhost *vh, const char *name);
+
+/**
+ * lws_get_protocol() - Returns a protocol pointer from a websocket
+ *				  connection.
+ * \param wsi:	pointer to struct websocket you want to know the protocol of
+ *
+ *
+ *	Some apis can act on all live connections of a given protocol,
+ *	this is how you can get a pointer to the active protocol if needed.
+ */
+LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
+lws_get_protocol(struct lws *wsi);
+
+/** lws_protocol_get() -  deprecated: use lws_get_protocol */
+LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
+lws_protocol_get(struct lws *wsi) LWS_WARN_DEPRECATED;
+
+/**
+ * lws_protocol_vh_priv_zalloc() - Allocate and zero down a protocol's per-vhost
+ *				   storage
+ * \param vhost:	vhost the instance is related to
+ * \param prot:		protocol the instance is related to
+ * \param size:		bytes to allocate
+ *
+ * Protocols often find it useful to allocate a per-vhost struct, this is a
+ * helper to be called in the per-vhost init LWS_CALLBACK_PROTOCOL_INIT
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_protocol_vh_priv_zalloc(struct lws_vhost *vhost,
+			    const struct lws_protocols *prot, int size);
+
+/**
+ * lws_protocol_vh_priv_get() - retreive a protocol's per-vhost storage
+ *
+ * \param vhost:	vhost the instance is related to
+ * \param prot:		protocol the instance is related to
+ *
+ * Recover a pointer to the allocated per-vhost storage for the protocol created
+ * by lws_protocol_vh_priv_zalloc() earlier
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_protocol_vh_priv_get(struct lws_vhost *vhost,
+			 const struct lws_protocols *prot);
+
+/**
+ * lws_vhd_find_by_pvo() - find a partner vhd
+ *
+ *  \param cx: the lws_context
+ *  \param protname: the name of the lws_protocol the vhd belongs to
+ *  \param pvo_name: the name of a pvo that must exist bound to the vhd
+ *  \param pvo_value: the required value of the named pvo
+ *
+ * This allows architectures with multiple protocols bound together to
+ * cleanly discover partner protocol instances even on completely
+ * different vhosts.  For example, a proxy may consist of two protocols
+ * listening on different vhosts, and there may be multiple instances
+ * of the proxy in the same process.  It's desirable that each side of
+ * the proxy is an independent protocol that can be freely bound to any
+ * vhost, eg, allowing Unix Domain to tls / h2 proxying, or each side
+ * bound to different network interfaces for localhost-only visibility
+ * on one side, using existing vhost management.
+ *
+ * That leaves the problem that the two sides have to find each other
+ * and bind at runtime.  This api allows each side to specify the
+ * protocol name, and a common pvo name and pvo value that indicates
+ * the two sides belong together, and search through all the instantiated
+ * vhost-protocols looking for a match.  If found, the private allocation
+ * (aka "vhd" of the match is returned).  NULL is returned on no match.
+ *
+ * Since this can only succeed when called by the last of the two
+ * protocols to be instantiated, both sides should call it and handle
+ * NULL gracefully, since it may mean that they were first and their
+ * partner vhsot-protocol has not been instantiated yet.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_vhd_find_by_pvo(struct lws_context *cx, const char *protname,
+		    const char *pvo_name, const char *pvo_value);
+
+
+/**
+ * lws_adjust_protocol_psds - change a vhost protocol's per session data size
+ *
+ * \param wsi: a connection with the protocol to change
+ * \param new_size: the new size of the per session data size for the protocol
+ *
+ * Returns user_space for the wsi, after allocating
+ *
+ * This should not be used except to initalize a vhost protocol's per session
+ * data size one time, before any connections are accepted.
+ *
+ * Sometimes the protocol wraps another protocol and needs to discover and set
+ * its per session data size at runtime.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_adjust_protocol_psds(struct lws *wsi, size_t new_size);
+
+/**
+ * lws_finalize_startup() - drop initial process privileges
+ *
+ * \param context:	lws context
+ *
+ * This is called after the end of the vhost protocol initializations, but
+ * you may choose to call it earlier
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_finalize_startup(struct lws_context *context);
+
+/**
+ * lws_pvo_search() - helper to find a named pvo in a linked-list
+ *
+ * \param pvo:	the first pvo in the linked-list
+ * \param name: the name of the pvo to return if found
+ *
+ * Returns NULL, or a pointer to the name pvo in the linked-list
+ */
+LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_options *
+lws_pvo_search(const struct lws_protocol_vhost_options *pvo, const char *name);
+
+/**
+ * lws_pvo_get_str() - retreive a string pvo value
+ *
+ * \param in:	the first pvo in the linked-list
+ * \param name: the name of the pvo to return if found
+ * \param result: pointer to a const char * to get the result if any
+ *
+ * Returns 0 if found and *result set, or nonzero if not found
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_pvo_get_str(void *in, const char *name, const char **result);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_protocol_init(struct lws_context *context);
+
+#define LWS_PLUGIN_API_MAGIC 191
+
+/*
+ * Abstract plugin header for any kind of plugin class, always at top of
+ * actual class plugin export type.
+ *
+ * The export type object must be exported with the same name as the plugin
+ * file, eg, libmyplugin.so must export a const one of these as the symbol
+ * "myplugin".
+ *
+ * That is the only expected export from the plugin.
+ */
+
+typedef struct lws_plugin_header {
+	const char *name;
+	const char *_class;
+	const char *lws_build_hash; /* set to LWS_BUILD_HASH */
+
+	unsigned int api_magic;
+	/* set to LWS_PLUGIN_API_MAGIC at plugin build time */
+
+	/* plugin-class specific superclass data follows */
+} lws_plugin_header_t;
+
+/*
+ * "lws_protocol_plugin" class export, for lws_protocol implementations done
+ * as plugins
+ */
+typedef struct lws_plugin_protocol {
+	lws_plugin_header_t hdr;
+
+	const struct lws_protocols *protocols; /**< array of supported protocols provided by plugin */
+	const struct lws_extension *extensions; /**< array of extensions provided by plugin */
+	int count_protocols; /**< how many protocols */
+	int count_extensions; /**< how many extensions */
+} lws_plugin_protocol_t;
+
+
+/*
+ * This is the dynamic, runtime created part of the plugin instantiation.
+ * These are kept in a linked-list and destroyed with the context.
+ */
+
+struct lws_plugin {
+	struct lws_plugin *list; /**< linked list */
+
+	const lws_plugin_header_t *hdr;
+
+	union {
+#if defined(LWS_WITH_LIBUV) && defined(UV_ERRNO_MAP)
+#if (UV_VERSION_MAJOR > 0)
+		uv_lib_t lib; /**< shared library pointer */
+#endif
+#endif
+		void *l; /**<  */
+	} u;
+};
+
+/*
+ * Event lib library plugin type (when LWS_WITH_EVLIB_PLUGINS)
+ * Public so new event libs can equally be supported outside lws itself
+ */
+
+typedef struct lws_plugin_evlib {
+	lws_plugin_header_t hdr;
+	const struct lws_event_loop_ops *ops;
+} lws_plugin_evlib_t;
+
+typedef int (*each_plugin_cb_t)(struct lws_plugin *p, void *user);
+
+/**
+ * lws_plugins_init() - dynamically load plugins of matching class from dirs
+ *
+ * \param pplugin:	pointer to linked-list for this kind of plugin
+ * \param d: array of directory paths to look in
+ * \param _class: class string that plugin must declare
+ * \param filter: NULL, or a string that must appear after the third char of the plugin filename
+ * \param each: NULL, or each_plugin_cb_t callback for each instantiated plugin
+ * \param each_user: pointer passed to each callback
+ *
+ * Allows you to instantiate a class of plugins to a specified linked-list.
+ * The each callback allows you to init each inistantiated callback and pass a
+ * pointer each_user to it.
+ *
+ * To take down the plugins, pass a pointer to the linked-list head to
+ * lws_plugins_destroy.
+ *
+ * This is used for lws protocol plugins but you can define your own plugin
+ * class name like "mypluginclass", declare it in your plugin headers, and load
+ * your own plugins to your own list using this api the same way.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_plugins_init(struct lws_plugin **pplugin, const char * const *d,
+		 const char *_class, const char *filter,
+		 each_plugin_cb_t each, void *each_user);
+
+/**
+ * lws_plugins_destroy() - dynamically unload list of plugins
+ *
+ * \param pplugin:	pointer to linked-list for this kind of plugin
+ * \param each: NULL, or each_plugin_cb_t callback for each instantiated plugin
+ * \param each_user: pointer passed to each callback
+ *
+ * Allows you to destroy a class of plugins from a specified linked-list
+ * created by a call to lws_plugins_init().
+ *
+ * The each callback allows you to deinit each inistantiated callback and pass a
+ * pointer each_user to it, just before its footprint is destroyed.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_plugins_destroy(struct lws_plugin **pplugin, each_plugin_cb_t each,
+		    void *each_user);
+
+#if defined(LWS_WITH_PLUGINS_BUILTIN)
+
+/* provide exports for builtin plugin protocols */
+
+extern const struct lws_protocols post_demo_protocols[1];
+extern const struct lws_protocols lws_raw_proxy_protocols[1];
+extern const struct lws_protocols lws_status_protocols[1];
+extern const struct lws_protocols lws_mirror_protocols[1];
+extern const struct lws_protocols lws_ssh_base_protocols[2];
+extern const struct lws_protocols post_demo_protocols[1];
+extern const struct lws_protocols dumb_increment_protocols[1];
+extern const struct lws_protocols deaddrop_protocols[1];
+extern const struct lws_protocols lws_raw_test_protocols[1];
+extern const struct lws_protocols lws_sshd_demo_protocols[1];
+extern const struct lws_protocols lws_acme_client_protocols[1];
+extern const struct lws_protocols client_loopback_test_protocols[1];
+extern const struct lws_protocols fulltext_demo_protocols[1];
+extern const struct lws_protocols lws_openmetrics_export_protocols[
+#if defined(LWS_WITH_SERVER) && defined(LWS_WITH_CLIENT) && defined(LWS_ROLE_WS)
+	4
+#else
+#if defined(LWS_WITH_SERVER)
+	3
+#else
+	1
+#endif
+#endif
+	];
+
+#define LWSOMPROIDX_DIRECT_HTTP_SERVER		0
+#define LWSOMPROIDX_PROX_HTTP_SERVER		1
+#define LWSOMPROIDX_PROX_WS_SERVER		2
+#define LWSOMPROIDX_PROX_WS_CLIENT		3
+
+#endif
+
+///@}

include/libwebsockets/lws-purify.h

@@ -0,0 +1,105 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup pur Sanitize / purify SQL and JSON helpers
+ *
+ * ##Sanitize / purify SQL and JSON helpers
+ *
+ * APIs for escaping untrusted JSON and SQL safely before use
+ */
+//@{
+
+/**
+ * lws_sql_purify() - like strncpy but with escaping for sql quotes
+ *
+ * \param escaped: output buffer
+ * \param string: input buffer ('/0' terminated)
+ * \param len: output buffer max length
+ *
+ * Because escaping expands the output string, it's not
+ * possible to do it in-place, ie, with escaped == string
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_sql_purify(char *escaped, const char *string, size_t len);
+
+/**
+ * lws_sql_purify_len() - return length of purified version of input string
+ *
+ * \param string: input buffer ('/0' terminated)
+ *
+ * Calculates any character escaping without writing it anywhere and returns the
+ * calculated length of the purified string.
+ */
+int
+lws_sql_purify_len(const char *p);
+
+/**
+ * lws_json_purify() - like strncpy but with escaping for json chars
+ *
+ * \param escaped: output buffer
+ * \param string: input buffer ('/0' terminated)
+ * \param len: output buffer max length
+ * \param in_used: number of bytes of string we could escape in len
+ *
+ * Because escaping expands the output string, it's not
+ * possible to do it in-place, ie, with escaped == string
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_json_purify(char *escaped, const char *string, int len, int *in_used);
+
+/**
+ * lws_json_purify_len() - find out the escaped length of a string
+ *
+ * \param string: input buffer ('/0' terminated)
+ *
+ * JSON may have to expand escapes by up to 6x the original depending on what
+ * it is.  This doesn't actually do the escaping but goes through the motions
+ * and computes the length of the escaped string.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_json_purify_len(const char *string);
+
+/**
+ * lws_filename_purify_inplace() - replace scary filename chars with underscore
+ *
+ * \param filename: filename to be purified
+ *
+ * Replace scary characters in the filename (it should not be a path)
+ * with underscore, so it's safe to use.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_filename_purify_inplace(char *filename);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_plat_write_cert(struct lws_vhost *vhost, int is_key, int fd, void *buf,
+			size_t len);
+LWS_VISIBLE LWS_EXTERN int
+lws_plat_write_file(const char *filename, void *buf, size_t len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_plat_read_file(const char *filename, void *buf, size_t len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_plat_recommended_rsa_bits(void);
+///@}

include/libwebsockets/lws-pwm.h

@@ -0,0 +1,67 @@
+/*
+ * Generic PWM controller ops
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+typedef struct lws_pwm_map {
+	_lws_plat_gpio_t		gpio;
+	uint8_t				index;
+	uint8_t				active_level;
+} lws_pwm_map_t;
+
+typedef struct lws_pwm_ops {
+	int (*init)(const struct lws_pwm_ops *lo);
+	void (*intensity)(const struct lws_pwm_ops *lo, _lws_plat_gpio_t gpio,
+			  lws_led_intensity_t inten);
+	const lws_pwm_map_t		*pwm_map;
+	uint8_t				count_pwm_map;
+} lws_pwm_ops_t;
+
+LWS_VISIBLE LWS_EXTERN int
+lws_pwm_plat_init(const struct lws_pwm_ops *lo);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_pwm_plat_intensity(const struct lws_pwm_ops *lo, _lws_plat_gpio_t gpio,
+		       lws_led_intensity_t inten);
+
+#define lws_pwm_plat_ops \
+		.init			= lws_pwm_plat_init, \
+		.intensity		= lws_pwm_plat_intensity
+
+/*
+ * May be useful for making your own transitions or sequences
+ */
+
+LWS_VISIBLE LWS_EXTERN lws_led_intensity_t
+lws_led_func_linear(lws_led_seq_phase_t n);
+LWS_VISIBLE LWS_EXTERN lws_led_intensity_t
+lws_led_func_sine(lws_led_seq_phase_t n);
+
+/* canned sequences that can work out of the box */
+
+extern const lws_led_sequence_def_t lws_pwmseq_sine_endless_slow,
+				    lws_pwmseq_sine_endless_fast,
+				    lws_pwmseq_linear_wipe,
+				    lws_pwmseq_sine_up, lws_pwmseq_sine_down,
+				    lws_pwmseq_static_on,
+				    lws_pwmseq_static_half,
+				    lws_pwmseq_static_off;

include/libwebsockets/lws-retry.h

@@ -0,0 +1,95 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+typedef struct lws_retry_bo {
+	const uint32_t	*retry_ms_table;	   /* base delay in ms */
+	uint16_t	retry_ms_table_count;      /* entries in table */
+	uint16_t	conceal_count;		   /* max retries to conceal */
+	uint16_t	secs_since_valid_ping;     /* idle before PING issued */
+	uint16_t	secs_since_valid_hangup;   /* idle before hangup conn */
+	uint8_t		jitter_percent;		/* % additional random jitter */
+} lws_retry_bo_t;
+
+#define LWS_RETRY_CONCEAL_ALWAYS (0xffff)
+
+/**
+ * lws_retry_get_delay_ms() - get next delay from backoff table
+ *
+ * \param lws_context: the lws context (used for getting random)
+ * \param retry: the retry backoff table we are using, or NULL for default
+ * \param ctry: pointer to the try counter
+ * \param conceal: pointer to flag set to nonzero if the try should be concealed
+ *			in terms of creating an error
+ *
+ * Increments *\p try and retruns the number of ms that should elapse before the
+ * next connection retry, according to the backoff table \p retry. *\p conceal is
+ * set if the number of tries is less than the backoff table conceal_count, or
+ * is zero if it exceeded it.  This lets you conceal a certain number of retries
+ * before alerting the caller there is a problem.
+ *
+ * If \p retry is NULL, a default of 3s + (0..300ms jitter) is used.  If it's
+ * non-NULL but jitter_percent is 0, the default of 30% jitter is retained.
+ */
+
+LWS_VISIBLE LWS_EXTERN unsigned int
+lws_retry_get_delay_ms(struct lws_context *context, const lws_retry_bo_t *retry,
+		       uint16_t *ctry, char *conceal);
+
+/**
+ * lws_retry_sul_schedule() - schedule a sul according to the backoff table
+ *
+ * \param lws_context: the lws context (used for getting random)
+ * \param sul: pointer to the sul to schedule
+ * \param retry: the retry backoff table we are using, or NULL for default
+ * \param cb: the callback for when the sul schedule time arrives
+ * \param ctry: pointer to the try counter
+ *
+ * Helper that combines interpreting the retry table with scheduling a sul to
+ * the computed delay.  If conceal is not set, it will not schedule the sul
+ * and just return 1.  Otherwise the sul is scheduled and it returns 0.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_retry_sul_schedule(struct lws_context *context, int tid,
+		       lws_sorted_usec_list_t *sul, const lws_retry_bo_t *retry,
+		       sul_cb_t cb, uint16_t *ctry);
+
+/**
+ * lws_retry_sul_schedule_retry_wsi() - retry sul schedule helper using wsi
+ *
+ * \param wsi: the wsi to set the hrtimer sul on to the next retry interval
+ * \param sul: pointer to the sul to schedule
+ * \param cb: the callback for when the sul schedule time arrives
+ * \param ctry: pointer to the try counter
+ *
+ * Helper that uses context, tid and retry policy from a wsi to call
+ * lws_retry_sul_schedule.
+ *
+ * Since a udp connection can have many writes in flight, the retry count and
+ * the sul used to track each thing that wants to be written have to be handled
+ * individually, not the wsi.  But the retry policy and the other things can
+ * be filled in from the wsi conveniently.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_retry_sul_schedule_retry_wsi(struct lws *wsi, lws_sorted_usec_list_t *sul,
+				 sul_cb_t cb, uint16_t *ctry);

include/libwebsockets/lws-ring.h

@@ -0,0 +1,306 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup lws_ring LWS Ringbuffer APIs
+ * ##lws_ring: generic ringbuffer struct
+ *
+ * Provides an abstract ringbuffer api supporting one head and one or an
+ * unlimited number of tails.
+ *
+ * All of the members are opaque and manipulated by lws_ring_...() apis.
+ *
+ * The lws_ring and its buffer is allocated at runtime on the heap, using
+ *
+ *  - lws_ring_create()
+ *  - lws_ring_destroy()
+ *
+ * It may contain any type, the size of the "element" stored in the ring
+ * buffer and the number of elements is given at creation time.
+ *
+ * When you create the ringbuffer, you can optionally provide an element
+ * destroy callback that frees any allocations inside the element.  This is then
+ * automatically called for elements with no tail behind them, ie, elements
+ * which don't have any pending consumer are auto-freed.
+ *
+ * Whole elements may be inserted into the ringbuffer and removed from it, using
+ *
+ *  - lws_ring_insert()
+ *  - lws_ring_consume()
+ *
+ * You can find out how many whole elements are free or waiting using
+ *
+ *  - lws_ring_get_count_free_elements()
+ *  - lws_ring_get_count_waiting_elements()
+ *
+ * In addition there are special purpose optional byte-centric apis
+ *
+ *  - lws_ring_next_linear_insert_range()
+ *  - lws_ring_bump_head()
+ *
+ *  which let you, eg, read() directly into the ringbuffer without needing
+ *  an intermediate bounce buffer.
+ *
+ *  The accessors understand that the ring wraps, and optimizes insertion and
+ *  consumption into one or two memcpy()s depending on if the head or tail
+ *  wraps.
+ *
+ *  lws_ring only supports a single head, but optionally multiple tails with
+ *  an API to inform it when the "oldest" tail has moved on.  You can give
+ *  NULL where-ever an api asks for a tail pointer, and it will use an internal
+ *  single tail pointer for convenience.
+ *
+ *  The "oldest tail", which is the only tail if you give it NULL instead of
+ *  some other tail, is used to track which elements in the ringbuffer are
+ *  still unread by anyone.
+ *
+ *   - lws_ring_update_oldest_tail()
+ */
+///@{
+struct lws_ring;
+
+/**
+ * lws_ring_create(): create a new ringbuffer
+ *
+ * \param element_len: the size in bytes of one element in the ringbuffer
+ * \param count: the number of elements the ringbuffer can contain
+ * \param destroy_element: NULL, or callback to be called for each element
+ *			   that is removed from the ringbuffer due to the
+ *			   oldest tail moving beyond it
+ *
+ * Creates the ringbuffer and allocates the storage.  Returns the new
+ * lws_ring *, or NULL if the allocation failed.
+ *
+ * If non-NULL, destroy_element will get called back for every element that is
+ * retired from the ringbuffer after the oldest tail has gone past it, and for
+ * any element still left in the ringbuffer when it is destroyed.  It replaces
+ * all other element destruction code in your user code.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_ring *
+lws_ring_create(size_t element_len, size_t count,
+		void (*destroy_element)(void *element));
+
+/**
+ * lws_ring_destroy():  destroy a previously created ringbuffer
+ *
+ * \param ring: the struct lws_ring to destroy
+ *
+ * Destroys the ringbuffer allocation and the struct lws_ring itself.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ring_destroy(struct lws_ring *ring);
+
+/**
+ * lws_ring_get_count_free_elements():  return how many elements can fit
+ *				      in the free space
+ *
+ * \param ring: the struct lws_ring to report on
+ *
+ * Returns how much room is left in the ringbuffer for whole element insertion.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_ring_get_count_free_elements(struct lws_ring *ring);
+
+/**
+ * lws_ring_get_count_waiting_elements():  return how many elements can be consumed
+ *
+ * \param ring: the struct lws_ring to report on
+ * \param tail: a pointer to the tail struct to use, or NULL for single tail
+ *
+ * Returns how many elements are waiting to be consumed from the perspective
+ * of the tail pointer given.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_ring_get_count_waiting_elements(struct lws_ring *ring, uint32_t *tail);
+
+/**
+ * lws_ring_insert():  attempt to insert up to max_count elements from src
+ *
+ * \param ring: the struct lws_ring to report on
+ * \param src: the array of elements to be inserted
+ * \param max_count: the number of available elements at src
+ *
+ * Attempts to insert as many of the elements at src as possible, up to the
+ * maximum max_count.  Returns the number of elements actually inserted.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_ring_insert(struct lws_ring *ring, const void *src, size_t max_count);
+
+/**
+ * lws_ring_consume():  attempt to copy out and remove up to max_count elements
+ *		        to src
+ *
+ * \param ring: the struct lws_ring to report on
+ * \param tail: a pointer to the tail struct to use, or NULL for single tail
+ * \param dest: the array of elements to be inserted. or NULL for no copy
+ * \param max_count: the number of available elements at src
+ *
+ * Attempts to copy out as many waiting elements as possible into dest, from
+ * the perspective of the given tail, up to max_count.  If dest is NULL, the
+ * copying out is not done but the elements are logically consumed as usual.
+ * NULL dest is useful in combination with lws_ring_get_element(), where you
+ * can use the element direct from the ringbuffer and then call this with NULL
+ * dest to logically consume it.
+ *
+ * Increments the tail position according to how many elements could be
+ * consumed.
+ *
+ * Returns the number of elements consumed.
+ */
+LWS_VISIBLE LWS_EXTERN size_t
+lws_ring_consume(struct lws_ring *ring, uint32_t *tail, void *dest,
+		 size_t max_count);
+
+/**
+ * lws_ring_get_element():  get a pointer to the next waiting element for tail
+ *
+ * \param ring: the struct lws_ring to report on
+ * \param tail: a pointer to the tail struct to use, or NULL for single tail
+ *
+ * Points to the next element that tail would consume, directly in the
+ * ringbuffer.  This lets you write() or otherwise use the element without
+ * having to copy it out somewhere first.
+ *
+ * After calling this, you must call lws_ring_consume(ring, &tail, NULL, 1)
+ * which will logically consume the element you used up and increment your
+ * tail (tail may also be NULL there if you use a single tail).
+ *
+ * Returns NULL if no waiting element, or a const void * pointing to it.
+ */
+LWS_VISIBLE LWS_EXTERN const void *
+lws_ring_get_element(struct lws_ring *ring, uint32_t *tail);
+
+/**
+ * lws_ring_update_oldest_tail():  free up elements older than tail for reuse
+ *
+ * \param ring: the struct lws_ring to report on
+ * \param tail: a pointer to the tail struct to use, or NULL for single tail
+ *
+ * If you are using multiple tails, you must use this API to inform the
+ * lws_ring when none of the tails still need elements in the fifo any more,
+ * by updating it when the "oldest" tail has moved on.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ring_update_oldest_tail(struct lws_ring *ring, uint32_t tail);
+
+/**
+ * lws_ring_get_oldest_tail():  get current oldest available data index
+ *
+ * \param ring: the struct lws_ring to report on
+ *
+ * If you are initializing a new ringbuffer consumer, you can set its tail to
+ * this to start it from the oldest ringbuffer entry still available.
+ */
+LWS_VISIBLE LWS_EXTERN uint32_t
+lws_ring_get_oldest_tail(struct lws_ring *ring);
+
+/**
+ * lws_ring_next_linear_insert_range():  used to write directly into the ring
+ *
+ * \param ring: the struct lws_ring to report on
+ * \param start: pointer to a void * set to the start of the next ringbuffer area
+ * \param bytes: pointer to a size_t set to the max length you may use from *start
+ *
+ * This provides a low-level, bytewise access directly into the ringbuffer
+ * allowing direct insertion of data without having to use a bounce buffer.
+ *
+ * The api reports the position and length of the next linear range that can
+ * be written in the ringbuffer, ie, up to the point it would wrap, and sets
+ * *start and *bytes accordingly.  You can then, eg, directly read() into
+ * *start for up to *bytes, and use lws_ring_bump_head() to update the lws_ring
+ * with what you have done.
+ *
+ * Returns nonzero if no insertion is currently possible.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_ring_next_linear_insert_range(struct lws_ring *ring, void **start,
+				  size_t *bytes);
+
+/**
+ * lws_ring_bump_head():  used to write directly into the ring
+ *
+ * \param ring: the struct lws_ring to operate on
+ * \param bytes: the number of bytes you inserted at the current head
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ring_bump_head(struct lws_ring *ring, size_t bytes);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_ring_dump(struct lws_ring *ring, uint32_t *tail);
+
+/*
+ * This is a helper that combines the common pattern of needing to consume
+ * some ringbuffer elements, move the consumer tail on, and check if that
+ * has moved any ringbuffer elements out of scope, because it was the last
+ * consumer that had not already consumed them.
+ *
+ * Elements that go out of scope because the oldest tail is now after them
+ * get garbage-collected by calling the destroy_element callback on them
+ * defined when the ringbuffer was created.
+ */
+
+#define lws_ring_consume_and_update_oldest_tail(\
+		___ring,    /* the lws_ring object */ \
+		___type,    /* type of objects with tails */ \
+		___ptail,   /* ptr to tail of obj with tail doing consuming */ \
+		___count,   /* count of payload objects being consumed */ \
+		___list_head,	/* head of list of objects with tails */ \
+		___mtail,   /* member name of tail in ___type */ \
+		___mlist  /* member name of next list member ptr in ___type */ \
+	) { \
+		int ___n, ___m; \
+	\
+	___n = lws_ring_get_oldest_tail(___ring) == *(___ptail); \
+	lws_ring_consume(___ring, ___ptail, NULL, ___count); \
+	if (___n) { \
+		uint32_t ___oldest; \
+		___n = 0; \
+		___oldest = *(___ptail); \
+		lws_start_foreach_llp(___type **, ___ppss, ___list_head) { \
+			___m = (int)lws_ring_get_count_waiting_elements( \
+					___ring, &(*___ppss)->___mtail); \
+			if (___m >= ___n) { \
+				___n = ___m; \
+				___oldest = (*___ppss)->___mtail; \
+			} \
+		} lws_end_foreach_llp(___ppss, ___mlist); \
+	\
+		lws_ring_update_oldest_tail(___ring, ___oldest); \
+	} \
+}
+
+/*
+ * This does the same as the lws_ring_consume_and_update_oldest_tail()
+ * helper, but for the simpler case there is only one consumer, so one
+ * tail, and that tail is always the oldest tail.
+ */
+
+#define lws_ring_consume_single_tail(\
+		___ring,  /* the lws_ring object */ \
+		___ptail, /* ptr to tail of obj with tail doing consuming */ \
+		___count  /* count of payload objects being consumed */ \
+	) { \
+	lws_ring_consume(___ring, ___ptail, NULL, ___count); \
+	lws_ring_update_oldest_tail(___ring, *(___ptail)); \
+}
+///@}

include/libwebsockets/lws-secure-streams-client.h

@@ -0,0 +1,331 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is the headers for secure stream api variants that deal with clients in
+ * different threads or even different processes.
+ *
+ * lws_ss_          when client is directly using the event loop
+ * lws_sstc_        when client is in a different thread to the event loop
+ * lws_sspc_        when client is in a different process to the event loop
+ *
+ * The client api is almost the same except the slightly diffent names.
+ */
+
+/*
+ * lws_sspc_ apis... different process
+ */
+
+/*
+ * Helper translation so user code written to lws_ss_ can be built for
+ * lws_sspc_ in one step by #define LWS_SS_USE_SSPC before including
+ */
+
+struct lws_sspc_handle;
+
+#if defined(LWS_SS_USE_SSPC)
+#define lws_ss_handle			lws_sspc_handle
+#define lws_ss_create			lws_sspc_create
+#define lws_ss_destroy			lws_sspc_destroy
+#define lws_ss_request_tx		lws_sspc_request_tx
+#define lws_ss_request_tx_len		lws_sspc_request_tx_len
+#define lws_ss_client_connect		lws_sspc_client_connect
+#define lws_ss_get_sequencer		lws_sspc_get_sequencer
+#define lws_ss_proxy_create		lws_sspc_proxy_create
+#define lws_ss_get_context		lws_sspc_get_context
+#define lws_ss_rideshare		lws_sspc_rideshare
+#define lws_ss_set_metadata		lws_sspc_set_metadata
+#define lws_ss_get_metadata		lws_sspc_get_metadata
+#define lws_ss_add_peer_tx_credit	lws_sspc_add_peer_tx_credit
+#define lws_ss_get_est_peer_tx_credit	lws_sspc_get_est_peer_tx_credit
+#define lws_ss_start_timeout		lws_sspc_start_timeout
+#define lws_ss_cancel_timeout		lws_sspc_cancel_timeout
+#define lws_ss_to_user_object		lws_sspc_to_user_object
+#define lws_ss_change_handlers		lws_sspc_change_handlers
+#define lws_smd_ss_rx_forward		lws_smd_sspc_rx_forward
+#define lws_ss_tag			lws_sspc_tag
+#define _lws_fi_user_ss_fi		_lws_fi_user_sspc_fi
+#define lwsl_ss_get_cx			lwsl_sspc_get_cx
+
+LWS_VISIBLE LWS_EXTERN void
+lws_log_prepend_sspc(struct lws_log_cx *cx, void *obj, char **p, char *e);
+
+LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
+lwsl_sspc_get_cx(struct lws_sspc_handle *ss);
+
+#undef lwsl_ss
+#define lwsl_ss lwsl_sspc
+
+#undef lwsl_hexdump_ss
+#define lwsl_hexdump_ss lwsl_hexdump_sspc
+#endif
+
+#define lwsl_sspc(_h, _fil, ...) \
+		 _lws_log_cx(lwsl_sspc_get_cx(_h), lws_log_prepend_sspc, _h, \
+					_fil, __func__, __VA_ARGS__)
+
+#define lwsl_hexdump_sspc(_h, _fil, _buf, _len) \
+		lwsl_hexdump_level_cx(lwsl_sspc_get_cx(_h), \
+				      lws_log_prepend_sspc, \
+				      _h, _fil, _buf, _len)
+
+/*
+ * lwsl_sspc
+ */
+
+#if (_LWS_ENABLED_LOGS & LLL_ERR)
+#define lwsl_sspc_err(_w, ...) lwsl_sspc(_w, LLL_ERR, __VA_ARGS__)
+#else
+#define lwsl_sspc_err(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_WARN)
+#define lwsl_sspc_warn(_w, ...) lwsl_sspc(_w, LLL_WARN, __VA_ARGS__)
+#else
+#define lwsl_sspc_warn(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_NOTICE)
+#define lwsl_sspc_notice(_w, ...) lwsl_sspc(_w, LLL_NOTICE, __VA_ARGS__)
+#else
+#define lwsl_sspc_notice(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_INFO)
+#define lwsl_sspc_info(_w, ...) lwsl_sspc(_w, LLL_INFO, __VA_ARGS__)
+#else
+#define lwsl_sspc_info(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_DEBUG)
+#define lwsl_sspc_debug(_w, ...) lwsl_sspc(_w, LLL_DEBUG, __VA_ARGS__)
+#else
+#define lwsl_sspc_debug(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_PARSER)
+#define lwsl_sspc_parser(_w, ...) lwsl_sspc(_w, LLL_PARSER, __VA_ARGS__)
+#else
+#define lwsl_sspc_parser(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_HEADER)
+#define lwsl_sspc_header(_w, ...) lwsl_sspc(_w, LLL_HEADER, __VA_ARGS__)
+#else
+#define lwsl_sspc_header(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_EXT)
+#define lwsl_sspc_ext(_w, ...) lwsl_sspc(_w, LLL_EXT, __VA_ARGS__)
+#else
+#define lwsl_sspc_ext(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_CLIENT)
+#define lwsl_sspc_client(_w, ...) lwsl_sspc(_w, LLL_CLIENT, __VA_ARGS__)
+#else
+#define lwsl_sspc_client(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_LATENCY)
+#define lwsl_sspc_latency(_w, ...) lwsl_sspc(_w, LLL_LATENCY, __VA_ARGS__)
+#else
+#define lwsl_sspc_latency(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_THREAD)
+#define lwsl_sspc_thread(_w, ...) lwsl_sspc(_w, LLL_THREAD, __VA_ARGS__)
+#else
+#define lwsl_sspc_thread(_w, ...) do {} while(0)
+#endif
+
+#if (_LWS_ENABLED_LOGS & LLL_USER)
+#define lwsl_sspc_user(_w, ...) lwsl_sspc(_w, LLL_USER, __VA_ARGS__)
+#else
+#define lwsl_sspc_user(_w, ...) do {} while(0)
+#endif
+
+#define lwsl_hexdump_sspc_err(_v, ...)    lwsl_hexdump_sspc(_v, LLL_ERR, __VA_ARGS__)
+#define lwsl_hexdump_sspc_warn(_v, ...)   lwsl_hexdump_sspc(_v, LLL_WARN, __VA_ARGS__)
+#define lwsl_hexdump_sspc_notice(_v, ...) lwsl_hexdump_sspc(_v, LLL_NOTICE, __VA_ARGS__)
+#define lwsl_hexdump_sspc_info(_v, ...)   lwsl_hexdump_sspc(_v, LLL_INFO, __VA_ARGS__)
+#define lwsl_hexdump_sspc_debug(_v, ...)  lwsl_hexdump_sspc(_v, LLL_DEBUG, __VA_ARGS__)
+
+
+LWS_VISIBLE LWS_EXTERN int
+lws_sspc_create(struct lws_context *context, int tsi, const lws_ss_info_t *ssi,
+		void *opaque_user_data, struct lws_sspc_handle **ppss,
+		struct lws_sequencer *seq_owner, const char **ppayload_fmt);
+
+/**
+ * lws_sspc_destroy() - Destroy secure stream
+ *
+ * \param ppss: pointer to lws_ss_t pointer to be destroyed
+ *
+ * Destroys the lws_ss_t pointed to by *ppss, and sets *ppss to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_sspc_destroy(struct lws_sspc_handle **ppss);
+
+/**
+ * lws_sspc_request_tx() - Schedule stream for tx
+ *
+ * \param pss: pointer to lws_ss_t representing stream that wants to transmit
+ *
+ * Schedules a write on the stream represented by \p pss.  When it's possible to
+ * write on this stream, the *tx callback will occur with an empty buffer for
+ * the stream owner to fill in.
+ */
+LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
+lws_sspc_request_tx(struct lws_sspc_handle *pss);
+
+/**
+ * lws_sspc_request_tx_len() - Schedule stream for tx with length hint
+ *
+ * \param h: pointer to handle representing stream that wants to transmit
+ * \param len: the length of the write in bytes
+ *
+ * Schedules a write on the stream represented by \p pss.  When it's possible to
+ * write on this stream, the *tx callback will occur with an empty buffer for
+ * the stream owner to fill in.
+ *
+ * This api variant should be used when it's possible the payload will go out
+ * over h1 with x-web-form-urlencoded or similar Content-Type.
+ *
+ * The serialized, sspc type api actually serializes and forwards the length
+ * hint to its upstream proxy, where it's available for use to produce the
+ * internet-capable protocol framing.
+ */
+LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
+lws_sspc_request_tx_len(struct lws_sspc_handle *h, unsigned long len);
+
+/**
+ * lws_sspc_client_connect() - Attempt the client connect
+ *
+ * \param h: secure streams handle
+ *
+ * Starts the connection process for the secure stream.  Returns 0.
+ */
+LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
+lws_sspc_client_connect(struct lws_sspc_handle *h);
+
+/**
+ * lws_sspc_get_sequencer() - Return parent sequencer pointer if any
+ *
+ * \param h: secure streams handle
+ *
+ * Returns NULL if the secure stream is not associated with a sequencer.
+ * Otherwise returns a pointer to the owning sequencer.  You can use this to
+ * identify which sequencer to direct messages to, from the secure stream
+ * callback.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
+lws_sspc_get_sequencer(struct lws_sspc_handle *h);
+
+/**
+ * lws_sspc_proxy_create() - Start a unix domain socket proxy for Secure Streams
+ *
+ * \param context: lws_context
+ *
+ * Creates a vhost that listens on an abstract namespace unix domain socket at
+ * address "proxy.ss.lws".  Client connections to this proxy to Secure Streams
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sspc_proxy_create(struct lws_context *context);
+
+/**
+ * lws_ss_get_context() - convenience helper to recover the lws context
+ *
+ * \h: secure streams handle
+ *
+ * Returns the lws context.  Dispenses with the need to pass a copy of it into
+ * your secure streams handler.
+ */
+
+LWS_VISIBLE LWS_EXTERN struct lws_context *
+lws_sspc_get_context(struct lws_sspc_handle *h);
+
+LWS_VISIBLE extern const struct lws_protocols lws_sspc_protocols[2];
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_sspc_rideshare(struct lws_sspc_handle *h);
+
+
+/**
+ * lws_sspc_set_metadata() - allow user to bind external data to defined ss metadata
+ *
+ * \h: secure streams handle
+ * \name: metadata name from the policy
+ * \value: pointer to user-managed data to bind to name
+ * \len: length of the user-managed data in value
+ *
+ * Binds user-managed data to the named metadata item from the ss policy.
+ * If present, the metadata item is handled in a protocol-specific way using
+ * the associated policy information.  For example, in the policy
+ *
+ *  	"\"metadata\":"		"["
+ *		"{\"uptag\":"  "\"X-Upload-Tag:\"},"
+ *		"{\"ctype\":"  "\"Content-Type:\"},"
+ *		"{\"xctype\":" "\"X-Content-Type:\"}"
+ *	"],"
+ *
+ * when the policy is using h1 is interpreted to add h1 headers of the given
+ * name with the value of the metadata on the left.
+ *
+ * Return 0 if OK, or nonzero if failed.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name,
+		      const void *value, size_t len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_sspc_get_metadata(struct lws_sspc_handle *h, const char *name,
+		      const void **value, size_t *len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_sspc_add_peer_tx_credit(struct lws_sspc_handle *h, int32_t add);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_sspc_get_est_peer_tx_credit(struct lws_sspc_handle *h);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_sspc_start_timeout(struct lws_sspc_handle *h, unsigned int timeout_ms);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_sspc_cancel_timeout(struct lws_sspc_handle *h);
+
+LWS_VISIBLE LWS_EXTERN void *
+lws_sspc_to_user_object(struct lws_sspc_handle *h);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_sspc_change_handlers(struct lws_sspc_handle *h,
+	lws_ss_state_return_t (*rx)(void *userobj, const uint8_t *buf,
+				    size_t len, int flags),
+	lws_ss_state_return_t (*tx)(void *userobj, lws_ss_tx_ordinal_t ord,
+				    uint8_t *buf, size_t *len, int *flags),
+	lws_ss_state_return_t (*state)(void *userobj, void *h_src
+					/* ss handle type */,
+				       lws_ss_constate_t state,
+				       lws_ss_tx_ordinal_t ack));
+
+const char *
+lws_sspc_tag(struct lws_sspc_handle *h);

include/libwebsockets/lws-secure-streams-policy.h

@@ -0,0 +1,418 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2019 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * included from libwebsockets.h
+ */
+
+typedef int (*plugin_auth_status_cb)(struct lws_ss_handle *ss, int status);
+
+/**
+ * lws_ss_plugin_auth_t - api for an auth plugin
+ *
+ * Auth plugins create and sequence authenticated connections that can carry one
+ * or more streams to an endpoint.  That may involve other connections to other
+ * places to eg, gather authenticated tokens and then make the real connection
+ * using the tokens.
+ *
+ * The secure stream object contains members to record which auth plugin the
+ * stream is bound to and an over-allocation of the secure stream object to
+ * contain the plugin auth private data.
+ *
+ * The auth plugin controls the state of the stream connection via the status
+ * callback, and handles retries.
+ *
+ * Network connections may require one kind of auth sequencing, and streams
+ * inside those connections another kind of auth sequencing depending on their
+ * role.  So the secure stream object allows defining plugins for both kinds.
+ *
+ * Streams may disappear at any time and require reauth to bring a new one up.
+ * The auth plugin sequencer will connect / reconnect either on demand, or from
+ * the start and after any connectivity loss if any stream using the connection
+ * has the LWSSSPOLF_NAILED_UP flag.
+ */
+
+#if defined(LWS_WITH_SSPLUGINS)
+typedef struct lws_ss_plugin {
+	struct lws_ss_plugin	*next;
+	const char		*name;	/**< auth plugin name */
+	size_t			alloc;	/**< size of private allocation */
+
+	int			(*create)(struct lws_ss_handle *ss, void *info,
+					  plugin_auth_status_cb status);
+				/**< called when the auth plugin is instantiated
+				     and bound to the secure stream.  status is
+				     called back with advisory information about
+				     the authenticated stream state as it
+				     proceeds */
+	int			(*destroy)(struct lws_ss_handle *ss);
+				/**< called when the related secure stream is
+				     being destroyed, and anything the auth
+				     plugin is doing should also be destroyed */
+	int			(*munge)(struct lws_ss_handle *ss, char *path,
+					 size_t path_len);
+				/**< if the plugin needs to munge transactions
+				     that have metadata outside the payload (eg,
+				     add http headers) this callback will give
+				     it the opportunity to do so */
+} lws_ss_plugin_t;
+#endif
+
+/* the public, const metrics policy definition */
+
+typedef struct lws_metric_policy {
+	/* order of first two mandated by JSON policy parsing scope union */
+	const struct lws_metric_policy	*next;
+	const char			*name;
+
+	const char			*report;
+
+	/**< the metrics policy name in the policy, used to bind to it */
+	uint64_t			us_schedule;
+	/**< us interval between lws_system metrics api reports */
+
+	uint32_t			us_decay_unit;
+	/**< how many us to decay avg by half, 0 = no decay */
+	uint8_t				min_contributors;
+	/**< before we can judge something is an outlier */
+} lws_metric_policy_t;
+
+typedef struct lws_ss_x509 {
+	struct lws_ss_x509	*next;
+	const char		*vhost_name; /**< vhost name using cert ctx */
+	const uint8_t		*ca_der;	/**< DER x.509 cert */
+	size_t			ca_der_len;	/**< length of DER cert */
+	uint8_t			keep:1; /**< ie, if used in server tls */
+} lws_ss_x509_t;
+
+enum {
+	LWSSSPOLF_OPPORTUNISTIC					= (1 << 0),
+	/**< the connection doesn't exist unless client asks to write */
+	LWSSSPOLF_NAILED_UP					= (1 << 1),
+	/**< the connection tries to be connected the whole life of the ss */
+	LWSSSPOLF_URGENT_TX					= (1 << 2),
+	/**< this connection carries critical tx data */
+	LWSSSPOLF_URGENT_RX					= (1 << 3),
+	/**< this connection carries critical rx data */
+	LWSSSPOLF_TLS						= (1 << 4),
+	/**< stream must be connected via a tls tunnel */
+	LWSSSPOLF_LONG_POLL					= (1 << 5),
+	/**< stream used to receive async rx at arbitrary intervals */
+	LWSSSPOLF_AUTH_BEARER					= (1 << 6),
+	/**< for http, use lws_system auth token 0 in authentication: bearer */
+	LWSSSPOLF_HTTP_NO_CONTENT_LENGTH			= (1 << 7),
+	/**< don't add any content length even if we have it */
+	LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM			= (1 << 8),
+	/**< set the client flag LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM */
+	LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR			= (1 << 9),
+	/**< set the client flag LCCSCF_H2_QUIRK_OVERFLOWS_TXCR */
+	LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE			= (1 << 10),
+	/**< HPACK decoder state does not end cleanly */
+	LWSSSPOLF_HTTP_MULTIPART				= (1 << 11),
+	/**< indicates stream goes out as specifically a multipart mime POST
+	 * section... if the tx has LWSSS_FLAG_COALESCE_CONTINUES flag then more
+	 * multipart sections are expected.  Without it, the multipart wrapper
+	 * is closed and the http transaction issue completed when this message
+	 * finishes. */
+	LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED			= (1 << 12),
+	/**< set up lws_system client cert */
+	LWSSSPOLF_LOCAL_SINK					= (1 << 13),
+	/**< expected to bind to a local sink only */
+	LWSSSPOLF_WAKE_SUSPEND__VALIDITY			= (1 << 14),
+	/**< this stream's idle validity checks are critical enough we
+	 * should arrange to wake from suspend to perform them
+	 */
+	LWSSSPOLF_SERVER					= (1 << 15),
+	/**< we listen on a socket as a server */
+	LWSSSPOLF_ALLOW_REDIRECTS				= (1 << 16),
+	/**< follow redirects */
+	LWSSSPOLF_HTTP_MULTIPART_IN				= (1 << 17),
+	/**< handle inbound multipart mime at SS level */
+
+	LWSSSPOLF_ATTR_LOW_LATENCY				= (1 << 18),
+	/**< stream requires low latency */
+	LWSSSPOLF_ATTR_HIGH_THROUGHPUT				= (1 << 19),
+	/**< stream requires high throughput */
+	LWSSSPOLF_ATTR_HIGH_RELIABILITY				= (1 << 20),
+	/**< stream requires high reliability */
+	LWSSSPOLF_ATTR_LOW_COST					= (1 << 21),
+	/**< stream is not critical and should be handled as cheap as poss */
+	LWSSSPOLF_PERF						= (1 << 22),
+	/**< capture and report performace information */
+	LWSSSPOLF_DIRECT_PROTO_STR				= (1 << 23),
+	/**< metadata as direct protocol string, e.g. http header */
+	LWSSSPOLF_HTTP_CACHE_COOKIES				= (1 << 24),
+	/**< Record http cookies and pass them back on future requests */
+	LWSSSPOLF_PRIORITIZE_READS				= (1 << 25),
+	/**< prioritize clearing reads at expense of writes */
+
+};
+
+typedef struct lws_ss_trust_store {
+	struct lws_ss_trust_store	*next;
+	const char			*name;
+
+	const lws_ss_x509_t		*ssx509[6];
+	int				count;
+} lws_ss_trust_store_t;
+
+enum {
+	LWSSSP_H1,
+	LWSSSP_H2,
+	LWSSSP_WS,
+	LWSSSP_MQTT,
+	LWSSSP_RAW,
+
+
+	LWSSS_HBI_AUTH = 0,
+	LWSSS_HBI_DSN,
+	LWSSS_HBI_FWV,
+	LWSSS_HBI_TYPE,
+
+	_LWSSS_HBI_COUNT /* always last */
+};
+
+/*
+ * This does for both the static policy metadata entry, and the runtime metadata
+ * handling object.
+ */
+
+typedef struct lws_ss_metadata {
+	struct lws_ss_metadata	*next;
+	const char		*name;
+	void			*value__may_own_heap;
+	size_t			length;
+
+	uint8_t			value_length; /* only valid if set by policy */
+	uint8_t			value_is_http_token; /* valid if set by policy */
+#if defined(LWS_WITH_SS_DIRECT_PROTOCOL_STR)
+	uint8_t			name_on_lws_heap:1;  /* proxy metatadata does this */
+#endif
+	uint8_t			value_on_lws_heap:1; /* proxy + rx metadata does this */
+#if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
+	uint8_t			pending_onward:1;
+#endif
+} lws_ss_metadata_t;
+
+typedef struct lws_ss_http_respmap {
+	uint16_t		resp;	/* the http response code */
+	uint16_t		state;	/* low 16-bits of associated state */
+} lws_ss_http_respmap_t;
+
+/*
+ * This is a mapping between an auth streamtype and a name and other information
+ * that can be independently instantiated.  Other streamtypes can indicate they
+ * require this authentication on their connection.
+ */
+
+typedef struct lws_ss_auth {
+	struct lws_ss_auth	*next;
+	const char		*name;
+
+	const char		*type;
+	const char		*streamtype;
+	uint8_t			blob_index;
+} lws_ss_auth_t;
+
+/**
+ * lws_ss_policy_t: policy database entry for a stream type
+ *
+ * Decides the system policy for how to implement connections of name
+ * .streamtype.
+ *
+ * Streams may need one kind of auth sequencing for the network connection and
+ * another kind of auth sequencing for the streams that are carried inside it,
+ * this is the purpose of .nauth and .sauth.  Both are optional and may be NULL.
+ *
+ * An array of these is set at context creation time, ending with one with a
+ * NULL streamtype.
+ */
+typedef struct lws_ss_policy {
+	struct lws_ss_policy	*next;
+	const char		*streamtype; /**< stream type lhs to match on */
+
+	const char		*endpoint;   /**< DNS address to connect to */
+	const char		*rideshare_streamtype; /**< optional transport
+					* on another, preexisting stream of this
+					* streamtype name */
+	const char		*payload_fmt;
+	const char		*socks5_proxy;
+	lws_ss_metadata_t	*metadata; /* linked-list of metadata */
+	const lws_metric_policy_t *metrics; /* linked-list of metric policies */
+	const lws_ss_auth_t	*auth; /* NULL or auth object we bind to */
+
+	/* protocol-specific connection policy details */
+
+	union {
+
+#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) || defined(LWS_ROLE_WS)
+
+		/* details for http-related protocols... */
+
+		struct {
+
+			/* common to all http-related protocols */
+
+			const char	*method;
+			const char	*url;
+
+			const char	*multipart_name;
+			const char	*multipart_filename;
+			const char	*multipart_content_type;
+
+			const char	*blob_header[_LWSSS_HBI_COUNT];
+			const char	*auth_preamble;
+
+			const lws_ss_http_respmap_t *respmap;
+
+			union {
+//				struct { /* LWSSSP_H1 */
+//				} h1;
+//				struct { /* LWSSSP_H2 */
+//				} h2;
+				struct { /* LWSSSP_WS */
+					const char	*subprotocol;
+					uint8_t		binary;
+					/* false = TEXT, true = BINARY */
+				} ws;
+			} u;
+
+			uint16_t	resp_expect;
+			uint8_t		count_respmap;
+			uint8_t		fail_redirect:1;
+		} http;
+
+#endif
+
+#if defined(LWS_ROLE_MQTT)
+
+		struct {
+			const char	*topic;	    /* stream sends on this topic */
+			const char	*subscribe; /* stream subscribes to this topic */
+
+			const char	*will_topic;
+			const char	*will_message;
+
+			const char	*birth_topic;
+			const char	*birth_message;
+
+			uint16_t	keep_alive;
+			uint8_t		qos;
+			uint8_t		clean_start;
+			uint8_t		will_qos;
+			uint8_t		will_retain;
+			uint8_t		birth_qos;
+			uint8_t		birth_retain;
+			uint8_t		aws_iot;
+			uint8_t		retain;
+
+		} mqtt;
+
+#endif
+
+		/* details for non-http related protocols... */
+	} u;
+
+#if defined(LWS_WITH_SSPLUGINS)
+	const
+	struct lws_ss_plugin	*plugins[2]; /**< NULL or auth plugin */
+	const void		*plugins_info[2];   /**< plugin-specific data */
+#endif
+
+#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
+	/* directly point to the metadata name, no need to expand */
+	const char *aws_region;
+	const char *aws_service;
+#endif
+	/*
+	 * We're either a client connection policy that wants a trust store,
+	 * or we're a server policy that wants a mem cert and key... Hold
+	 * these mutually-exclusive things in a union.
+	 */
+
+	union {
+		const lws_ss_trust_store_t		*store;
+		/**< CA certs needed for conn validation, only set between
+		 * policy parsing and vhost creation */
+		struct {
+			const lws_ss_x509_t		*cert;
+			/**< the server's signed cert with the pubkey */
+			const lws_ss_x509_t		*key;
+			/**< the server's matching private key */
+		} server;
+	} trust;
+
+	const lws_retry_bo_t	*retry_bo;   /**< retry policy to use */
+
+	uint32_t		proxy_buflen; /**< max dsh alloc for proxy */
+	uint32_t		proxy_buflen_rxflow_on_above;
+	uint32_t		proxy_buflen_rxflow_off_below;
+
+	uint32_t		client_buflen; /**< max dsh alloc for client */
+	uint32_t		client_buflen_rxflow_on_above;
+	uint32_t		client_buflen_rxflow_off_below;
+
+
+	uint32_t		timeout_ms;  /**< default message response
+					      * timeout in ms */
+	uint32_t		flags;	     /**< stream attribute flags */
+
+	uint16_t		port;	     /**< endpoint port */
+
+	uint8_t			metadata_count;    /**< metadata count */
+	uint8_t			protocol;    /**< protocol index */
+	uint8_t			client_cert; /**< which client cert to apply
+						  0 = none, 1+ = cc 0+ */
+	uint8_t			priority;	/* 0 = normal, 6 = max normal,
+						 * 7 = network management */
+} lws_ss_policy_t;
+
+#if !defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY)
+
+/*
+ * These only exist / have meaning if there's a dynamic JSON policy enabled
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_policy_parse_begin(struct lws_context *context, int overlay);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_policy_parse_abandon(struct lws_context *context);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_policy_parse(struct lws_context *context, const uint8_t *buf, size_t len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_policy_overlay(struct lws_context *context, const char *overlay);
+
+/*
+ * You almost certainly don't want these, they return the first policy or auth
+ * object in a linked-list of objects created by lws_ss_policy_parse above,
+ * they are exported to generate static policy with
+ */
+LWS_VISIBLE LWS_EXTERN const lws_ss_policy_t *
+lws_ss_policy_get(struct lws_context *context);
+
+LWS_VISIBLE LWS_EXTERN const lws_ss_auth_t *
+lws_ss_auth_get(struct lws_context *context);
+
+#endif

include/libwebsockets/lws-secure-streams.h

@@ -0,0 +1,846 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * included from libwebsockets.h
+ *
+ *
+ * Secure Streams is a *payload-only* client communication channel where all the
+ * details about the connection are held in a systemwide policy database and
+ * are keyed by the streamtype field... the user of the communication channel
+ * does not know or manage the choice of endpoint, tls CA, or even wire
+ * protocol.  The advantage is he then does not have any dependency on any of
+ * those and they can be changed just by changing the policy database without
+ * touching the code using the stream.
+ *
+ * There are two ways secure streams interfaces to user code:
+ *
+ * 1) [Linux / RTOS] the natural, smallest interface is to call back to user
+ *    code that only operates directly from the lws event loop thread context
+ *    (direct callbacks from lws_ss_t)
+ *
+ *    lws_thread( [user code] ---- lws )
+ *
+ * 2) [Linux] where the user code is in a different process and communicates
+ *    asynchronously via a proxy socket
+ *
+ *    user_process{ [user code] | shim | socket-}------ lws_process{ lws }
+ *
+ * In the second, IPC, case, all packets are prepended by one or more bytes
+ * indicating the packet type and serializing any associated data, known as
+ * Serialized Secure Streams or SSS.
+ *
+ * Serialized Secure Streams
+ * -------------------------
+ *
+ * On the transport, adjacent packets may be coalesced, that is, the original
+ * packet sizes are lost and two or more packets are combined.  For that reason
+ * the serialization format always contains a 1-byte type and then a 2-byte
+ * frame length.
+ *
+ * Client to proxy
+ *
+ * - Proxied connection setup
+ *
+ *   -  0: LWSSS_SER_TXPRE_STREAMTYPE
+ *   -  1: 2-byte MSB-first rest-of-frame length
+ *   -  3: 1-byte Client SSS protocol version (introduced in SSSv1)
+ *   -  4: 4-byte Client PID (introduced in SSSv1)
+ *   -  8: 4-byte MSB-first initial tx credit
+ *   - 12: the streamtype name with no NUL
+ *
+ * - Proxied tx
+ *
+ *   -  0: LWSSS_SER_TXPRE_TX_PAYLOAD
+ *   -  1: 2 byte MSB-first rest-of-frame length
+ *   -  3: 4-byte MSB-first flags
+ *   -  7: 4-byte MSB-first us between client requested write and wrote to proxy
+ *   - 11: 8-byte MSB-first us resolution unix time client wrote to proxy
+ *   - 19: payload
+ *
+ * - Proxied secure stream destroy
+ *
+ *   -  0: LWSSS_SER_TXPRE_DESTROYING
+ *   -  1: 00, 00
+ *
+ * - Proxied metadata - sent when one metadata item set clientside
+ *
+ *   -  0: LWSSS_SER_TXPRE_METADATA
+ *   -  1: 2-byte MSB-first rest-of-frame length
+ *   -  3: 1-byte metadata name length
+ *   -  4: metadata name
+ *   -  ...: metadata value (for rest of packet)
+ *
+ * - TX credit management - sent when using tx credit apis, cf METADATA
+ *
+ *   - 0: LWSSS_SER_TXPRE_TXCR_UPDATE
+ *   - 1: 2-byte MSB-first rest-of-frame length 00, 04
+ *   - 3: 4-byte additional tx credit adjust value
+ *
+ * - Stream timeout management - forwarded when user applying or cancelling t.o.
+ *
+ *   -  0: LWSSS_SER_TXPRE_TIMEOUT_UPDATE
+ *   -  1: 2-byte MSB-first rest-of-frame length 00, 04
+ *   -  3: 4-byte MSB-first unsigned 32-bit timeout, 0 = use policy, -1 = cancel
+ *
+ * - Passing up payload length hint
+ *
+ *   -  0: LWSSS_SER_TXPRE_PAYLOAD_LENGTH_HINT
+ *   -  1: 2-byte MSB-first rest-of-frame length 00, 04
+ *   -  3: 4-byte MSB-first unsigned 32-bit payload length hint
+ *
+ * Proxy to client
+ *
+ * - Proxied connection setup result
+ *
+ *   -  0: LWSSS_SER_RXPRE_CREATE_RESULT
+ *   -  1: 2 byte MSB-first rest-of-frame length (usually 00, 03)
+ *   -  3: 1 byte result, 0 = success.  On failure, proxy will close connection.
+ *   -  4: 4 byte client dsh allocation recommended for stream type, from policy
+ *         (introduced in SSSv1)
+ *   -  8: 2 byte MSB-first initial tx credit
+ *   - 10: if present, comma-sep list of rideshare types from policy
+ *
+ * - Proxied rx
+ *
+ *   -  0: LWSSS_SER_RXPRE_RX_PAYLOAD
+ *   -  1: 2 byte MSB-first rest-of-frame length
+ *   -  3: 4-byte MSB-first flags
+ *   -  7: 4-byte MSB-first us between inbound read and wrote to client
+ *   - 11: 8-byte MSB-first us resolution unix time proxy wrote to client
+ *   - 17: (rideshare name len + rideshare name if flags & LWSSS_FLAG_RIDESHARE)
+ *          payload
+ *
+ * - Proxied tx credit
+ *
+ *   -  0: LWSSS_SER_RXPRE_TXCR_UPDATE
+ *   -  1: 00, 04
+ *   -  3: 4-byte MSB-first addition tx credit bytes
+ *
+ * - Proxied rx metadata
+ *
+ *   -  0: LWSSS_SER_RXPRE_METADATA
+ *   -  1: 2-byte MSB-first rest-of-frame length
+ *   -  3: 1-byte metadata name length
+ *   -  4: metadata name
+ *   -  ...: metadata value (for rest of packet)
+ *
+ * - Proxied state (8 or 11 byte packet)
+ *
+ *   -  0: LWSSS_SER_RXPRE_CONNSTATE
+ *   -  1: 00, 05 if state < 256, else 00, 08
+ *   -  3: 1 byte state index if state < 256, else 4-byte MSB-first state index
+ *   -  4 or 7: 4-byte MSB-first ordinal
+ *
+ * - Proxied performance information
+ *
+ *   -  0: LWSSS_SER_RXPRE_PERF
+ *   -  1: 2-byte MSB-first rest-of-frame length
+ *   -  3: ... performance JSON (for rest of packet)
+ *
+ * Proxied tx may be read by the proxy but rejected due to lack of buffer space
+ * at the proxy.  For that reason, tx must be held at the sender until it has
+ * been acknowledged or denied.
+ *
+ * Sinks
+ * -----
+ *
+ * Sinks are logical "servers", you can register as a sink for a particular
+ * streamtype by using the lws_ss_create() api with ssi->register_sink set to 1.
+ *
+ * For directly fulfilled Secure Streams, new streams of that streamtype bind
+ * to the rx, tx and state handlers given when it was registered.
+ *
+ *  - When new streams are created the registered sink handler for (*state) is
+ *    called with event LWSSSCS_SINK_JOIN and the new client stream handle in
+ *    the h_src parameter.
+ *
+ *  - When the client stream sends something to the sink, it calls the sink's
+ *    (*rx) with the client stream's
+ */
+
+/** \defgroup secstr Secure Streams
+* ##Secure Streams
+*
+* Secure Streams related apis
+*/
+///@{
+
+#define LWS_SS_MTU 1540
+
+struct lws_ss_handle;
+typedef uint32_t lws_ss_tx_ordinal_t;
+
+/*
+ * connection state events
+ *
+ * If you add states, take care about the state names and state transition
+ * validity enforcement tables too
+ */
+typedef enum {
+	/* zero means unset */
+	LWSSSCS_CREATING		= 1,
+	LWSSSCS_DISCONNECTED,
+	LWSSSCS_UNREACHABLE,		/* oridinal arg = 1 = caused by dns
+					 * server reachability failure */
+	LWSSSCS_AUTH_FAILED,
+	LWSSSCS_CONNECTED,
+	LWSSSCS_CONNECTING,
+	LWSSSCS_DESTROYING,
+	LWSSSCS_POLL,
+	LWSSSCS_ALL_RETRIES_FAILED,	/* all retries in bo policy failed */
+	LWSSSCS_QOS_ACK_REMOTE,		/* remote peer received and acked tx */
+	LWSSSCS_QOS_NACK_REMOTE,
+	LWSSSCS_QOS_ACK_LOCAL,		/* local proxy accepted our tx */
+	LWSSSCS_QOS_NACK_LOCAL,		/* local proxy refused our tx */
+	LWSSSCS_TIMEOUT,		/* optional timeout timer fired */
+
+	LWSSSCS_SERVER_TXN,
+	LWSSSCS_SERVER_UPGRADE,		/* the server protocol upgraded */
+
+	LWSSSCS_EVENT_WAIT_CANCELLED, /* somebody called lws_cancel_service */
+
+	LWSSSCS_UPSTREAM_LINK_RETRY,	/* if we are being proxied over some
+					 * intermediate link, this transient
+					 * state may be sent to indicate we are
+					 * waiting to establish that link before
+					 * creation can proceed.. ack is the
+					 * number of ms we have been trying */
+
+	LWSSSCS_SINK_JOIN,		/* sinks get this when a new source
+					 * stream joins the sink */
+	LWSSSCS_SINK_PART,		/* sinks get this when a new source
+					 * stream leaves the sink */
+
+	LWSSSCS_USER_BASE = 1000
+} lws_ss_constate_t;
+
+enum {
+	LWSSS_FLAG_SOM						= (1 << 0),
+	/* payload contains the start of new message */
+	LWSSS_FLAG_EOM						= (1 << 1),
+	/* payload contains the end of message */
+	LWSSS_FLAG_POLL						= (1 << 2),
+	/* Not a real transmit... poll for rx if protocol needs it */
+	LWSSS_FLAG_RELATED_START				= (1 << 3),
+	/* Appears in a zero-length message indicating a message group of zero
+	 * or more messages is now starting. */
+	LWSSS_FLAG_RELATED_END					= (1 << 4),
+	/* Appears in a zero-length message indicating a message group of zero
+	 * or more messages has now finished. */
+	LWSSS_FLAG_RIDESHARE					= (1 << 5),
+	/* Serialized payload starts with non-default rideshare name length and
+	 * name string without NUL, then payload */
+	LWSSS_FLAG_PERF_JSON					= (1 << 6),
+	/* This RX is JSON performance data, only on streams with "perf" flag
+	 * set */
+
+	/*
+	 * In the case the secure stream is proxied across a process or thread
+	 * boundary, eg by proxying through a socket for IPC, metadata must be
+	 * carried in-band.  A byte is prepended to each rx payload to
+	 * differentiate what it is.
+	 *
+	 * Secure streams where the user is called back directly does not need
+	 * any of this and only pure payloads are passed.
+	 *
+	 * rx (received by client) prepends for proxied connections
+	 */
+
+	LWSSS_SER_RXPRE_RX_PAYLOAD				= 0x55,
+	LWSSS_SER_RXPRE_CREATE_RESULT,
+	LWSSS_SER_RXPRE_CONNSTATE,
+	LWSSS_SER_RXPRE_TXCR_UPDATE,
+	LWSSS_SER_RXPRE_METADATA,
+	LWSSS_SER_RXPRE_TLSNEG_ENCLAVE_SIGN,
+	LWSSS_SER_RXPRE_PERF,
+
+	/* tx (send by client) prepends for proxied connections */
+
+	LWSSS_SER_TXPRE_STREAMTYPE				= 0xaa,
+	LWSSS_SER_TXPRE_ONWARD_CONNECT,
+	LWSSS_SER_TXPRE_DESTROYING,
+	LWSSS_SER_TXPRE_TX_PAYLOAD,
+	LWSSS_SER_TXPRE_METADATA,
+	LWSSS_SER_TXPRE_TXCR_UPDATE,
+	LWSSS_SER_TXPRE_TIMEOUT_UPDATE,
+	LWSSS_SER_TXPRE_PAYLOAD_LENGTH_HINT,
+	LWSSS_SER_TXPRE_TLSNEG_ENCLAVE_SIGNED,
+};
+
+typedef enum {
+	LPCSPROX_WAIT_INITIAL_TX = 1, /* after connect, must send streamtype */
+	LPCSPROX_REPORTING_FAIL, /* stream creation failed, wait to to tell */
+	LPCSPROX_REPORTING_OK, /* stream creation succeeded, wait to to tell */
+	LPCSPROX_OPERATIONAL, /* ready for payloads */
+	LPCSPROX_DESTROYED,
+
+	LPCSCLI_SENDING_INITIAL_TX,  /* after connect, must send streamtype */
+	LPCSCLI_WAITING_CREATE_RESULT,   /* wait to hear if proxy ss create OK */
+	LPCSCLI_LOCAL_CONNECTED,	      /* we are in touch with the proxy */
+	LPCSCLI_ONWARD_CONNECT,	      /* request onward ss connection */
+	LPCSCLI_OPERATIONAL, /* ready for payloads */
+
+} lws_ss_conn_states_t;
+
+/*
+ * Returns from state() callback can tell the caller what the user code
+ * wants to do
+ */
+
+typedef enum lws_ss_state_return {
+	LWSSSSRET_TX_DONT_SEND		=  1, /* (*tx) only, or failure */
+
+	LWSSSSRET_OK			=  0, /* no error */
+	LWSSSSRET_DISCONNECT_ME		= -1, /* caller should disconnect us */
+	LWSSSSRET_DESTROY_ME		= -2, /* caller should destroy us */
+} lws_ss_state_return_t;
+
+/**
+ * lws_ss_info_t: information about stream to be created
+ *
+ * Prepare this struct with information about what the stream type is and how
+ * the stream should interface with your code, and pass it to lws_ss_create()
+ * to create the requested stream.
+ */
+
+enum {
+	LWSSSINFLAGS_REGISTER_SINK			=	(1 << 0),
+	/**< If set, we're not creating a specific stream, but registering
+	 * ourselves as the "sink" for .streamtype.  It's analogous to saying
+	 * we want to be the many-to-one "server" for .streamtype; when other
+	 * streams are created with that streamtype, they should be forwarded
+	 * to this stream owner, where they join and part from the sink via
+	 * (*state) LWSSSCS_SINK_JOIN / _PART events, the new client handle
+	 * being provided in the h_src parameter.
+	 */
+	LWSSSINFLAGS_PROXIED				=	(1 << 1),
+	/**< Set if the stream is being created as a stand-in at the proxy */
+	LWSSSINFLAGS_SERVER				=	(1 << 2),
+	/**< Set on the server object copy of the ssi / info to indicate that
+	 * stream creation using this ssi is for Accepted connections belonging
+	 * to a server */
+	LWSSSINFLAGS_ACCEPTED				=	(1 << 3),
+	/**< Set on the accepted object copy of the ssi / info to indicate that
+	 * we are an accepted connection from a server's listening socket */
+};
+
+typedef lws_ss_state_return_t (*lws_sscb_rx)(void *userobj, const uint8_t *buf,
+					     size_t len, int flags);
+typedef lws_ss_state_return_t (*lws_sscb_tx)(void *userobj,
+					     lws_ss_tx_ordinal_t ord,
+					     uint8_t *buf, size_t *len,
+					     int *flags);
+typedef lws_ss_state_return_t (*lws_sscb_state)(void *userobj, void *h_src,
+						lws_ss_constate_t state,
+						lws_ss_tx_ordinal_t ack);
+
+#if defined(LWS_WITH_SECURE_STREAMS_BUFFER_DUMP)
+typedef void (*lws_ss_buffer_dump_cb)(void *userobj, const uint8_t *buf,
+		size_t len, int done);
+#endif
+
+struct lws_ss_policy;
+
+typedef struct lws_ss_info {
+	const char *streamtype; /**< type of stream we want to create */
+	size_t	    user_alloc; /**< size of user allocation */
+	size_t	    handle_offset; /**< offset of handle stg in user_alloc type,
+				    set to offsetof(mytype, my_handle_member) */
+	size_t	    opaque_user_data_offset;
+	/**< offset of opaque user data ptr in user_alloc type, set to
+	     offsetof(mytype, opaque_ud_member) */
+
+#if defined(LWS_WITH_SECURE_STREAMS_CPP)
+	const struct lws_ss_policy	*policy;
+	/**< Normally NULL, or a locally-generated policy to apply to this
+	 * connection instead of a named streamtype */
+#endif
+
+#if defined(LWS_WITH_SYS_FAULT_INJECTION)
+	lws_fi_ctx_t				fic;
+	/**< Attach external Fault Injection context to the stream, hierarchy
+	 * is ss->context */
+#endif
+
+	lws_sscb_rx rx;
+	/**< callback with rx payload for this stream */
+	lws_sscb_tx tx;
+	/**< callback to send payload on this stream... 0 = send as set in
+	 * len and flags, 1 = do not send anything (ie, not even 0 len frame) */
+	lws_sscb_state state;
+	/**< advisory cb about state of stream and QoS status if applicable...
+	 * h_src is only used with sinks and LWSSSCS_SINK_JOIN/_PART events.
+	 * Return nonzero to indicate you want to destroy the stream. */
+#if defined(LWS_WITH_SECURE_STREAMS_BUFFER_DUMP)
+	lws_ss_buffer_dump_cb dump;
+	/**< cb to record needed protocol buffer data*/
+#endif
+	int	    manual_initial_tx_credit;
+	/**< 0 = manage any tx credit automatically, nonzero explicitly sets the
+	 * peer stream to have the given amount of tx credit, if the protocol
+	 * can support it.
+	 *
+	 * In the special case of _lws_smd streamtype, this is used to indicate
+	 * the connection's rx class mask.
+	 * */
+	uint32_t	client_pid;
+	/**< used in proxy / serialization case to hold the client pid this
+	 * proxied connection is to be tagged with
+	 */
+	uint8_t		flags;
+	uint8_t		sss_protocol_version;
+	/**< used in proxy / serialization case to hold the SS serialization
+	 * protocol level to use with this peer... clients automatically request
+	 * the most recent version they were built with
+	 * (LWS_SSS_CLIENT_PROTOCOL_VERSION) and the proxy stores the requested
+	 * version in here
+	 */
+
+} lws_ss_info_t;
+
+/**
+ * lws_ss_create() - Create secure stream
+ *
+ * \param context: the lws context to create this inside
+ * \param tsi: service thread index to create on (normally 0)
+ * \param ssi: pointer to lws_ss_info_t filled in with info about desired stream
+ * \param opaque_user_data: opaque data to set in the stream's user object
+ * \param ppss: pointer to secure stream handle pointer set on exit
+ * \param ppayload_fmt: NULL or pointer to a string ptr to take payload format
+ *			name from the policy
+ *
+ * Requests a new secure stream described by \p ssi be created.  If successful,
+ * the stream is created, its state callback called with LWSSSCS_CREATING, \p *ppss
+ * is set to point to the handle, and it returns 0.  If it failed, it returns
+ * nonzero.
+ *
+ * Along with the opaque stream object, streams overallocate
+ *
+ * 1) a user data struct whose size is set in ssi
+ * 2) nauth plugin instantiation data (size set in the plugin struct)
+ * 3) sauth plugin instantiation data (size set in the plugin struct)
+ * 4) space for a copy of the stream type name
+ *
+ * The user data struct is initialized to all zeros, then the .handle_offset and
+ * .opaque_user_data_offset fields of the ssi are used to prepare the user data
+ * struct with the ss handle that was created, and a copy of the
+ * opaque_user_data pointer given as an argument.
+ *
+ * If you want to set up the stream with specific information, point to it in
+ * opaque_user_data and use the copy of that pointer in your user data member
+ * for it starting from the LWSSSCS_CREATING state call.
+ *
+ * Since different endpoints chosen by the policy may require different payload
+ * formats, \p ppayload_fmt is set to point to the name of the needed payload
+ * format from the policy database if non-NULL.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_ss_create(struct lws_context *context, int tsi, const lws_ss_info_t *ssi,
+	      void *opaque_user_data, struct lws_ss_handle **ppss,
+	      struct lws_sequencer *seq_owner, const char **ppayload_fmt);
+
+/**
+ * lws_ss_destroy() - Destroy secure stream
+ *
+ * \param ppss: pointer to lws_ss_t pointer to be destroyed
+ *
+ * Destroys the lws_ss_t pointed to by \p *ppss, and sets \p *ppss to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ss_destroy(struct lws_ss_handle **ppss);
+
+/**
+ * lws_ss_request_tx() - Schedule stream for tx
+ *
+ * \param pss: pointer to lws_ss_t representing stream that wants to transmit
+ *
+ * Schedules a write on the stream represented by \p pss.  When it's possible to
+ * write on this stream, the \p *tx callback will occur with an empty buffer for
+ * the stream owner to fill in.
+ *
+ * Returns 0 or LWSSSSRET_DESTROY_ME
+ */
+LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT
+lws_ss_request_tx(struct lws_ss_handle *pss);
+
+/**
+ * lws_ss_request_tx() - Schedule stream for tx
+ *
+ * \param pss: pointer to lws_ss_t representing stream that wants to transmit
+ * \param len: the length of the write in bytes
+ *
+ * Schedules a write on the stream represented by \p pss.  When it's possible to
+ * write on this stream, the \p *tx callback will occur with an empty buffer for
+ * the stream owner to fill in.
+ *
+ * This api variant should be used when it's possible the payload will go out
+ * over h1 with x-web-form-urlencoded or similar Content-Type.
+ */
+LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT
+lws_ss_request_tx_len(struct lws_ss_handle *pss, unsigned long len);
+
+/**
+ * lws_ss_client_connect() - Attempt the client connect
+ *
+ * \param h: secure streams handle
+ *
+ * Starts the connection process for the secure stream.
+ *
+ * Can return any of the lws_ss_state_return_t values depending on user
+ * state callback returns.
+ *
+ * LWSSSSRET_OK means the connection is ongoing.
+ *
+ */
+LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT
+lws_ss_client_connect(struct lws_ss_handle *h);
+
+/**
+ * lws_ss_get_sequencer() - Return parent sequencer pointer if any
+ *
+ * \param h: secure streams handle
+ *
+ * Returns NULL if the secure stream is not associated with a sequencer.
+ * Otherwise returns a pointer to the owning sequencer.  You can use this to
+ * identify which sequencer to direct messages to, from the secure stream
+ * callback.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
+lws_ss_get_sequencer(struct lws_ss_handle *h);
+
+/**
+ * lws_ss_proxy_create() - Start a unix domain socket proxy for Secure Streams
+ *
+ * \param context: lws_context
+ * \param bind: if port is 0, unix domain path with leading @ for abstract.
+ *		if port nonzero, NULL, or network interface to bind listen to
+ * \param port: tcp port to listen on
+ *
+ * Creates a vhost that listens either on an abstract namespace unix domain
+ * socket (port = 0) or a tcp listen socket (port nonzero).  If bind is NULL
+ * and port is 0, the abstract unix domain socket defaults to "proxy.ss.lws".
+ *
+ * Client connections to this proxy to Secure Streams are fulfilled using the
+ * policy local to the proxy and the data passed between the client and the
+ * proxy using serialized Secure Streams protocol.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_proxy_create(struct lws_context *context, const char *bind, int port);
+
+/**
+ * lws_ss_state_name() - convenience helper to get a printable conn state name
+ *
+ * \param state: the connection state index
+ *
+ * Returns a printable name for the connection state index passed in.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_ss_state_name(int state);
+
+/**
+ * lws_ss_get_context() - convenience helper to recover the lws context
+ *
+ * \param h: secure streams handle
+ *
+ * Returns the lws context.  Dispenses with the need to pass a copy of it into
+ * your secure streams handler.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_context *
+lws_ss_get_context(struct lws_ss_handle *h);
+
+#define LWSSS_TIMEOUT_FROM_POLICY				0
+
+/**
+ * lws_ss_start_timeout() - start or restart the timeout on the stream
+ *
+ * \param h: secure streams handle
+ * \param timeout_ms: LWSSS_TIMEOUT_FROM_POLICY for policy value, else use timeout_ms
+ *
+ * Starts or restarts the stream's own timeout timer.  If the specified time
+ * passes without lws_ss_cancel_timeout() being called on the stream, then the
+ * stream state callback receives LWSSSCS_TIMEOUT
+ *
+ * The process being protected by the timeout is up to the user code, it may be
+ * arbitrarily long and cross multiple protocol transactions or involve other
+ * streams.  It's up to the user to decide when to start and when / if to cancel
+ * the stream timeout.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ss_start_timeout(struct lws_ss_handle *h, unsigned int timeout_ms);
+
+/**
+ * lws_ss_cancel_timeout() - remove any timeout on the stream
+ *
+ * \param h: secure streams handle
+ *
+ * Disable any timeout that was applied to the stream by lws_ss_start_timeout().
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ss_cancel_timeout(struct lws_ss_handle *h);
+
+/**
+ * lws_ss_to_user_object() - convenience helper to get user object from handle
+ *
+ * \param h: secure streams handle
+ *
+ * Returns the user allocation related to the handle.  Normally you won't need
+ * this since it's available in the rx, tx and state callbacks as "userdata"
+ * already.
+ */
+LWS_VISIBLE LWS_EXTERN void *
+lws_ss_to_user_object(struct lws_ss_handle *h);
+
+/**
+ * lws_ss_rideshare() - find the current streamtype when types rideshare
+ *
+ * \param h: the stream handle
+ *
+ * Under some conditions, the payloads may be structured using protocol-
+ * specific formatting, eg, http multipart mime.  It's possible to map the
+ * logical partitions in the payload to different stream types using
+ * the policy "rideshare" feature.
+ *
+ * This api lets the callback code find out which rideshare stream type the
+ * current payload chunk belongs to.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_ss_rideshare(struct lws_ss_handle *h);
+
+
+/**
+ * lws_ss_set_metadata() - allow user to bind external data to defined ss metadata
+ *
+ * \param h: secure streams handle
+ * \param name: metadata name from the policy
+ * \param value: pointer to user-managed data to bind to name
+ * \param len: length of the user-managed data in value
+ *
+ * Binds user-managed data to the named metadata item from the ss policy.
+ * If present, the metadata item is handled in a protocol-specific way using
+ * the associated policy information.  For example, in the policy
+ *
+ *  	"\"metadata\":"		"["
+ *		"{\"uptag\":"  "\"X-Upload-Tag:\"},"
+ *		"{\"ctype\":"  "\"Content-Type:\"},"
+ *		"{\"xctype\":" "\"\"}"
+ *	"],"
+ *
+ * when the policy is using h1 is interpreted to add h1 headers of the given
+ * name with the value of the metadata on the left.
+ *
+ * Return 0 if OK or nonzero if, eg, metadata name does not exist on the
+ * streamtype.  You must check the result of this, eg, transient OOM can cause
+ * these to fail and you should retry later.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_ss_set_metadata(struct lws_ss_handle *h, const char *name,
+		    const void *value, size_t len);
+
+/**
+ * lws_ss_alloc_set_metadata() - copy data and bind to ss metadata
+ *
+ * \param h: secure streams handle
+ * \param name: metadata name from the policy
+ * \param value: pointer to user-managed data to bind to name
+ * \param len: length of the user-managed data in value
+ *
+ * Same as lws_ss_set_metadata(), but allocates a heap buffer for the data
+ * first and takes a copy of it, so the original can go out of scope
+ * immediately after.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_ss_alloc_set_metadata(struct lws_ss_handle *h, const char *name,
+			  const void *value, size_t len);
+
+/**
+ * lws_ss_get_metadata() - get current value of stream metadata item
+ *
+ * \param h: secure streams handle
+ * \param name: metadata name from the policy
+ * \param value: pointer to pointer to be set to point at the value
+ * \param len: pointer to size_t to set to the length of the value
+ *
+ * Binds user-managed data to the named metadata item from the ss policy.
+ * If present, the metadata item is handled in a protocol-specific way using
+ * the associated policy information.  For example, in the policy
+ *
+ *  	"\"metadata\":"		"["
+ *		"{\"uptag\":"  "\"X-Upload-Tag:\"},"
+ *		"{\"ctype\":"  "\"Content-Type:\"},"
+ *		"{\"xctype\":" "\"\"}"
+ *	"],"
+ *
+ * when the policy is using h1 is interpreted to add h1 headers of the given
+ * name with the value of the metadata on the left.
+ *
+ * Return 0 if \p *value and \p *len set OK, or nonzero if, eg, metadata \p name does
+ * not exist on the streamtype.
+ *
+ * The pointed-to values may only exist until the next time around the event
+ * loop.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_get_metadata(struct lws_ss_handle *h, const char *name,
+		    const void **value, size_t *len);
+
+/**
+ * lws_ss_server_ack() - indicate how we feel about what the server has sent
+ *
+ * \param h: ss handle of accepted connection
+ * \param nack: 0 means we are OK with it, else some problem
+ *
+ * For SERVER secure streams
+ *
+ * Depending on the protocol, the server sending us something may be
+ * transactional, ie, built into it sending something is the idea we will
+ * respond somehow out-of-band; HTTP is like this with, eg, 200 response code.
+ *
+ * Calling this with nack=0 indicates that when we later respond, we want to
+ * acknowledge the transaction (eg, it means a 200 if http underneath), if
+ * nonzero that the transaction should act like it failed.
+ *
+ * If the underlying protocol doesn't understand transactions (eg, ws) then this
+ * has no effect either way.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ss_server_ack(struct lws_ss_handle *h, int nack);
+
+typedef void (*lws_sssfec_cb)(struct lws_ss_handle *h, void *arg);
+
+/**
+ * lws_ss_server_foreach_client() - callback for each live client connected to server
+ *
+ * \param h: server ss handle
+ * \param cb: the callback
+ * \param arg: arg passed to callback
+ *
+ * For SERVER secure streams
+ *
+ * Call the callback \p cb once for each client ss connected to the server,
+ * passing \p arg as an additional callback argument each time.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ss_server_foreach_client(struct lws_ss_handle *h, lws_sssfec_cb cb,
+			     void *arg);
+
+/**
+ * lws_ss_change_handlers() - helper for dynamically changing stream handlers
+ *
+ * \param h: ss handle
+ * \param rx: the new RX handler
+ * \param tx: the new TX handler
+ * \param state: the new state handler
+ *
+ * Handlers set to NULL are left unchanged.
+ *
+ * This works on any handle, client or server and takes effect immediately.
+ *
+ * Depending on circumstances this may be helpful when
+ *
+ * a) a server stream undergoes an LWSSSCS_SERVER_UPGRADE (as in http -> ws) and
+ * the payloads in the new protocol have a different purpose that is best
+ * handled in their own rx and tx callbacks, and
+ *
+ * b) you may want to serve several different, possibly large things based on
+ * what was requested.  Setting a customized handler allows clean encapsulation
+ * of the different serving strategies.
+ *
+ * If the stream is long-lived, like ws, you should set the changed handler back
+ * to the default when the transaction wanting it is completed.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_ss_change_handlers(struct lws_ss_handle *h, lws_sscb_rx rx, lws_sscb_tx tx,
+		       lws_sscb_state state);
+
+/**
+ * lws_ss_add_peer_tx_credit() - allow peer to transmit more to us
+ *
+ * \param h: secure streams handle
+ * \param add: additional tx credit (signed)
+ *
+ * Indicate to remote peer that we can accept \p add bytes more payload being
+ * sent to us.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_add_peer_tx_credit(struct lws_ss_handle *h, int32_t add);
+
+/**
+ * lws_ss_get_est_peer_tx_credit() - get our current estimate of peer's tx credit
+ *
+ * \param h: secure streams handle
+ *
+ * Based on what credit we gave it, and what we have received, report our
+ * estimate of peer's tx credit usable to transmit to us.  This may be outdated
+ * in that some or all of its credit may already have been expended by sending
+ * stuff to us that is in flight already.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_get_est_peer_tx_credit(struct lws_ss_handle *h);
+
+LWS_VISIBLE LWS_EXTERN const char *
+lws_ss_tag(struct lws_ss_handle *h);
+
+
+#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
+/**
+ * lws_ss_sigv4_set_aws_key() - set aws credential into system blob
+ *
+ * \param context: lws_context
+ * \param idx:     the system blob index specified in the policy, currently
+ *                  up to 4 blobs.
+ * \param keyid:   aws access keyid
+ * \param key:     aws access key
+ *
+ * Return 0 if OK or nonzero if e.g. idx is invalid; system blob heap appending
+ * fails.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_ss_sigv4_set_aws_key(struct lws_context* context, uint8_t idx,
+		                const char * keyid, const char * key);
+
+/**
+ * lws_aws_filesystem_credentials_helper() - read aws credentials from file
+ *
+ * \param path: path to read, ~ at start is converted to $HOME contents if any
+ * \param kid: eg, "aws_access_key_id"
+ * \param ak: eg, "aws_secret_access_key"
+ * \param aws_keyid: pointer to pointer for allocated keyid from credentials file
+ * \param aws_key: pointer to pointer for allocated key from credentials file
+ *
+ * Return 0 if both *aws_keyid and *aws_key allocated from the config file, else
+ * nonzero, and neither *aws_keyid or *aws_key are allocated.
+ *
+ * If *aws_keyid and *aws_key are set, it's the user's responsibility to
+ * free() them when they are no longer needed.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_aws_filesystem_credentials_helper(const char *path, const char *kid,
+				      const char *ak, char **aws_keyid,
+				      char **aws_key);
+
+#endif
+
+///@}
+

include/libwebsockets/lws-sequencer.h

@@ -0,0 +1,243 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * lws_sequencer is intended to help implement sequences that:
+ *
+ *  - outlive a single connection lifetime,
+ *  - are not associated with a particular protocol,
+ *  - are not associated with a particular vhost,
+ *  - must receive and issue events inside the event loop
+ *
+ * lws_sequencer-s are bound to a pt (per-thread) which for the default case of
+ * one service thread is the same as binding to an lws_context.
+ */
+/*
+ * retry backoff table... retry n happens after .retry_ms_table[n] ms, with
+ * the last entry used if n is greater than the number of entries.
+ *
+ * The first .conceal_count retries are concealed, but after that the failures
+ * are reported.
+ */
+
+typedef enum {
+	LWSSEQ_CREATED,		/* sequencer created */
+	LWSSEQ_DESTROYED,	/* sequencer destroyed */
+	LWSSEQ_TIMED_OUT,	/* sequencer timeout */
+	LWSSEQ_HEARTBEAT,	/* 1Hz callback */
+
+	LWSSEQ_WSI_CONNECTED,	/* wsi we bound to us has connected */
+	LWSSEQ_WSI_CONN_FAIL,	/* wsi we bound to us has failed to connect */
+	LWSSEQ_WSI_CONN_CLOSE,	/* wsi we bound to us has closed */
+
+
+	LWSSEQ_SS_STATE_BASE,	/* secure streams owned by a sequencer provide
+				 * automatic messages about state changes on
+				 * the sequencer, passing the oridinal in the
+				 * event argument field.  The message index is
+				 * LWSSEQ_SS_STATE_BASE + the enum from
+				 * lws_ss_constate_t */
+
+	LWSSEQ_USER_BASE = 100	/* define your events from here */
+} lws_seq_events_t;
+
+typedef enum lws_seq_cb_return {
+	LWSSEQ_RET_CONTINUE,
+	LWSSEQ_RET_DESTROY
+} lws_seq_cb_return_t;
+
+/*
+ * handler for this sequencer.  Return 0 if OK else nonzero to destroy the
+ * sequencer.  LWSSEQ_DESTROYED will be called back to the handler so it can
+ * close / destroy any private assets associated with the sequence.
+ *
+ * The callback may return either LWSSEQ_RET_CONTINUE for the sequencer to
+ * resume or LWSSEQ_RET_DESTROY to indicate the sequence is finished.
+ *
+ * Event indexes consist of some generic ones but mainly user-defined ones
+ * starting from LWSSEQ_USER_BASE.
+ */
+typedef lws_seq_cb_return_t (*lws_seq_event_cb)(struct lws_sequencer *seq,
+			     void *user, int event, void *data, void *aux);
+
+typedef struct lws_seq_info {
+	struct lws_context		*context;   /* lws_context for seq */
+	int				tsi;	    /* thread service idx */
+	size_t				user_size;  /* size of user alloc */
+	void				**puser;    /* place ptr to user */
+	lws_seq_event_cb		cb;	    /* seq callback */
+	const char			*name;	    /* seq name */
+	const lws_retry_bo_t		*retry;	    /* retry policy */
+	uint8_t				wakesuspend:1; /* important enough to
+						     * wake system */
+} lws_seq_info_t;
+
+/**
+ * lws_seq_create() - create and bind sequencer to a pt
+ *
+ * \param info:	information about sequencer to create
+ *
+ * This binds an abstract sequencer to a per-thread (by default, the single
+ * event loop of an lws_context).  After the event loop starts, the sequencer
+ * will receive an LWSSEQ_CREATED event on its callback from the event loop
+ * context, where it can begin its sequence flow.
+ *
+ * Lws itself will only call the callback subsequently with LWSSEQ_DESTROYED
+ * when the sequencer is being destroyed.
+ *
+ * pt locking is used to protect the related data structures.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
+lws_seq_create(lws_seq_info_t *info);
+
+/**
+ * lws_seq_destroy() - destroy the sequencer
+ *
+ * \param seq: pointer to the the opaque sequencer pointer returned by
+ *	       lws_seq_create()
+ *
+ * This proceeds to destroy the sequencer, calling LWSSEQ_DESTROYED and then
+ * freeing the sequencer object itself.  The pointed-to seq pointer will be
+ * set to NULL.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_seq_destroy(struct lws_sequencer **seq);
+
+/**
+ * lws_seq_queue_event() - queue an event on the given sequencer
+ *
+ * \param seq: the opaque sequencer pointer returned by lws_seq_create()
+ * \param e: the event index to queue
+ * \param data: associated opaque (to lws) data to provide the callback
+ * \param aux: second opaque data to provide the callback
+ *
+ * This queues the event on a given sequencer.  Queued events are delivered one
+ * per sequencer each subsequent time around the event loop, so the cb is called
+ * from the event loop thread context.
+ *
+ * Notice that because the events are delivered in order from the event loop,
+ * the scope of objects pointed to by \p data or \p aux may exceed the lifetime
+ * of the thing containing the pointed-to data.  So it's usually better to pass
+ * values here.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_seq_queue_event(struct lws_sequencer *seq, lws_seq_events_t e, void *data,
+			  void *aux);
+
+/**
+ * lws_seq_check_wsi() - check if wsi still extant
+ *
+ * \param seq: the sequencer interested in the wsi
+ * \param wsi: the wsi we want to confirm hasn't closed yet
+ *
+ * Check if wsi still extant, by peeking in the message queue for a
+ * LWSSEQ_WSI_CONN_CLOSE message about wsi.  (Doesn't need to do the same for
+ * CONN_FAIL since that will never have produced any messages prior to that).
+ *
+ * Use this to avoid trying to perform operations on wsi that have already
+ * closed but we didn't get to that message yet.
+ *
+ * Returns 0 if not closed yet or 1 if it has closed but we didn't process the
+ * close message yet.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_seq_check_wsi(struct lws_sequencer *seq, struct lws *wsi);
+
+#define LWSSEQTO_NONE 0
+
+/**
+ * lws_seq_timeout_us() - set a timeout by which the sequence must have
+ *				completed by a different event or inform the
+ *				sequencer
+ *
+ * \param seq: The sequencer to set the timeout on
+ * \param us: How many us in the future to fire the timeout
+ *		LWS_SET_TIMER_USEC_CANCEL = cancel any existing timeout
+ *
+ * This api allows the sequencer to ask to be informed if it has not completed
+ * or disabled its timeout after secs seconds.  Lws will send a LWSSEQ_TIMED_OUT
+ * event to the sequencer if the timeout expires.
+ *
+ * Typically the sequencer sets the timeout when starting a step, then waits to
+ * hear a queued event informing it the step completed or failed.  The timeout
+ * provides a way to deal with the case the step neither completed nor failed
+ * within the timeout period.
+ *
+ * Lws wsi timeouts are not really suitable for this since they are focused on
+ * short-term protocol timeout protection and may be set and reset many times
+ * in one transaction.  Wsi timeouts also enforce closure of the wsi when they
+ * trigger, sequencer timeouts have no side effect except to queue the
+ * LWSSEQ_TIMED_OUT message and leave it to the sequencer to decide how to
+ * react appropriately.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_seq_timeout_us(struct lws_sequencer *seq, lws_usec_t us);
+
+/**
+ * lws_seq_from_user(): get the lws_seq_t pointer from the user ptr
+ *
+ * \param u: the sequencer user allocation returned by lws_seq_create() or
+ *	     provided in the sequencer callback
+ *
+ * This gets the lws_seq_t * from the sequencer user allocation pointer.
+ * Actually these are allocated at the same time in one step, with the user
+ * allocation immediately after the lws_seq_t, so lws can compute where
+ * the lws_seq_t is from having the user allocation pointer.  Since the
+ * size of the lws_seq_t is unknown to user code, this helper does it for
+ * you.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
+lws_seq_from_user(void *u);
+
+/**
+ * lws_seq_us_since_creation(): elapsed seconds since sequencer created
+ *
+ * \param seq: pointer to the lws_seq_t
+ *
+ * Returns the number of us elapsed since the lws_seq_t was
+ * created.  This is useful to calculate sequencer timeouts for the current
+ * step considering a global sequencer lifetime limit.
+ */
+LWS_VISIBLE LWS_EXTERN lws_usec_t
+lws_seq_us_since_creation(struct lws_sequencer *seq);
+
+/**
+ * lws_seq_name(): get the name of this sequencer
+ *
+ * \param seq: pointer to the lws_seq_t
+ *
+ * Returns the name given when the sequencer was created.  This is useful to
+ * annotate logging when then are multiple sequencers in play.
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_seq_name(struct lws_sequencer *seq);
+
+/**
+ * lws_seq_get_context(): get the lws_context sequencer was created on
+ *
+ * \param seq: pointer to the lws_seq_t
+ *
+ * Returns the lws_context.  Saves you having to store it if you have a seq
+ * pointer handy.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_context *
+lws_seq_get_context(struct lws_sequencer *seq);

include/libwebsockets/lws-service.h

@@ -0,0 +1,202 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup service Built-in service loop entry
+ *
+ * ##Built-in service loop entry
+ *
+ * If you're not using libev / libuv, these apis are needed to enter the poll()
+ * wait in lws and service any connections with pending events.
+ */
+///@{
+
+/**
+ * lws_service() - Service any pending websocket activity
+ * \param context:	Websocket context
+ * \param timeout_ms:	Set to 0; ignored; for backward compatibility
+ *
+ *	This function deals with any pending websocket traffic, for three
+ *	kinds of event.  It handles these events on both server and client
+ *	types of connection the same.
+ *
+ *	1) Accept new connections to our context's server
+ *
+ *	2) Call the receive callback for incoming frame data received by
+ *	    server or client connections.
+ *
+ *  Since v3.2 internally the timeout wait is ignored, the lws scheduler is
+ *  smart enough to stay asleep until an event is queued.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_service(struct lws_context *context, int timeout_ms);
+
+/**
+ * lws_service_tsi() - Service any pending websocket activity
+ *
+ * \param context:	Websocket context
+ * \param timeout_ms:	Set to 0; ignored; for backwards compatibility
+ * \param tsi:		Thread service index, starting at 0
+ *
+ * Same as lws_service(), but for a specific thread service index.  Only needed
+ * if you are spawning multiple service threads that operate on the same lws_context.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_service_tsi(struct lws_context *context, int timeout_ms, int tsi);
+
+/**
+ * lws_cancel_service_pt() - Cancel servicing of pending socket activity
+ *				on one thread
+ * \param wsi:	Cancel service on the thread this wsi is serviced by
+ *
+ * Same as lws_cancel_service(), but targets a single service thread, the one
+ * the wsi belongs to.  You probably want to use lws_cancel_service() instead.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_cancel_service_pt(struct lws *wsi);
+
+/**
+ * lws_cancel_service() - Cancel wait for new pending socket activity
+ * \param context:	Websocket context
+ *
+ * This function creates an immediate "synchronous interrupt" to the lws poll()
+ * wait or event loop.  As soon as possible in the serialzed service sequencing,
+ * a LWS_CALLBACK_EVENT_WAIT_CANCELLED callback is sent to every protocol on
+ * every vhost.
+ *
+ * lws_cancel_service() may be called from another thread while the context
+ * exists, and its effect will be immediately serialized.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_cancel_service(struct lws_context *context);
+
+/**
+ * lws_service_fd() - Service polled socket with something waiting
+ * \param context:	Websocket context
+ * \param pollfd:	The pollfd entry describing the socket fd and which events
+ *		happened
+ *
+ * This function takes a pollfd that has POLLIN or POLLOUT activity and
+ * services it according to the state of the associated
+ * struct lws.
+ *
+ * The one call deals with all "service" that might happen on a socket
+ * including listen accepts, http files as well as websocket protocol.
+ *
+ * If a pollfd says it has something, you can just pass it to
+ * lws_service_fd() whether it is a socket handled by lws or not.
+ * If it sees it is a lws socket, the traffic will be handled and
+ * pollfd->revents will be zeroed now.
+ *
+ * If the socket is foreign to lws, it leaves revents alone.  So you can
+ * see if you should service yourself by checking the pollfd revents
+ * after letting lws try to service it.
+ *
+ * lws before v3.2 allowed pollfd to be NULL, to indicate that background
+ * periodic processing should be done.  Since v3.2, lws schedules any items
+ * that need handling in the future using lws_sul and NULL is no longer valid.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_service_fd(struct lws_context *context, struct lws_pollfd *pollfd);
+
+/**
+ * lws_service_fd_tsi() - Service polled socket in specific service thread
+ * \param context:	Websocket context
+ * \param pollfd:	The pollfd entry describing the socket fd and which events
+ *		happened.
+ * \param tsi: thread service index
+ *
+ * Same as lws_service_fd() but used with multiple service threads
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_service_fd_tsi(struct lws_context *context, struct lws_pollfd *pollfd,
+		   int tsi);
+
+/**
+ * lws_service_adjust_timeout() - Check for any connection needing forced service
+ * \param context:	Websocket context
+ * \param timeout_ms:	The original poll timeout value.  You can just set this
+ *			to 1 if you don't really have a poll timeout.
+ * \param tsi: thread service index
+ *
+ * Under some conditions connections may need service even though there is no
+ * pending network action on them, this is "forced service".  For default
+ * poll() and libuv / libev, the library takes care of calling this and
+ * dealing with it for you.  But for external poll() integration, you need
+ * access to the apis.
+ *
+ * If anybody needs "forced service", returned timeout is zero.  In that case,
+ * you can call lws_service_tsi() with a timeout of -1 to only service
+ * guys who need forced service.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_service_adjust_timeout(struct lws_context *context, int timeout_ms, int tsi);
+
+/* Backwards compatibility */
+#define lws_plat_service_tsi lws_service_tsi
+
+LWS_VISIBLE LWS_EXTERN int
+lws_handle_POLLOUT_event(struct lws *wsi, struct lws_pollfd *pollfd);
+
+///@}
+
+/*! \defgroup uv libuv helpers
+ *
+ * ##libuv helpers
+ *
+ * APIs specific to libuv event loop itegration
+ */
+///@{
+#if defined(LWS_WITH_LIBUV) && defined(UV_ERRNO_MAP)
+
+/*
+ * Any direct libuv allocations in lws protocol handlers must participate in the
+ * lws reference counting scheme.  Two apis are provided:
+ *
+ * - lws_libuv_static_refcount_add(handle, context, tsi) to mark the handle with
+ *  a pointer to the context and increment the global uv object counter
+ *
+ * - lws_libuv_static_refcount_del() which should be used as the close callback
+ *   for your own libuv objects declared in the protocol scope.
+ *
+ * Using the apis allows lws to detach itself from a libuv loop completely
+ * cleanly and at the moment all of its libuv objects have completed close.
+ */
+
+LWS_VISIBLE LWS_EXTERN uv_loop_t *
+lws_uv_getloop(struct lws_context *context, int tsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_libuv_static_refcount_add(uv_handle_t *, struct lws_context *context,
+				int tsi);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_libuv_static_refcount_del(uv_handle_t *);
+
+#endif /* LWS_WITH_LIBUV */
+
+#if defined(LWS_PLAT_FREERTOS)
+#define lws_libuv_static_refcount_add(_a, _b, _c)
+#define lws_libuv_static_refcount_del NULL
+#endif
+///@}

include/libwebsockets/lws-settings.h

@@ -0,0 +1,112 @@
+/*
+ * Generic Settings storage
+ *
+ * Copyright (C) 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ *
+ * This is like an abstract class for non-volatile storage, whether in a file-
+ * system or flash-backed blocks, etc.  Named blobs of variable size are stored
+ * in nonvolatile media of some sort.  Typically, these are JSON objects under
+ * a naming scheme like, eg, "network".
+ *
+ * There's a platform-specific storage identifier opaque_plat provided when the
+ * storage object is instantiated, this describes eg the storage device or
+ * partition in instantiation-specific terms.
+ *
+ * Blobs have a further "filename" associated with them.
+ */
+
+#define LSOOPEN_FLAG_WRITEABLE				(1 << 0)
+
+struct lws_settings_ops;
+
+typedef struct {
+	void						*handle_plat;
+	const struct lws_settings_ops			*so;
+	uint8_t						refcount;
+	void						*opaque_plat;
+} lws_settings_instance_t;
+
+typedef struct lws_settings_ops {
+	int (*get)(lws_settings_instance_t *si, const char *name,
+		   uint8_t *dest, size_t *max_actual);
+	/**< if dest is NULL, max_actual is set to the actual length without
+	 * copying anything out */
+	int (*set)(lws_settings_instance_t *si, const char *name,
+		   const uint8_t *src, size_t len);
+} lws_settings_ops_t;
+
+/**
+ * lws_settings_plat_get() - read a named blob from a settings instance
+ *
+ * \param si: the settings instance
+ * \param name: the name of the setting blob in the instance
+ * \param dest: NULL, or the buffer to copy the setting blob info
+ * \param max_actual: point to size of dest, or zero; actual blob size on exit
+ *
+ * If the named blob doesn't exist in the si, or can't read, returns nonzero.
+ * Otherwise, returns 0 and sets *max_actual to the true blob size.  If dest is
+ * non-NULL, as much of the blob as will fit in the amount specified by
+ * *max_actual on entry is copied to dest.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_settings_plat_get(lws_settings_instance_t *si, const char *name,
+		      uint8_t *dest, size_t *max_actual);
+
+/**
+ * lws_settings_plat_get() - read a named blob from a settings instance
+ *
+ * \param si: the settings instance
+ * \param name: the name of the setting blob in the instance
+ * \param src: blob to copy to settings instance
+ * \param len: length of blob to copy
+ *
+ * Creates or replaces a settings blob of the given name made up of the \p len
+ * bytes of data from \p src.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_settings_plat_set(lws_settings_instance_t *si, const char *name,
+		      const uint8_t *src, size_t len);
+
+/**
+ * lws_settings_plat_printf() - read a named blob from a settings instance
+ *
+ * \param si: the settings instance
+ * \param name: the name of the setting blob in the instance
+ * \param format: printf-style format string
+ *
+ * Creates or replaces a settings blob of the given name from the printf-style
+ * format string and arguments provided.  There's no specific limit to the size,
+ * the size is computed and then a temp heap buffer used.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_settings_plat_printf(lws_settings_instance_t *si, const char *name,
+		         const char *format, ...) LWS_FORMAT(3);
+
+#define lws_settings_ops_plat \
+	.get		= lws_settings_plat_get, \
+	.set		= lws_settings_plat_set,
+
+LWS_VISIBLE LWS_EXTERN lws_settings_instance_t *
+lws_settings_init(const lws_settings_ops_t *so, void *opaque_plat);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_settings_deinit(lws_settings_instance_t **si);

include/libwebsockets/lws-sha1-base64.h

@@ -0,0 +1,109 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup sha SHA and B64 helpers
+ * ##SHA and B64 helpers
+ *
+ * These provide SHA-1 and B64 helper apis
+ */
+///@{
+#ifdef LWS_SHA1_USE_OPENSSL_NAME
+#define lws_SHA1 SHA1
+#else
+/**
+ * lws_SHA1(): make a SHA-1 digest of a buffer
+ *
+ * \param d: incoming buffer
+ * \param n: length of incoming buffer
+ * \param md: buffer for message digest (must be >= 20 bytes)
+ *
+ * Reduces any size buffer into a 20-byte SHA-1 hash.
+ */
+LWS_VISIBLE LWS_EXTERN unsigned char *
+lws_SHA1(const unsigned char *d, size_t n, unsigned char *md);
+#endif
+/**
+ * lws_b64_encode_string(): encode a string into base 64
+ *
+ * \param in: incoming buffer
+ * \param in_len: length of incoming buffer
+ * \param out: result buffer
+ * \param out_size: length of result buffer
+ *
+ * Encodes a string using b64
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
+/**
+ * lws_b64_encode_string_url(): encode a string into base 64
+ *
+ * \param in: incoming buffer
+ * \param in_len: length of incoming buffer
+ * \param out: result buffer
+ * \param out_size: length of result buffer
+ *
+ * Encodes a string using b64 with the "URL" variant (+ -> -, and / -> _)
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_b64_encode_string_url(const char *in, int in_len, char *out, int out_size);
+/**
+ * lws_b64_decode_string(): decode a string from base 64
+ *
+ * \param in: incoming buffer
+ * \param out: result buffer
+ * \param out_size: length of result buffer
+ *
+ * Decodes a NUL-terminated string using b64
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_b64_decode_string(const char *in, char *out, int out_size);
+/**
+ * lws_b64_decode_string_len(): decode a string from base 64
+ *
+ * \param in: incoming buffer
+ * \param in_len: length of incoming buffer
+ * \param out: result buffer
+ * \param out_size: length of result buffer
+ *
+ * Decodes a range of chars using b64
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_b64_decode_string_len(const char *in, int in_len, char *out, int out_size);
+
+struct lws_b64state {
+	unsigned char quad[4];
+	size_t done;
+	size_t len;
+	int i;
+	int c;
+};
+
+LWS_VISIBLE LWS_EXTERN void
+lws_b64_decode_state_init(struct lws_b64state *state);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_b64_decode_stateful(struct lws_b64state *s, const char *in, size_t *in_len,
+			uint8_t *out, size_t *out_size, int final);
+///@}
+

include/libwebsockets/lws-smd.h

@@ -0,0 +1,227 @@
+/*
+ * lws System Message Distribution
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#define LWS_SMD_MAX_PAYLOAD		384
+#define LWS_SMD_CLASS_BITFIELD_BYTES	4
+
+#define LWS_SMD_STREAMTYPENAME		"_lws_smd"
+#define LWS_SMD_SS_RX_HEADER_LEN	16
+
+typedef uint32_t lws_smd_class_t;
+
+struct lws_smd_msg; /* opaque */
+struct lws_smd_peer; /* opaque */
+
+/*
+ * Well-known device classes
+ */
+
+enum {
+	LWSSMDCL_INTERACTION					= (1 << 0),
+	/**<
+	 * Any kind of event indicating a user was interacting with the device,
+	 * eg, press a button, touched the screen, lifted the device etc
+	 */
+	LWSSMDCL_SYSTEM_STATE					= (1 << 1),
+	/**<
+	 * The lws_system state changed, eg, to OPERATIONAL
+	 */
+	LWSSMDCL_NETWORK					= (1 << 2),
+	/**<
+	 * Something happened on the network, eg, link-up or DHCP, or captive
+	 * portal state update
+	 */
+	LWSSMDCL_METRICS					= (1 << 3),
+	/**<
+	 * An SS client process is reporting a metric to the proxy (this class
+	 * is special in that it is not rebroadcast by the proxy)
+	 */
+
+	LWSSMDCL_USER_BASE_BITNUM				= 24
+};
+
+/**
+ * lws_smd_msg_alloc() - allocate a message of length len
+ *
+ * \param ctx: the lws_context
+ * \param _class: the smd message class, recipients filter on this
+ * \param len: the required payload length
+ *
+ * This helper returns an opaque lws_smd_msg pointer and sets *buf to a buffer
+ * associated with it of length \p len.
+ *
+ * In this way the lws_msg_smd type remains completely opaque and the allocated
+ * area can be prepared by the caller directly, without copying.
+ *
+ * On failure, it returns NULL... it may fail for OOM but it may also fail if
+ * you request to allocate for a message class that the system has no
+ * participant who is listening for that class of event currently... the event
+ * generation action at the caller should be bypassed without error then.
+ *
+ * This is useful if you have a message you know the length of.  For text-based
+ * messages like JSON, lws_smd_msg_printf() is more convenient.
+ */
+LWS_VISIBLE LWS_EXTERN void * /* payload */
+lws_smd_msg_alloc(struct lws_context *ctx, lws_smd_class_t _class, size_t len);
+
+/**
+ * lws_smd_msg_free() - abandon a previously allocated message before sending
+ *
+ * \param payload: pointer the previously-allocated message payload
+ *
+ * Destroys a previously-allocated opaque message object and the requested
+ * buffer space, in the case that between allocating it and sending it, some
+ * condition was met that means it can no longer be sent, eg, an error
+ * generating the content.  Otherwise there is no need to destroy allocated
+ * message objects with this, lws will take care of it.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_smd_msg_free(void **payload);
+
+/**
+ * lws_smd_msg_send() - queue a previously allocated message
+ *
+ * \param ctx: the lws_context
+ * \param msg: the prepared message
+ *
+ * Queues an allocated, prepared message for delivery to smd clients
+ *
+ * This is threadsafe to call from a non-service thread.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_smd_msg_send(struct lws_context *ctx, void *payload);
+
+/**
+ * lws_smd_msg_printf() - queue a previously allocated message
+ *
+ * \param ctx: the lws_context
+ * \param _class: the message class
+ * \param format: the format string to prepare the payload with
+ * \param ...: arguments for the format string, if any
+ *
+ * For string-based messages, eg, JSON, allows formatted creating of the payload
+ * size discovery, allocation and message send all in one step.
+ *
+ * Unlike lws_smd_msg_alloc() you do not need to know the length beforehand as
+ * this computes it and calls lws_smd_msg_alloc() with the correct length.
+ *
+ * To be clear this also calls through to lws_smd_msg_send(), it really does
+ * everything in one step.  If there are no registered participants that want
+ * messages of \p _class, this function returns immediately without doing any
+ * allocation or anything else.
+ *
+ * This is threadsafe to call from a non-service thread.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_smd_msg_printf(struct lws_context *ctx, lws_smd_class_t _class,
+		   const char *format, ...) LWS_FORMAT(3);
+
+/**
+ * lws_smd_ss_msg_printf() - helper to prepare smd ss message tx
+ *
+ * \param h: the ss handle
+ * \param buf: the ss tx buffer
+ * \param len: on entry, points to the ss tx buffer length, on exit, set to used
+ * \param _class: the message class
+ * \param format: the format string to prepare the payload with
+ * \param ...: arguments for the format string, if any
+ *
+ * This helper lets you produce SMD messages on an SS link of the builtin
+ * streamtype LWS_SMD_STREAMTYPENAME, using the same api format as
+ * lws_smd_msg_prinf(), but writing the message into the ss tx buffer from
+ * its tx() callback.
+ */
+
+struct lws_ss_handle;
+LWS_VISIBLE LWS_EXTERN int
+lws_smd_ss_msg_printf(const char *tag, uint8_t *buf, size_t *len,
+		      lws_smd_class_t _class, const char *format, ...)
+		      LWS_FORMAT(5);
+
+/**
+ * lws_smd_ss_rx_forward() - helper to forward smd messages that came in by SS
+ *
+ * \param ss_user: ss user pointer, as delivered to rx callback
+ * \param buf: the ss rx buffer
+ * \param len: the length of the ss rx buffer
+ *
+ * Proxied Secure Streams with the streamtype LWS_SMD_STREAMTYPENAME receive
+ * serialized SMD messages from the proxy, this helper allows them to be
+ * translated into deserialized SMD messages and forwarded to registered SMD
+ * participants in the local context in one step.
+ *
+ * Just pass through what arrived in the LWS_SMD_STREAMTYPENAME rx() callback
+ * to this api.
+ *
+ * Returns 0 if OK else nonzero if unable to queue the SMD message.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_smd_ss_rx_forward(void *ss_user, const uint8_t *buf, size_t len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_smd_sspc_rx_forward(void *ss_user, const uint8_t *buf, size_t len);
+
+typedef int (*lws_smd_notification_cb_t)(void *opaque, lws_smd_class_t _class,
+					 lws_usec_t timestamp, void *buf,
+					 size_t len);
+
+#define LWSSMDREG_FLAG_PROXIED_SS	(1 << 0)
+/**< It's actually a proxied SS connection registering, opaque is the ss h */
+
+/*
+ * lws_smd_register() - register to receive smd messages
+ *
+ * \param ctx: the lws_context
+ * \param opaque: an opaque pointer handed to the callback
+ * \param flags: typically 0
+ * \param _class_filter: bitmap of message classes we care about
+ * \param cb: the callback to receive messages
+ *
+ * Queues an allocated, prepared message for delivery to smd clients.
+ *
+ * Returns NULL on failure, or an opaque handle which may be given to
+ * lws_smd_unregister() to stop participating in the shared message queue.
+ *
+ * This is threadsafe to call from a non-service thread.
+ */
+
+LWS_VISIBLE LWS_EXTERN struct lws_smd_peer *
+lws_smd_register(struct lws_context *ctx, void *opaque, int flags,
+		 lws_smd_class_t _class_filter, lws_smd_notification_cb_t cb);
+
+/*
+ * lws_smd_unregister() - unregister receiving smd messages
+ *
+ * \param pr: the handle returned from the registration
+ *
+ * Destroys the registration of the callback for messages and ability to send
+ * messages.
+ *
+ * It's not necessary to call this if the registration wants to survive for as
+ * long as the lws_context... lws_context_destroy will also clean up any
+ * registrations still active by then.
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_smd_unregister(struct lws_smd_peer *pr);

include/libwebsockets/lws-spa.h

@@ -0,0 +1,176 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup form-parsing  Form Parsing
+ * \ingroup http
+ * ##POSTed form parsing functions
+ *
+ * These lws_spa (stateful post arguments) apis let you parse and urldecode
+ * POSTed form arguments, both using simple urlencoded and multipart transfer
+ * encoding.
+ *
+ * It's capable of handling file uploads as well a named input parsing,
+ * and the apis are the same for both form upload styles.
+ *
+ * You feed it a list of parameter names and it creates pointers to the
+ * urldecoded arguments: file upload parameters pass the file data in chunks to
+ * a user-supplied callback as they come.
+ *
+ * Since it's stateful, it handles the incoming data needing more than one
+ * POST_BODY callback and has no limit on uploaded file size.
+ */
+///@{
+
+/** enum lws_spa_fileupload_states */
+enum lws_spa_fileupload_states {
+	LWS_UFS_CONTENT,
+	/**< a chunk of file content has arrived */
+	LWS_UFS_FINAL_CONTENT,
+	/**< the last chunk (possibly zero length) of file content has arrived */
+	LWS_UFS_OPEN,
+	/**< a new file is starting to arrive */
+	LWS_UFS_CLOSE
+	/**< the file decode stuff is being destroyed */
+};
+
+/**
+ * lws_spa_fileupload_cb() - callback to receive file upload data
+ *
+ * \param data: opt_data pointer set in lws_spa_create
+ * \param name: name of the form field being uploaded
+ * \param filename: original filename from client
+ * \param buf: start of data to receive
+ * \param len: length of data to receive
+ * \param state: information about how this call relates to file
+ *
+ * Notice name and filename shouldn't be trusted, as they are passed from
+ * HTTP provided by the client.
+ */
+typedef int (*lws_spa_fileupload_cb)(void *data, const char *name,
+				     const char *filename, char *buf, int len,
+				     enum lws_spa_fileupload_states state);
+
+/** struct lws_spa - opaque urldecode parser capable of handling multipart
+ *			and file uploads */
+struct lws_spa;
+
+/**
+ * lws_spa_create() - create urldecode parser
+ *
+ * \param wsi: lws connection (used to find Content Type)
+ * \param param_names: array of form parameter names, like "username"
+ * \param count_params: count of param_names
+ * \param max_storage: total amount of form parameter values we can store
+ * \param opt_cb: NULL, or callback to receive file upload data.
+ * \param opt_data: NULL, or user pointer provided to opt_cb.
+ *
+ * Creates a urldecode parser and initializes it.
+ *
+ * It's recommended to use the newer api, lws_spa_create_via_info()
+ * instead.
+ *
+ * opt_cb can be NULL if you just want normal name=value parsing, however
+ * if one or more entries in your form are bulk data (file transfer), you
+ * can provide this callback and filter on the name callback parameter to
+ * treat that urldecoded data separately.  The callback should return -1
+ * in case of fatal error, and 0 if OK.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_spa *
+lws_spa_create(struct lws *wsi, const char * const *param_names,
+	       int count_params, int max_storage, lws_spa_fileupload_cb opt_cb,
+	       void *opt_data);
+
+typedef struct lws_spa_create_info {
+	const char * const *param_names; /* array of form parameter names, like "username" */
+	int count_params; /* count of param_names */
+	int max_storage; /* total amount of form parameter values we can store */
+	lws_spa_fileupload_cb opt_cb; /* NULL, or callback to receive file upload data. */
+	void *opt_data; /* NULL, or user pointer provided to opt_cb. */
+	size_t param_names_stride; /* 0 if param_names is an array of char *.
+					Else stride to next char * */
+	struct lwsac **ac;	/* NULL, or pointer to lwsac * to contain all
+				   related heap allocations */
+	size_t ac_chunk_size;	/* 0 for default, or ac chunk size */
+} lws_spa_create_info_t;
+
+/**
+ * lws_spa_create_via_info() - create urldecode parser
+ *
+ * \param wsi: lws connection (used to find Content Type)
+ * \param info: pointer to struct defining the arguments
+ *
+ * Creates a urldecode parser and initializes it.
+ *
+ * opt_cb can be NULL if you just want normal name=value parsing, however
+ * if one or more entries in your form are bulk data (file transfer), you
+ * can provide this callback and filter on the name callback parameter to
+ * treat that urldecoded data separately.  The callback should return -1
+ * in case of fatal error, and 0 if OK.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_spa *
+lws_spa_create_via_info(struct lws *wsi, const lws_spa_create_info_t *info);
+
+/**
+ * lws_spa_process() - parses a chunk of input data
+ *
+ * \param spa: the parser object previously created
+ * \param in: incoming urlencoded data
+ * \param len: count of bytes valid at \p in
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_spa_process(struct lws_spa *spa, const char *in, int len);
+
+/**
+ * lws_spa_finalize() - indicate incoming data completed
+ *
+ * \param spa: the parser object previously created
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_spa_finalize(struct lws_spa *spa);
+
+/**
+ * lws_spa_get_length() - return length of parameter value
+ *
+ * \param spa: the parser object previously created
+ * \param n: parameter ordinal to return length of value for
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_spa_get_length(struct lws_spa *spa, int n);
+
+/**
+ * lws_spa_get_string() - return pointer to parameter value
+ * \param spa: the parser object previously created
+ * \param n: parameter ordinal to return pointer to value for
+ */
+LWS_VISIBLE LWS_EXTERN const char *
+lws_spa_get_string(struct lws_spa *spa, int n);
+
+/**
+ * lws_spa_destroy() - destroy parser object
+ *
+ * \param spa: the parser object previously created
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_spa_destroy(struct lws_spa *spa);
+///@}

include/libwebsockets/lws-spi.h

@@ -0,0 +1,73 @@
+/*
+ * Generic I2C ops
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This is like an abstract class for spi, a real implementation provides
+ * functions for the ops that use the underlying OS arrangements.
+ *
+ * It uses descriptor / queuing semantics but eg the GPIO BB implementantion is
+ * synchronous.
+ */
+
+#if !defined(__LWS_SPI_H__)
+#define __LWS_SPI_H__
+
+#include <stdint.h>
+#include <stddef.h>
+
+typedef int (*lws_spi_cb_t)(void *opaque);
+
+enum {
+	LWSSPIMODE_CPOL					= (1 << 0),
+	LWSSPIMODE_CPHA					= (1 << 1),
+
+	LWS_SPI_BUSMODE_CLK_IDLE_LOW_SAMP_RISING	= 0,
+	LWS_SPI_BUSMODE_CLK_IDLE_HIGH_SAMP_RISING	= LWSSPIMODE_CPOL,
+	LWS_SPI_BUSMODE_CLK_IDLE_LOW_SAMP_FALLING	= LWSSPIMODE_CPHA,
+	LWS_SPI_BUSMODE_CLK_IDLE_HIGH_SAMP_FALLING	= LWSSPIMODE_CPHA |
+							  LWSSPIMODE_CPOL,
+
+	LWS_SPI_TXN_HALF_DUPLEX_DISCRETE	= 0,
+	/**< separate MISO and MOSI, but only either MISO or MOSI has data at
+	 * one time... i2c style in SPI */
+};
+
+typedef struct lws_spi_desc {
+	const uint8_t		*src;
+	const uint8_t		*data;
+	uint8_t			*dest;
+	void			*opaque;
+	lws_spi_cb_t		completion_cb;
+	uint16_t		count_cmd;
+	uint16_t		count_write;
+	uint16_t		count_read;
+	uint8_t			txn_type;
+	uint8_t			channel;
+} lws_spi_desc_t;
+
+typedef struct lws_spi_ops {
+	int  (*init)(const struct lws_spi_ops *ctx);
+	int  (*queue)(const struct lws_spi_ops *ctx, const lws_spi_desc_t *desc);
+	uint8_t	bus_mode;
+} lws_spi_ops_t;
+
+#endif

include/libwebsockets/lws-ssd1306-i2c.h

@@ -0,0 +1,64 @@
+/*
+ * lws abstract display implementation for ssd1306 on i2c
+ *
+ * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#if !defined(__LWS_DISPLAY_SSD1306_I2C_H__)
+#define __LWS_DISPLAY_SSD1306_I2C_H__
+
+/*
+ * D/C# pin on SSD1306 sets the I2C device ads
+ * from these two options (7-bit address)
+ */
+
+#define SSD1306_I2C7_ADS1		0x3c
+#define SSD1306_I2C7_ADS2		0x3d
+
+typedef struct lws_display_ssd1306 {
+
+	lws_display_t		disp; /* use lws_display_ssd1306_ops to set ops */
+	const lws_i2c_ops_t	*i2c;	      /* i2c ops */
+
+	const lws_gpio_ops_t	*gpio;	      /* NULL or gpio ops */
+	_lws_plat_gpio_t	reset_gpio;   /* if gpio ops, nReset gpio # */
+
+	uint8_t			i2c7_address; /* one of SSD1306_I2C7_ADS... */
+
+} lws_display_ssd1306_t;
+
+int
+lws_display_ssd1306_i2c_init(const struct lws_display *disp);
+int
+lws_display_ssd1306_i2c_contrast(const struct lws_display *disp, uint8_t b);
+int
+lws_display_ssd1306_i2c_blit(const struct lws_display *disp, const uint8_t *src,
+                             lws_display_scalar x, lws_display_scalar y,
+                             lws_display_scalar w, lws_display_scalar h);
+int
+lws_display_ssd1306_i2c_power(const struct lws_display *disp, int state);
+
+#define lws_display_ssd1306_ops \
+	.init = lws_display_ssd1306_i2c_init, \
+	.contrast = lws_display_ssd1306_i2c_contrast, \
+	.blit = lws_display_ssd1306_i2c_blit, \
+	.power = lws_display_ssd1306_i2c_power
+#endif

include/libwebsockets/lws-state.h

@@ -0,0 +1,119 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+struct lws_state_notify_link;
+struct lws_state_manager;
+
+#if defined(LWS_WITH_SYS_STATE)
+
+typedef int (*lws_state_notify_t)(struct lws_state_manager *mgr,
+				  struct lws_state_notify_link *link,
+				  int current, int target);
+
+typedef struct lws_state_notify_link {
+	lws_dll2_t		list;
+	lws_state_notify_t	notify_cb;
+	const char		*name;
+} lws_state_notify_link_t;
+
+typedef struct lws_state_manager {
+	lws_dll2_owner_t	notify_list;
+	struct lws_context	*context;
+	void			*parent;
+#if defined(LWS_WITH_SYS_SMD)
+	lws_smd_class_t		smd_class;
+#endif
+	/**< optional opaque pointer to owning object... useful to make such
+	 * a pointer available to a notification callback.  Ignored by lws */
+	const char		**state_names;
+	const char		*name;
+	int			state;
+} lws_state_manager_t;
+
+/**
+ * lws_state_reg_notifier() - add dep handler for state notifications
+ *
+ * \param context: the lws_context
+ * \param nl: the handler to add to the notifier linked-list
+ *
+ * Add \p notify_link to the context's list of notification handlers for system
+ * state changes.  The handlers can defeat or take over responsibility for
+ * retrying the change after they have initiated some dependency.
+ */
+
+LWS_EXTERN LWS_VISIBLE void
+lws_state_reg_notifier(lws_state_manager_t *mgr, lws_state_notify_link_t *nl);
+
+/**
+ * lws_state_reg_deregister() - deregister a notifier
+ *
+ * \param nl: notification hardler to deregister
+ *
+ * Remove a notification handler from its state manager
+ */
+
+LWS_EXTERN LWS_VISIBLE void
+lws_state_reg_deregister(lws_state_notify_link_t *nl);
+
+/**
+ * lws_state_reg_notifier_list() - add dep handlers for state notifications
+ *
+ * \param context: the lws_context
+ * \param nl: list of notification handlers
+ *
+ * Add a NULL-terminated list of notification handler pointers to a notification
+ * manager object
+ */
+
+LWS_EXTERN LWS_VISIBLE void
+lws_state_reg_notifier_list(lws_state_manager_t *mgr,
+			    lws_state_notify_link_t * const *nl);
+
+/**
+ * lws_state_transition_steps() - move to state via starting any deps
+ *
+ * \param mgr: the state manager object
+ * \param target: the state we wish to move to
+ *
+ * Advance state by state towards state \p target.  At each state, notifiers
+ * may veto the change and be triggered to perform dependencies, stopping the
+ * advance towards the target state.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_state_transition_steps(lws_state_manager_t *mgr, int target);
+
+/**
+ * lws_state_transition() - move to state via starting any deps
+ *
+ * \param mgr: the state manager object
+ * \param target: the state we wish to move to
+ *
+ * Jump to state target atomically.  Notifiers may veto it.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_state_transition(lws_state_manager_t *mgr, int target);
+
+#else
+
+#endif

include/libwebsockets/lws-struct.h

@@ -0,0 +1,284 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#if defined(LWS_WITH_STRUCT_SQLITE3)
+#include <sqlite3.h>
+#endif
+
+typedef enum {
+	LSMT_SIGNED,
+	LSMT_UNSIGNED,
+	LSMT_BOOLEAN,
+	LSMT_STRING_CHAR_ARRAY,
+	LSMT_STRING_PTR,
+	LSMT_LIST,
+	LSMT_CHILD_PTR,
+	LSMT_SCHEMA,
+	LSMT_BLOB_PTR,
+
+} lws_struct_map_type_eum;
+
+typedef struct lejp_collation {
+	struct lws_dll2 chunks;
+	int len;
+	char buf[LEJP_STRING_CHUNK + 1];
+} lejp_collation_t;
+
+typedef struct lws_struct_map {
+	const char *colname;
+	const struct lws_struct_map *child_map;
+	lejp_callback lejp_cb;
+	size_t ofs;			/* child dll2; points to dll2_owner */
+	size_t aux;
+	size_t ofs_clist;
+	size_t child_map_size;
+	lws_struct_map_type_eum type;
+} lws_struct_map_t;
+
+typedef int (*lws_struct_args_cb)(void *obj, void *cb_arg);
+
+typedef struct lws_struct_args {
+	const lws_struct_map_t *map_st[LEJP_MAX_PARSING_STACK_DEPTH];
+	lws_struct_args_cb cb;
+	struct lwsac *ac;
+	void *cb_arg;
+	void *dest;
+
+	size_t dest_len;
+	size_t toplevel_dll2_ofs;
+	size_t map_entries_st[LEJP_MAX_PARSING_STACK_DEPTH];
+	size_t ac_block_size;
+	int subtype;
+
+	int top_schema_index;
+
+	/*
+	 * temp ac used to collate unknown possibly huge strings before final
+	 * allocation and copy
+	 */
+	struct lwsac *ac_chunks;
+	struct lws_dll2_owner chunks_owner;
+	size_t chunks_length;
+} lws_struct_args_t;
+
+#define LSM_SIGNED(type, name, qname) \
+	{ \
+	  qname, \
+	  NULL, \
+	  NULL, \
+	  offsetof(type, name), \
+	  sizeof ((type *)0)->name, \
+	  0, \
+	  0, \
+	  LSMT_SIGNED \
+	}
+
+#define LSM_UNSIGNED(type, name, qname) \
+	{ \
+	  qname, \
+	  NULL, \
+	  NULL, \
+	  offsetof(type, name), \
+	  sizeof ((type *)0)->name, \
+	  0, \
+	  0, \
+	  LSMT_UNSIGNED \
+	}
+
+#define LSM_BOOLEAN(type, name, qname) \
+	{ \
+	  qname, \
+	  NULL, \
+	  NULL, \
+	  offsetof(type, name), \
+	  sizeof ((type *)0)->name, \
+	  0, \
+	  0, \
+	  LSMT_BOOLEAN \
+	}
+
+#define LSM_CARRAY(type, name, qname) \
+	{ \
+	  qname, \
+	  NULL, \
+	  NULL, \
+	  offsetof(type, name), \
+	  sizeof (((type *)0)->name), \
+	  0, \
+	  0, \
+	  LSMT_STRING_CHAR_ARRAY \
+	}
+
+#define LSM_STRING_PTR(type, name, qname) \
+	{ \
+	  qname, \
+	  NULL, \
+	  NULL, \
+	  offsetof(type, name), \
+	  sizeof (((type *)0)->name), \
+	  0, \
+	  0, \
+	  LSMT_STRING_PTR \
+	}
+
+#define LSM_LIST(ptype, pname, ctype, cname, lejp_cb, cmap, qname) \
+	{ \
+	  qname, \
+	  cmap, \
+	  lejp_cb, \
+	  offsetof(ptype, pname), \
+	  sizeof (ctype), \
+	  offsetof(ctype, cname), \
+	  LWS_ARRAY_SIZE(cmap), \
+	  LSMT_LIST \
+	}
+
+#define LSM_CHILD_PTR(ptype, pname, ctype, lejp_cb, cmap, qname) \
+	{ \
+	  qname, \
+	  cmap, \
+	  lejp_cb, \
+	  offsetof(ptype, pname), \
+	  sizeof (ctype), \
+	  0, \
+	  LWS_ARRAY_SIZE(cmap), \
+	  LSMT_CHILD_PTR \
+	}
+
+#define LSM_SCHEMA(ctype, lejp_cb, map, schema_name) \
+	{ \
+	  schema_name, \
+	  map, \
+	  lejp_cb, \
+	  0, \
+	  sizeof (ctype), \
+	  0, \
+	  LWS_ARRAY_SIZE(map), \
+	  LSMT_SCHEMA \
+	}
+
+#define LSM_SCHEMA_DLL2(ctype, cdll2mem, lejp_cb, map, schema_name) \
+	{ \
+	  schema_name, \
+	  map, \
+	  lejp_cb, \
+	  offsetof(ctype, cdll2mem), \
+	  sizeof (ctype), \
+	  0, \
+	  LWS_ARRAY_SIZE(map), \
+	  LSMT_SCHEMA \
+	}
+
+/*
+ * This is just used to create the table schema, it is not part of serialization
+ * and deserialization.  Blobs should be accessed separately.
+ */
+
+#define LSM_BLOB_PTR(type, blobptr_name, qname) \
+	{ \
+	  qname, /* JSON item, or sqlite3 column name */ \
+	  NULL, \
+	  NULL, \
+	  offsetof(type, blobptr_name),       /* member that points to blob */ \
+	  sizeof (((type *)0)->blobptr_name),       /* size of blob pointer */ \
+	  0,		 /* member holding blob len */ \
+	  0, /* size of blob length member */ \
+	  LSMT_BLOB_PTR \
+	}
+
+typedef struct lws_struct_serialize_st {
+	const struct lws_dll2 *dllpos;
+	const lws_struct_map_t *map;
+	const char *obj;
+	size_t map_entries;
+	size_t map_entry;
+	size_t size;
+	char subsequent;
+	char idt;
+} lws_struct_serialize_st_t;
+
+enum {
+	LSSERJ_FLAG_PRETTY	= (1 << 0),
+	LSSERJ_FLAG_OMIT_SCHEMA = (1 << 1)
+};
+
+typedef struct lws_struct_serialize {
+	lws_struct_serialize_st_t st[LEJP_MAX_PARSING_STACK_DEPTH];
+
+	size_t offset;
+	size_t remaining;
+
+	int sp;
+	int flags;
+} lws_struct_serialize_t;
+
+typedef enum {
+	LSJS_RESULT_CONTINUE,
+	LSJS_RESULT_FINISH,
+	LSJS_RESULT_ERROR
+} lws_struct_json_serialize_result_t;
+
+LWS_VISIBLE LWS_EXTERN int
+lws_struct_json_init_parse(struct lejp_ctx *ctx, lejp_callback cb,
+			   void *user);
+
+LWS_VISIBLE LWS_EXTERN signed char
+lws_struct_schema_only_lejp_cb(struct lejp_ctx *ctx, char reason);
+
+LWS_VISIBLE LWS_EXTERN signed char
+lws_struct_default_lejp_cb(struct lejp_ctx *ctx, char reason);
+
+LWS_VISIBLE LWS_EXTERN lws_struct_serialize_t *
+lws_struct_json_serialize_create(const lws_struct_map_t *map,
+				 size_t map_entries, int flags,
+				 const void *ptoplevel);
+
+LWS_VISIBLE LWS_EXTERN void
+lws_struct_json_serialize_destroy(lws_struct_serialize_t **pjs);
+
+LWS_VISIBLE LWS_EXTERN lws_struct_json_serialize_result_t
+lws_struct_json_serialize(lws_struct_serialize_t *js, uint8_t *buf,
+			  size_t len, size_t *written);
+
+typedef struct sqlite3 sqlite3;
+
+LWS_VISIBLE LWS_EXTERN int
+lws_struct_sq3_serialize(sqlite3 *pdb, const lws_struct_map_t *schema,
+			 lws_dll2_owner_t *owner, uint32_t manual_idx);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_struct_sq3_deserialize(sqlite3 *pdb, const char *filter, const char *order,
+			   const lws_struct_map_t *schema, lws_dll2_owner_t *o,
+			   struct lwsac **ac, int start, int limit);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_struct_sq3_create_table(sqlite3 *pdb, const lws_struct_map_t *schema);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_struct_sq3_open(struct lws_context *context, const char *sqlite3_path,
+		    char create_if_missing, sqlite3 **pdb);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_struct_sq3_close(sqlite3 **pdb);
+

include/libwebsockets/lws-system.h

@@ -0,0 +1,399 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * This provides a clean way to interface lws user code to be able to
+ * work unchanged on different systems for fetching common system information,
+ * and performing common system operations like reboot.
+ */
+
+/*
+ * Types of system blob that can be set and retreived
+ */
+
+typedef enum {
+	LWS_SYSBLOB_TYPE_AUTH,
+	LWS_SYSBLOB_TYPE_CLIENT_CERT_DER = LWS_SYSBLOB_TYPE_AUTH + 2,
+	LWS_SYSBLOB_TYPE_CLIENT_KEY_DER,
+	LWS_SYSBLOB_TYPE_DEVICE_SERIAL,
+	LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION,
+	LWS_SYSBLOB_TYPE_DEVICE_TYPE,
+	LWS_SYSBLOB_TYPE_NTP_SERVER,
+	LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID,
+	LWS_SYSBLOB_TYPE_MQTT_USERNAME,
+	LWS_SYSBLOB_TYPE_MQTT_PASSWORD,
+
+#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
+	/* extend 4 more auth blobs, each has 2 slots */
+	LWS_SYSBLOB_TYPE_EXT_AUTH1,
+	LWS_SYSBLOB_TYPE_EXT_AUTH2 = LWS_SYSBLOB_TYPE_EXT_AUTH1 + 2,
+	LWS_SYSBLOB_TYPE_EXT_AUTH3 = LWS_SYSBLOB_TYPE_EXT_AUTH2 + 2,
+	LWS_SYSBLOB_TYPE_EXT_AUTH4 = LWS_SYSBLOB_TYPE_EXT_AUTH3 + 2,
+	LWS_SYSBLOB_TYPE_EXT_AUTH4_1,
+#endif
+
+	LWS_SYSBLOB_TYPE_COUNT /* ... always last */
+} lws_system_blob_item_t;
+
+/* opaque generic blob whose content may be on-the-heap or pointed-to
+ * directly case by case.  When it's on the heap, it can be produced by
+ * appending (it's a buflist underneath).  Either way, it can be consumed by
+ * copying out a given length from a given offset.
+ */
+
+typedef struct lws_system_blob lws_system_blob_t;
+
+LWS_EXTERN LWS_VISIBLE void
+lws_system_blob_direct_set(lws_system_blob_t *b, const uint8_t *ptr, size_t len);
+
+LWS_EXTERN LWS_VISIBLE void
+lws_system_blob_heap_empty(lws_system_blob_t *b);
+
+LWS_EXTERN LWS_VISIBLE int
+lws_system_blob_heap_append(lws_system_blob_t *b, const uint8_t *ptr, size_t len);
+
+LWS_EXTERN LWS_VISIBLE size_t
+lws_system_blob_get_size(lws_system_blob_t *b);
+
+/* return 0 and sets *ptr to point to blob data if possible, nonzero = fail */
+LWS_EXTERN LWS_VISIBLE int
+lws_system_blob_get_single_ptr(lws_system_blob_t *b, const uint8_t **ptr);
+
+LWS_EXTERN LWS_VISIBLE int
+lws_system_blob_get(lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs);
+
+LWS_EXTERN LWS_VISIBLE void
+lws_system_blob_destroy(lws_system_blob_t *b);
+
+/*
+ * Get the opaque blob for index idx of various system blobs.  Returns 0 if
+ * *b was set otherwise nonzero means out of range
+ */
+
+LWS_EXTERN LWS_VISIBLE lws_system_blob_t *
+lws_system_get_blob(struct lws_context *context, lws_system_blob_item_t type,
+                    int idx);
+
+/*
+ * Lws view of system state... normal operation from user code perspective is
+ * dependent on implicit (eg, knowing the date for cert validation) and
+ * explicit dependencies.
+ *
+ * Bit of lws and user code can register notification handlers that can enforce
+ * dependent operations before state transitions can complete.
+ */
+
+typedef enum { /* keep system_state_names[] in sync in context.c */
+	LWS_SYSTATE_UNKNOWN,
+
+	LWS_SYSTATE_CONTEXT_CREATED,	 /* context was just created */
+	LWS_SYSTATE_INITIALIZED,	 /* protocols initialized.  Lws itself
+					  * can operate normally */
+	LWS_SYSTATE_IFACE_COLDPLUG,	 /* existing net ifaces iterated */
+	LWS_SYSTATE_DHCP,		 /* at least one net iface configured */
+	LWS_SYSTATE_CPD_PRE_TIME,	 /* Captive portal detect without valid
+					  * time, good for non-https tests... if
+					  * you care about it, implement and
+					  * call lws_system_ops_t
+					  * .captive_portal_detect_request()
+					  * and move the state forward according
+					  * to the result. */
+	LWS_SYSTATE_TIME_VALID,		 /* ntpclient ran, or hw time valid...
+					  * tls cannot work until we reach here
+					  */
+	LWS_SYSTATE_CPD_POST_TIME,	 /* Captive portal detect after time was
+					  * time, good for https tests... if
+					  * you care about it, implement and
+					  * call lws_system_ops_t
+					  * .captive_portal_detect_request()
+					  * and move the state forward according
+					  * to the result. */
+
+	LWS_SYSTATE_POLICY_VALID,	 /* user code knows how to operate... */
+	LWS_SYSTATE_REGISTERED,		 /* device has an identity... */
+	LWS_SYSTATE_AUTH1,		 /* identity used for main auth token */
+	LWS_SYSTATE_AUTH2,		 /* identity used for optional auth */
+
+	LWS_SYSTATE_OPERATIONAL,	 /* user code can operate normally */
+
+	LWS_SYSTATE_POLICY_INVALID,	 /* user code is changing its policies
+					  * drop everything done with old
+					  * policy, switch to new then enter
+					  * LWS_SYSTATE_POLICY_VALID */
+	LWS_SYSTATE_CONTEXT_DESTROYING,	 /* Context is being destroyed */
+} lws_system_states_t;
+
+/* Captive Portal Detect -related */
+
+typedef enum {
+	LWS_CPD_UNKNOWN = 0,	/* test didn't happen ince last DHCP acq yet */
+	LWS_CPD_INTERNET_OK,	/* no captive portal: our CPD test passed OK,
+				 * we can go out on the internet */
+	LWS_CPD_CAPTIVE_PORTAL,	/* we inferred we're behind a captive portal */
+	LWS_CPD_NO_INTERNET,	/* we couldn't touch anything */
+} lws_cpd_result_t;
+
+typedef void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque);
+struct lws_attach_item;
+
+LWS_EXTERN LWS_VISIBLE int
+lws_tls_jit_trust_got_cert_cb(struct lws_context *cx, void *got_opaque,
+			      const uint8_t *skid, size_t skid_len,
+			      const uint8_t *der, size_t der_len);
+
+typedef struct lws_system_ops {
+	int (*reboot)(void);
+	int (*set_clock)(lws_usec_t us);
+	int (*attach)(struct lws_context *context, int tsi, lws_attach_cb_t cb,
+		      lws_system_states_t state, void *opaque,
+		      struct lws_attach_item **get);
+	/**< if \p get is NULL, add an attach callback request to the pt for
+	 * \p cb with arg \p opaque, that should be called when we're at or past
+	 * system state \p state.
+	 *
+	 * If \p get is non-NULL, look for the first listed item on the pt whose
+	 * state situation is ready, and set *get to point to it.  If no items,
+	 * or none where the system state is right, set *get to NULL.
+	 *
+	 * It's done like this so (*attach) can perform system-specific
+	 * locking outside of lws core, for both getting and adding items the
+	 * same so it is thread-safe.  A non-threadsafe helper
+	 * __lws_system_attach() is provided to do the actual work inside the
+	 * system-specific locking.
+	 */
+	int (*captive_portal_detect_request)(struct lws_context *context);
+	/**< Check if we can go out on the internet cleanly, or if we are being
+	 * redirected or intercepted by a captive portal.
+	 * Start the check that proceeds asynchronously, and report the results
+	 * by calling lws_captive_portal_detect_result() api
+	 */
+
+	int (*metric_report)(lws_metric_pub_t *mdata);
+	/**< metric \p item is reporting an event of kind \p rpt,
+	 * held in \p mdata... return 0 to leave the metric object as it is,
+	 * or nonzero to reset it. */
+
+	int (*jit_trust_query)(struct lws_context *cx, const uint8_t *skid,
+			       size_t skid_len, void *got_opaque);
+	/**< user defined trust store search, if we do trust a cert with SKID
+	 * matching skid / skid_len, then it should get hold of the DER for the
+	 * matching root CA and call
+	 * lws_tls_jit_trust_got_cert_cb(..., got_opaque) before cleaning up and
+	 * returning.  The DER should be destroyed if in heap before returning.
+	 */
+
+	uint32_t	wake_latency_us;
+	/**< time taken for this device to wake from suspend, in us
+	 */
+} lws_system_ops_t;
+
+#if defined(LWS_WITH_SYS_STATE)
+
+/**
+ * lws_system_get_state_manager() - return the state mgr object for system state
+ *
+ * \param context: the lws_context
+ *
+ * The returned pointer can be used with the lws_state_ apis
+ */
+
+LWS_EXTERN LWS_VISIBLE lws_state_manager_t *
+lws_system_get_state_manager(struct lws_context *context);
+
+#endif
+
+/* wrappers handle NULL members or no ops struct set at all cleanly */
+
+#define LWSSYSGAUTH_HEX (1 << 0)
+
+/**
+ * lws_system_get_ops() - get ahold of the system ops struct from the context
+ *
+ * \param context: the lws_context
+ *
+ * Returns the system ops struct.  It may return NULL and if not, anything in
+ * there may be NULL.
+ */
+LWS_EXTERN LWS_VISIBLE const lws_system_ops_t *
+lws_system_get_ops(struct lws_context *context);
+
+#if defined(LWS_WITH_SYS_STATE)
+
+/**
+ * lws_system_context_from_system_mgr() - return context from system state mgr
+ *
+ * \param mgr: pointer to specifically the system state mgr
+ *
+ * Returns the context from the system state mgr.  Helper since the lws_context
+ * is opaque.
+ */
+LWS_EXTERN LWS_VISIBLE struct lws_context *
+lws_system_context_from_system_mgr(lws_state_manager_t *mgr);
+
+#endif
+
+/**
+ * __lws_system_attach() - get and set items on context attach list
+ *
+ * \param context: context to get or set attach items to
+ * \param tsi: thread service index (normally 0)
+ * \param cb: callback to call from context event loop thread
+ * \param state: the lws_system state we have to be in or have passed through
+ * \param opaque: optional pointer to user specific info given to callback
+ * \param get: NULL, or pointer to pointer to take detached tail item on exit
+ *
+ * This allows other threads to enqueue callback requests to happen from a pt's
+ * event loop thread safely.  The callback gets the context pointer and a user
+ * opaque pointer that can be optionally given when the item is added to the
+ * attach list.
+ *
+ * This api is the no-locking core function for getting and setting items on the
+ * pt's attach list.  The lws_system operation (*attach) is the actual
+ * api that user and internal code calls for this feature, it should perform
+ * system-specific locking, call this helper, release the locking and then
+ * return the result.  This api is public only so it can be used in the locked
+ * implementation of (*attach).
+ *
+ * If get is NULL, then the call adds to the head of the pt attach list using
+ * cb, state, and opaque; if get is non-NULL, then *get is set to the first
+ * waiting attached item that meets the state criteria and that item is removed
+ * from the list.
+ *
+ * This is a non-threadsafe helper only designed to be called from
+ * implementations of struct lws_system's (*attach) operation where system-
+ * specific locking has been applied around it, making it threadsafe.
+ */
+LWS_EXTERN LWS_VISIBLE int
+__lws_system_attach(struct lws_context *context, int tsi, lws_attach_cb_t cb,
+		    lws_system_states_t state, void *opaque,
+		    struct lws_attach_item **get);
+
+
+enum {
+	LWSDH_IPV4_SUBNET_MASK		= 0,
+	LWSDH_IPV4_BROADCAST,
+	LWSDH_LEASE_SECS,
+	LWSDH_REBINDING_SECS,
+	LWSDH_RENEWAL_SECS,
+
+	_LWSDH_NUMS_COUNT,
+
+	LWSDH_SA46_IP			= 0,
+	LWSDH_SA46_DNS_SRV_1,
+	LWSDH_SA46_DNS_SRV_2,
+	LWSDH_SA46_DNS_SRV_3,
+	LWSDH_SA46_DNS_SRV_4,
+	LWSDH_SA46_IPV4_ROUTER,
+	LWSDH_SA46_NTP_SERVER,
+	LWSDH_SA46_DHCP_SERVER,
+
+	_LWSDH_SA46_COUNT,
+};
+
+typedef struct lws_dhcpc_ifstate {
+	char				ifname[16];
+	char				domain[64];
+	uint8_t				mac[6];
+	uint32_t			nums[_LWSDH_NUMS_COUNT];
+	lws_sockaddr46			sa46[_LWSDH_SA46_COUNT];
+} lws_dhcpc_ifstate_t;
+
+typedef int (*dhcpc_cb_t)(void *opaque, lws_dhcpc_ifstate_t *is);
+
+/**
+ * lws_dhcpc_request() - add a network interface to dhcpc management
+ *
+ * \param c: the lws_context
+ * \param i: the interface name, like "eth0"
+ * \param af: address family
+ * \param cb: the change callback
+ * \param opaque: opaque pointer given to the callback
+ *
+ * Register a network interface as being managed by DHCP.  lws will proceed to
+ * try to acquire an IP.  Requires LWS_WITH_SYS_DHCP_CLIENT at cmake.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_dhcpc_request(struct lws_context *c, const char *i, int af, dhcpc_cb_t cb,
+		void *opaque);
+
+/**
+ * lws_dhcpc_remove() - remove a network interface to dhcpc management
+ *
+ * \param context: the lws_context
+ * \param iface: the interface name, like "eth0"
+ *
+ * Remove handling of the network interface from dhcp.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_dhcpc_remove(struct lws_context *context, const char *iface);
+
+/**
+ * lws_dhcpc_status() - has any interface reached BOUND state
+ *
+ * \param context: the lws_context
+ * \param sa46: set to a DNS server from a bound interface, or NULL
+ *
+ * Returns 1 if any network interface managed by dhcpc has reached the BOUND
+ * state (has acquired an IP, gateway and DNS server), otherwise 0.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_dhcpc_status(struct lws_context *context, lws_sockaddr46 *sa46);
+
+/**
+ * lws_system_cpd_start() - helper to initiate captive portal detection
+ *
+ * \param context: the lws_context
+ *
+ * Resets the context's captive portal state to LWS_CPD_UNKNOWN and calls the
+ * lws_system_ops_t captive_portal_detect_request() implementation to begin
+ * testing the captive portal state.
+ */
+LWS_EXTERN LWS_VISIBLE int
+lws_system_cpd_start(struct lws_context *context);
+
+LWS_EXTERN LWS_VISIBLE void
+lws_system_cpd_start_defer(struct lws_context *cx, lws_usec_t defer_us);
+
+
+/**
+ * lws_system_cpd_set() - report the result of the captive portal detection
+ *
+ * \param context: the lws_context
+ * \param result: one of the LWS_CPD_ constants representing captive portal state
+ *
+ * Sets the context's captive portal detection state to result.  User captive
+ * portal detection code would call this once it had a result from its test.
+ */
+LWS_EXTERN LWS_VISIBLE void
+lws_system_cpd_set(struct lws_context *context, lws_cpd_result_t result);
+
+
+/**
+ * lws_system_cpd_state_get() - returns the last tested captive portal state
+ *
+ * \param context: the lws_context
+ *
+ * Returns one of the LWS_CPD_ constants indicating the system's understanding
+ * of the current captive portal situation.
+ */
+LWS_EXTERN LWS_VISIBLE lws_cpd_result_t
+lws_system_cpd_state_get(struct lws_context *context);

include/libwebsockets/lws-test-sequencer.h

@@ -0,0 +1,61 @@
+ /*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *
+ * lws_test_sequencer manages running an array of unit tests.
+ */
+
+typedef void (*lws_test_sequence_cb)(const void *cb_user);
+
+typedef struct lws_test_sequencer_args {
+	lws_abs_t		*abs; /* abstract protocol + unit test txport */
+	lws_unit_test_t	*tests; /* array of lws_unit_test_t */
+	int			*results; /* takes result dispositions */
+	int			results_max; /* max space usable in results */
+	int			*count_tests; /* count of done tests */
+	int			*count_passes; /* count of passed tests */
+	lws_test_sequence_cb	cb; /* completion callback */
+	void			*cb_user; /* opaque user ptr given to cb */
+} lws_test_sequencer_args_t;
+
+/**
+ * lws_abs_unit_test_sequencer() - helper to sequence multiple unit tests
+ *
+ * \param args: lws_test_sequencer_args_t prepared with arguments for the tests
+ *
+ * This helper sequences one or more unit tests to run and collects the results.
+ *
+ * The incoming abs should be set up for the abstract protocol you want to test
+ * and the lws unit-test transport.
+ *
+ * Results are one of
+ *
+ * 	LPE_SUCCEEDED
+ *	LPE_FAILED
+ *	LPE_FAILED_UNEXPECTED_TIMEOUT
+ *	LPE_FAILED_UNEXPECTED_PASS
+ *	LPE_FAILED_UNEXPECTED_CLOSE
+ *
+ * The callback args->cb is called when the tests have been done.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_abs_unit_test_sequencer(const lws_test_sequencer_args_t *args);

include/libwebsockets/lws-threadpool.h

@@ -0,0 +1,280 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup threadpool Threadpool related functions
+ * ##Threadpool
+ * \ingroup lwsapi
+ *
+ * This allows you to create one or more pool of threads which can run tasks
+ * associated with a wsi.  If the pool is busy, tasks wait on a queue.
+ *
+ * Tasks don't have to be atomic, if they will take more than a few tens of ms
+ * they should return back to the threadpool worker with a return of 0.  This
+ * will allow them to abort cleanly.
+ */
+//@{
+
+struct lws_threadpool;
+struct lws_threadpool_task;
+
+enum lws_threadpool_task_status {
+	LWS_TP_STATUS_QUEUED,
+	LWS_TP_STATUS_RUNNING,
+	LWS_TP_STATUS_SYNCING,
+	LWS_TP_STATUS_STOPPING,
+	LWS_TP_STATUS_FINISHED, /* lws_threadpool_task_status() frees task */
+	LWS_TP_STATUS_STOPPED, /* lws_threadpool_task_status() frees task */
+};
+
+enum lws_threadpool_task_return {
+	/** Still work to do, just confirming not being stopped */
+	LWS_TP_RETURN_CHECKING_IN,
+	/** Still work to do, enter cond_wait until service thread syncs.  This
+	 * is used if you have filled your buffer(s) of data to the service
+	 * thread and are blocked until the service thread completes sending at
+	 * least one.
+	 */
+	LWS_TP_RETURN_SYNC,
+	/** No more work to do... */
+	LWS_TP_RETURN_FINISHED,
+	/** Responding to request to stop */
+	LWS_TP_RETURN_STOPPED,
+
+	/* OR on to indicate this task wishes to outlive its wsi */
+	LWS_TP_RETURN_FLAG_OUTLIVE = 64
+};
+
+struct lws_threadpool_create_args {
+	int threads;
+	int max_queue_depth;
+};
+
+struct lws_threadpool_task_args {
+#if defined(LWS_WITH_SECURE_STREAMS)
+	struct lws_ss_handle *ss; /**< either wsi or ss must be set */
+#endif
+	struct lws *wsi;	/**< either wsi or ss must be set */
+
+	void *user;		/**< user may set (user-private pointer) */
+	const char *name;	/**< user may set to describe task */
+	char async_task;	/**< set to allow the task to shrug off the loss
+				     of the associated wsi and continue to
+				     completion */
+	enum lws_threadpool_task_return (*task)(void *user,
+					enum lws_threadpool_task_status s);
+	/**< user must set to actual task function */
+	void (*cleanup)(struct lws *wsi, void *user);
+	/**< socket lifecycle may end while task is not stoppable, so the task
+	 * must be able to detach from any wsi and clean itself up when it does
+	 * stop.  If NULL, no cleanup necessary, otherwise point to a user-
+	 * supplied function that destroys the stuff in \p user.
+	 *
+	 * wsi may be NULL on entry, indicating the task got detached due to the
+	 * wsi closing before.
+	 */
+};
+
+/**
+ * lws_threadpool_create() - create a pool of worker threads
+ *
+ * \param context: the lws_context the threadpool will exist inside
+ * \param args: argument struct prepared by caller
+ * \param format: printf-type format for the task name
+ * \param ...: printf type args for the task name format
+ *
+ * Creates a pool of worker threads with \p threads and a queue of up to
+ * \p max_queue_depth waiting tasks if all the threads are busy.
+ *
+ * Returns NULL if OOM, or a struct lws_threadpool pointer that must be
+ * destroyed by lws_threadpool_destroy().
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_threadpool *
+lws_threadpool_create(struct lws_context *context,
+		      const struct lws_threadpool_create_args *args,
+		      const char *format, ...) LWS_FORMAT(3);
+
+/**
+ * lws_threadpool_finish() - Stop all pending and running tasks
+ *
+ * \param tp: the threadpool object
+ *
+ * Marks the threadpool as under destruction.  Removes everything from the
+ * pending queue and completes those tasks as LWS_TP_STATUS_STOPPED.
+ *
+ * Running tasks will also get LWS_TP_STATUS_STOPPED as soon as they
+ * "resurface".
+ *
+ * This doesn't reap tasks or free the threadpool, the reaping is done by the
+ * lws_threadpool_task_status() on the done task.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_threadpool_finish(struct lws_threadpool *tp);
+
+/**
+ * lws_threadpool_destroy() - Destroy a threadpool
+ *
+ * \param tp: the threadpool object
+ *
+ * Waits for all worker threads to stop, ends the threads and frees the tp.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_threadpool_destroy(struct lws_threadpool *tp);
+
+/**
+ * lws_threadpool_enqueue() - Queue the task and run it on a worker thread when possible
+ *
+ * \param tp: the threadpool to queue / run on
+ * \param args: information about what to run
+ * \param format: printf-type format for the task name
+ * \param ...: printf type args for the task name format
+ *
+ * This asks for a task to run ASAP on a worker thread in threadpool \p tp.
+ *
+ * The args defines the wsi, a user-private pointer, a timeout in secs and
+ * a pointer to the task function.
+ *
+ * Returns NULL or an opaque pointer to the queued (or running, or completed)
+ * task.
+ *
+ * Once a task is created and enqueued, it can only be destroyed by calling
+ * lws_threadpool_task_status() on it after it has reached the state
+ * LWS_TP_STATUS_FINISHED or LWS_TP_STATUS_STOPPED.
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task *
+lws_threadpool_enqueue(struct lws_threadpool *tp,
+		       const struct lws_threadpool_task_args *args,
+		       const char *format, ...) LWS_FORMAT(3);
+
+/**
+ * lws_threadpool_dequeue() - Dequeue or try to stop a running task
+ *
+ * \param wsi: the wsi whose current task we want to eliminate
+ *
+ * Returns 0 is the task was dequeued or already compeleted, or 1 if the task
+ * has been asked to stop asynchronously.
+ *
+ * This doesn't free the task.  It only shortcuts it to state
+ * LWS_TP_STATUS_STOPPED.  lws_threadpool_task_status() must be performed on
+ * the task separately once it is in LWS_TP_STATUS_STOPPED to free the task.
+ *
+ * DEPRECATED: You should use lws_threadpool_dequeue_task() with
+ * lws_threadpool_get_task_wsi() / _ss() if you know there can only be one task
+ * per connection, or call it via lws_threadpool_foreach_task_wsi() / _ss() to
+ * get the tasks bound to the connection.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_threadpool_dequeue(struct lws *wsi) LWS_WARN_DEPRECATED;
+
+LWS_VISIBLE LWS_EXTERN int
+lws_threadpool_dequeue_task(struct lws_threadpool_task *task);
+
+
+/**
+ * lws_threadpool_task_status() - reap completed tasks
+ *
+ * \param wsi: the wsi to query the current task of
+ * \param task: receives a pointer to the opaque task
+ * \param user: receives a void * pointer to the task user data
+ *
+ * This is the equivalent of posix waitpid()... it returns the status of the
+ * task, and if the task is in state LWS_TP_STATUS_FINISHED or
+ * LWS_TP_STATUS_STOPPED, frees \p task.  If in another state, the task
+ * continues to exist.
+ *
+ * This is designed to be called from the service thread.
+ *
+ * Its use is to make sure the service thread has seen the state of the task
+ * before deleting it.
+ *
+ * DEPRECATED... use lws_threadpool_task_status() instead and get the task
+ * pointer from lws_threadpool_get_task_wsi() / _ss() if you know there can only
+ * be one, else call it via lws_threadpool_foreach_task_wsi() / _ss()
+ */
+LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status
+lws_threadpool_task_status_wsi(struct lws *wsi,
+			       struct lws_threadpool_task **task, void **user)
+				LWS_WARN_DEPRECATED;
+
+LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status
+lws_threadpool_task_status(struct lws_threadpool_task *task, void **user);
+
+LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status
+lws_threadpool_task_status_noreap(struct lws_threadpool_task *task);
+
+/**
+ * lws_threadpool_task_sync() - Indicate to a stalled task it may continue
+ *
+ * \param task: the task to unblock
+ * \param stop: 0 = run after unblock, 1 = when he unblocks, stop him
+ *
+ * Inform the task that the service thread has finished with the shared data
+ * and that the task, if blocked in LWS_TP_RETURN_SYNC, may continue.
+ *
+ * If the lws service context determined that the task must be aborted, it
+ * should still call this but with stop = 1, causing the task to finish.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_threadpool_task_sync(struct lws_threadpool_task *task, int stop);
+
+/**
+ * lws_threadpool_dump() - dump the state of a threadpool to the log
+ *
+ * \param tp: The threadpool to dump
+ *
+ * This locks the threadpool and then dumps the pending queue, the worker
+ * threads and the done queue, together with time information for how long
+ * the tasks have been in their current state, how long they have occupied a
+ * thread, etc.
+ *
+ * This only does anything on lws builds with CMAKE_BUILD_TYPE=DEBUG, otherwise
+ * while it still exists, it's a NOP.
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_threadpool_dump(struct lws_threadpool *tp);
+
+
+
+LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task *
+lws_threadpool_get_task_wsi(struct lws *wsi);
+
+#if defined(LWS_WITH_SECURE_STREAMS)
+LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task *
+lws_threadpool_get_task_ss(struct lws_ss_handle *ss);
+#endif
+
+
+LWS_VISIBLE LWS_EXTERN int
+lws_threadpool_foreach_task_wsi(struct lws *wsi, void *user,
+				int (*cb)(struct lws_threadpool_task *task,
+					  void *user));
+
+#if defined(LWS_WITH_SECURE_STREAMS)
+LWS_VISIBLE LWS_EXTERN int
+lws_threadpool_foreach_task_ss(struct lws_ss_handle *ss, void *user,
+		int (*cb)(struct lws_threadpool_task *task, void *user));
+#endif
+
+
+//@}

include/libwebsockets/lws-timeout-timer.h

@@ -0,0 +1,304 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup timeout Connection timeouts
+
+    APIs related to setting connection timeouts
+*/
+//@{
+
+/*
+ * NOTE: These public enums are part of the abi.  If you want to add one,
+ * add it at where specified so existing users are unaffected.
+ */
+enum pending_timeout {
+	NO_PENDING_TIMEOUT					=  0,
+	PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE			=  1,
+	PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE		=  2,
+	PENDING_TIMEOUT_ESTABLISH_WITH_SERVER			=  3,
+	PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE		=  4,
+	PENDING_TIMEOUT_AWAITING_PING				=  5,
+	PENDING_TIMEOUT_CLOSE_ACK				=  6,
+	PENDING_TIMEOUT_UNUSED1					=  7,
+	PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE			=  8,
+	PENDING_TIMEOUT_SSL_ACCEPT				=  9,
+	PENDING_TIMEOUT_HTTP_CONTENT				= 10,
+	PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND			= 11,
+	PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE			= 12,
+	PENDING_TIMEOUT_SHUTDOWN_FLUSH				= 13,
+	PENDING_TIMEOUT_CGI					= 14,
+	PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE			= 15,
+	PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING			= 16,
+	PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG			= 17,
+	PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD			= 18,
+	PENDING_TIMEOUT_AWAITING_SOCKS_GREETING_REPLY	        = 19,
+	PENDING_TIMEOUT_AWAITING_SOCKS_CONNECT_REPLY		= 20,
+	PENDING_TIMEOUT_AWAITING_SOCKS_AUTH_REPLY		= 21,
+	PENDING_TIMEOUT_KILLED_BY_SSL_INFO			= 22,
+	PENDING_TIMEOUT_KILLED_BY_PARENT			= 23,
+	PENDING_TIMEOUT_CLOSE_SEND				= 24,
+	PENDING_TIMEOUT_HOLDING_AH				= 25,
+	PENDING_TIMEOUT_UDP_IDLE				= 26,
+	PENDING_TIMEOUT_CLIENT_CONN_IDLE			= 27,
+	PENDING_TIMEOUT_LAGGING					= 28,
+	PENDING_TIMEOUT_THREADPOOL				= 29,
+	PENDING_TIMEOUT_THREADPOOL_TASK				= 30,
+	PENDING_TIMEOUT_KILLED_BY_PROXY_CLIENT_CLOSE		= 31,
+	PENDING_TIMEOUT_USER_OK					= 32,
+
+	/****** add new things just above ---^ ******/
+
+	PENDING_TIMEOUT_USER_REASON_BASE			= 1000
+};
+
+#define lws_time_in_microseconds lws_now_usecs
+
+#define LWS_TO_KILL_ASYNC -1
+/**< If LWS_TO_KILL_ASYNC is given as the timeout sec in a lws_set_timeout()
+ * call, then the connection is marked to be killed at the next timeout
+ * check.  This is how you should force-close the wsi being serviced if
+ * you are doing it outside the callback (where you should close by nonzero
+ * return).
+ */
+#define LWS_TO_KILL_SYNC -2
+/**< If LWS_TO_KILL_SYNC is given as the timeout sec in a lws_set_timeout()
+ * call, then the connection is closed before returning (which may delete
+ * the wsi).  This should only be used where the wsi being closed is not the
+ * wsi currently being serviced.
+ */
+/**
+ * lws_set_timeout() - marks the wsi as subject to a timeout some seconds hence
+ *
+ * \param wsi:	Websocket connection instance
+ * \param reason:	timeout reason
+ * \param secs:	how many seconds.  You may set to LWS_TO_KILL_ASYNC to
+ *		force the connection to timeout at the next opportunity, or
+ *		LWS_TO_KILL_SYNC to close it synchronously if you know the
+ *		wsi is not the one currently being serviced.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
+
+/**
+ * lws_set_timeout_us() - marks the wsi as subject to a timeout some us hence
+ *
+ * \param wsi:	Websocket connection instance
+ * \param reason:	timeout reason
+ * \param us:	0 removes the timeout, otherwise number of us to wait
+ *
+ * Higher-resolution version of lws_set_timeout().  Actual resolution depends
+ * on platform and load, usually ms.
+ */
+void
+lws_set_timeout_us(struct lws *wsi, enum pending_timeout reason, lws_usec_t us);
+
+/* helper for clearer LWS_TO_KILL_ASYNC / LWS_TO_KILL_SYNC usage */
+#define lws_wsi_close(w, to_kill) lws_set_timeout(w, 1, to_kill)
+
+
+#define LWS_SET_TIMER_USEC_CANCEL ((lws_usec_t)-1ll)
+#define LWS_USEC_PER_SEC ((lws_usec_t)1000000)
+
+/**
+ * lws_set_timer_usecs() - schedules a callback on the wsi in the future
+ *
+ * \param wsi:	Websocket connection instance
+ * \param usecs:  LWS_SET_TIMER_USEC_CANCEL removes any existing scheduled
+ *		  callback, otherwise number of microseconds in the future
+ *		  the callback will occur at.
+ *
+ * NOTE: event loop support for this:
+ *
+ *  default poll() loop:   yes
+ *  libuv event loop:      yes
+ *  libev:    not implemented (patch welcome)
+ *  libevent: not implemented (patch welcome)
+ *
+ * After the deadline expires, the wsi will get a callback of type
+ * LWS_CALLBACK_TIMER and the timer is exhausted.  The deadline may be
+ * continuously deferred by further calls to lws_set_timer_usecs() with a later
+ * deadline, or cancelled by lws_set_timer_usecs(wsi, -1).
+ *
+ * If the timer should repeat, lws_set_timer_usecs() must be called again from
+ * LWS_CALLBACK_TIMER.
+ *
+ * Accuracy depends on the platform and the load on the event loop or system...
+ * all that's guaranteed is the callback will come after the requested wait
+ * period.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_set_timer_usecs(struct lws *wsi, lws_usec_t usecs);
+
+struct lws_sorted_usec_list;
+
+typedef void (*sul_cb_t)(struct lws_sorted_usec_list *sul);
+
+typedef struct lws_sorted_usec_list {
+	struct lws_dll2 list;	/* simplify the code by keeping this at start */
+	lws_usec_t	us;
+	sul_cb_t	cb;
+	uint32_t	latency_us;	/* us it may safely be delayed */
+} lws_sorted_usec_list_t;
+
+/*
+ * There are multiple sul owners to allow accounting for, a) events that must
+ * wake from suspend, and b) events that can be missued due to suspend
+ */
+#define LWS_COUNT_PT_SUL_OWNERS			2
+
+#define LWSSULLI_MISS_IF_SUSPENDED		0
+#define LWSSULLI_WAKE_IF_SUSPENDED		1
+
+/*
+ * lws_sul2_schedule() - schedule a callback
+ *
+ * \param context: the lws_context
+ * \param tsi: the thread service index (usually 0)
+ * \param flags: LWSSULLI_...
+ * \param sul: pointer to the sul element
+ *
+ * Generic callback-at-a-later time function.  The callback happens on the
+ * event loop thread context.
+ *
+ * Although the api has us resultion, the actual resolution depends on the
+ * platform and may be, eg, 1ms.
+ *
+ * This doesn't allocate and doesn't fail.
+ *
+ * If flags contains LWSSULLI_WAKE_IF_SUSPENDED, the scheduled event is placed
+ * on a sul owner list that, if the system has entered low power suspend mode,
+ * tries to arrange that the system should wake from platform suspend just
+ * before the event is due.  Scheduled events without this flag will be missed
+ * in the case the system is in suspend and nothing else happens to have woken
+ * it.
+ *
+ * You can call it again with another us value to change the delay or move the
+ * event to a different owner (ie, wake or miss on suspend).
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_sul2_schedule(struct lws_context *context, int tsi, int flags,
+		  lws_sorted_usec_list_t *sul);
+
+/*
+ * lws_sul_cancel() - cancel scheduled callback
+ *
+ * \param sul: pointer to the sul element
+ *
+ * If it's scheduled, remove the sul from its owning sorted list.
+ * If not scheduled, it's a NOP.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_sul_cancel(lws_sorted_usec_list_t *sul);
+
+/*
+ * lws_sul_earliest_wakeable_event() - get earliest wake-from-suspend event
+ *
+ * \param ctx: the lws context
+ * \param pearliest: pointer to lws_usec_t to take the result
+ *
+ * Either returns 1 if no pending event, or 0 and sets *pearliest to the
+ * MONOTONIC time of the current earliest next expected event.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_sul_earliest_wakeable_event(struct lws_context *ctx, lws_usec_t *pearliest);
+
+/*
+ * For backwards compatibility
+ *
+ * If us is LWS_SET_TIMER_USEC_CANCEL, the sul is removed from the scheduler.
+ * New code can use lws_sul_cancel()
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_sul_schedule(struct lws_context *ctx, int tsi, lws_sorted_usec_list_t *sul,
+		 sul_cb_t _cb, lws_usec_t _us);
+LWS_VISIBLE LWS_EXTERN void
+lws_sul_schedule_wakesuspend(struct lws_context *ctx, int tsi,
+			     lws_sorted_usec_list_t *sul, sul_cb_t _cb,
+			     lws_usec_t _us);
+
+#if defined(LWS_WITH_SUL_DEBUGGING)
+/**
+ * lws_sul_debug_zombies() - assert there are no scheduled sul in a given object
+ *
+ * \param ctx: lws_context
+ * \param po: pointer to the object that is about to be destroyed
+ * \param len: length of the object that is about to be destroyed
+ * \param destroy_description: string clue what any failure is related to
+ *
+ * This is an optional debugging helper that walks the sul scheduler lists
+ * confirming that there are no suls scheduled that live inside the object
+ * footprint described by po and len.  When internal objects are about to be
+ * destroyed, like wsi / user_data or secure stream handles, if
+ * LWS_WITH_SUL_DEBUGGING is enabled the scheduler is checked for anything
+ * in the object being destroyed.  If something found, an error is printed and
+ * an assert fired.
+ *
+ * Internal sul like timeouts should always be cleaned up correctly, but user
+ * suls in, eg, wsi user_data area, or in secure stream user allocation, may be
+ * the cause of difficult to find bugs if valgrind not available and the user
+ * code left a sul in the scheduler after destroying the object the sul was
+ * living in.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_sul_debug_zombies(struct lws_context *ctx, void *po, size_t len,
+		      const char *destroy_description);
+#else
+#define lws_sul_debug_zombies(_a, _b, _c, _d)
+#endif
+
+/*
+ * lws_validity_confirmed() - reset the validity timer for a network connection
+ *
+ * \param wsi: the connection that saw traffic proving the connection valid
+ *
+ * Network connections are subject to intervals defined by the context, the
+ * vhost if server connections, or the client connect info if a client
+ * connection.  If the connection goes longer than the specified time since
+ * last observing traffic that can only happen if traffic is passing in both
+ * directions, then lws will try to create a PING transaction on the network
+ * connection.
+ *
+ * If the connection reaches the specified `.secs_since_valid_hangup` time
+ * still without any proof of validity, the connection will be closed.
+ *
+ * If the PONG comes, or user code observes traffic that satisfies the proof
+ * that both directions are passing traffic to the peer and calls this api,
+ * the connection validity timer is reset and the scheme repeats.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_validity_confirmed(struct lws *wsi);
+
+/*
+ * These are not normally needed, they're exported for the case there's code
+ * using lws_sul for which lws is an optional link dependency.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+__lws_sul_insert(lws_dll2_owner_t *own, lws_sorted_usec_list_t *sul);
+
+LWS_VISIBLE LWS_EXTERN lws_usec_t
+__lws_sul_service_ripe(lws_dll2_owner_t *own, int own_len, lws_usec_t usnow);
+
+///@}

include/libwebsockets/lws-tls-sessions.h

@@ -0,0 +1,81 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup tls_sessions TLS Session Management
+
+    APIs related to managing TLS Sessions
+*/
+//@{
+
+
+#define LWS_SESSION_TAG_LEN 96
+
+struct lws_tls_session_dump
+{
+	char			tag[LWS_SESSION_TAG_LEN];
+	void			*blob;
+        void			*opaque;
+	size_t			blob_len;
+};
+
+typedef int (*lws_tls_sess_cb_t)(struct lws_context *cx,
+				 struct lws_tls_session_dump *info);
+
+/**
+ * lws_tls_session_dump_save() - serialize a tls session via a callback
+ *
+ * \param vh: the vhost to load into the session cache
+ * \param host: the name of the host the session relates to
+ * \param port: the port the session connects to on the host
+ * \param cb_save: the callback to perform the saving of the session blob
+ * \param opq: an opaque pointer passed into the callback
+ *
+ * If a session matching the vhost/host/port exists in the vhost's session
+ * cache, serialize it via the provided callback.
+ *
+ * \p opq is passed to the callback without being used by lws at all.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_tls_session_dump_save(struct lws_vhost *vh, const char *host, uint16_t port,
+			  lws_tls_sess_cb_t cb_save, void *opq);
+
+/**
+ * lws_tls_session_dump_load() - deserialize a tls session via a callback
+ *
+ * \param vh: the vhost to load into the session cache
+ * \param host: the name of the host the session relates to
+ * \param port: the port the session connects to on the host
+ * \param cb_load: the callback to retreive the session blob from
+ * \param opq: an opaque pointer passed into the callback
+ *
+ * Try to preload a session described by the first three parameters into the
+ * client session cache, from the given callback.
+ *
+ * \p opq is passed to the callback without being used by lws at all.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_tls_session_dump_load(struct lws_vhost *vh, const char *host, uint16_t port,
+			  lws_tls_sess_cb_t cb_load, void *opq);
+
+///@}

include/libwebsockets/lws-tokenize.h

@@ -0,0 +1,272 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/* Do not treat - as a terminal character, so "my-token" is one token */
+#define LWS_TOKENIZE_F_MINUS_NONTERM	(1 << 0)
+/* Separately report aggregate colon-delimited tokens */
+#define LWS_TOKENIZE_F_AGG_COLON	(1 << 1)
+/* Enforce sequencing for a simple token , token , token ... list */
+#define LWS_TOKENIZE_F_COMMA_SEP_LIST	(1 << 2)
+/* Allow more characters in the tokens and less delimiters... default is
+ * only alphanumeric + underscore in tokens */
+#define LWS_TOKENIZE_F_RFC7230_DELIMS	(1 << 3)
+/* Do not treat . as a terminal character, so "warmcat.com" is one token */
+#define LWS_TOKENIZE_F_DOT_NONTERM	(1 << 4)
+/* If something starts looking like a float, like 1.2, force to be string token.
+ * This lets you receive dotted-quads like 192.168.0.1 as string tokens, and
+ * avoids illegal float format detection like 1.myserver.com */
+#define LWS_TOKENIZE_F_NO_FLOATS	(1 << 5)
+/* Instead of LWS_TOKZE_INTEGER, report integers as any other string token */
+#define LWS_TOKENIZE_F_NO_INTEGERS	(1 << 6)
+/* # makes the rest of the line a comment */
+#define LWS_TOKENIZE_F_HASH_COMMENT	(1 << 7)
+/* Do not treat / as a terminal character, so "multipart/related" is one token */
+#define LWS_TOKENIZE_F_SLASH_NONTERM	(1 << 8)
+/* Do not treat * as a terminal character, so "myfile*" is one token */
+#define LWS_TOKENIZE_F_ASTERISK_NONTERM	(1 << 9)
+/* Do not treat = as a terminal character, so "x=y" is one token */
+#define LWS_TOKENIZE_F_EQUALS_NONTERM	(1 << 10)
+
+typedef enum {
+
+	LWS_TOKZE_ERRS			=  5, /* the number of errors defined */
+
+	LWS_TOKZE_ERR_BROKEN_UTF8	= -5,	/* malformed or partial utf8 */
+	LWS_TOKZE_ERR_UNTERM_STRING	= -4,	/* ended while we were in "" */
+	LWS_TOKZE_ERR_MALFORMED_FLOAT	= -3,	/* like 0..1 or 0.1.1 */
+	LWS_TOKZE_ERR_NUM_ON_LHS	= -2,	/* like 123= or 0.1= */
+	LWS_TOKZE_ERR_COMMA_LIST	= -1,	/* like ",tok", or, "tok,," */
+
+	LWS_TOKZE_ENDED = 0,		/* no more content */
+
+	/* Note: results have ordinal 1+, EOT is 0 and errors are < 0 */
+
+	LWS_TOKZE_DELIMITER,		/* a delimiter appeared */
+	LWS_TOKZE_TOKEN,		/* a token appeared */
+	LWS_TOKZE_INTEGER,		/* an integer appeared */
+	LWS_TOKZE_FLOAT,		/* a float appeared */
+	LWS_TOKZE_TOKEN_NAME_EQUALS,	/* token [whitespace] = */
+	LWS_TOKZE_TOKEN_NAME_COLON,	/* token [whitespace] : (only with
+					   LWS_TOKENIZE_F_AGG_COLON flag) */
+	LWS_TOKZE_QUOTED_STRING,	/* "*", where * may have any char */
+
+} lws_tokenize_elem;
+
+/*
+ * helper enums to allow caller to enforce legal delimiter sequencing, eg
+ * disallow "token,,token", "token,", and ",token"
+ */
+
+enum lws_tokenize_delimiter_tracking {
+	LWSTZ_DT_NEED_FIRST_CONTENT,
+	LWSTZ_DT_NEED_DELIM,
+	LWSTZ_DT_NEED_NEXT_CONTENT,
+};
+
+typedef struct lws_tokenize {
+	const char *start; /**< set to the start of the string to tokenize */
+	const char *token; /**< the start of an identified token or delimiter */
+	size_t len;	/**< set to the length of the string to tokenize */
+	size_t token_len;	/**< the length of the identied token or delimiter */
+
+	uint16_t flags;	/**< optional LWS_TOKENIZE_F_ flags, or 0 */
+	uint8_t delim;
+
+	int8_t e; /**< convenient for storing lws_tokenize return */
+} lws_tokenize_t;
+
+/**
+ * lws_tokenize() - breaks down a string into tokens and delimiters in-place
+ *
+ * \param ts: the lws_tokenize struct to init
+ * \param start: the string to tokenize
+ * \param flags: LWS_TOKENIZE_F_ option flags
+ *
+ * This initializes the tokenize struct to point to the given string, and
+ * sets the length to 2GiB - 1 (so there must be a terminating NUL)... you can
+ * override this requirement by setting ts.len yourself before using it.
+ *
+ * .delim is also initialized to LWSTZ_DT_NEED_FIRST_CONTENT.
+ */
+
+LWS_VISIBLE LWS_EXTERN void
+lws_tokenize_init(struct lws_tokenize *ts, const char *start, int flags);
+
+/**
+ * lws_tokenize() - breaks down a string into tokens and delimiters in-place
+ *
+ * \param ts: the lws_tokenize struct with information and state on what to do
+ *
+ * The \p ts struct should have its start, len and flags members initialized to
+ * reflect the string to be tokenized and any options.
+ *
+ * Then `lws_tokenize()` may be called repeatedly on the struct, returning one
+ * of `lws_tokenize_elem` each time, and with the struct's `token` and
+ * `token_len` members set to describe the content of the delimiter or token
+ * payload each time.
+ *
+ * There are no allocations during the process.
+ *
+ * returns lws_tokenize_elem that was identified (LWS_TOKZE_ENDED means reached
+ * the end of the string).
+ */
+
+LWS_VISIBLE LWS_EXTERN lws_tokenize_elem
+lws_tokenize(struct lws_tokenize *ts);
+
+/**
+ * lws_tokenize_cstr() - copy token string to NUL-terminated buffer
+ *
+ * \param ts: pointer to lws_tokenize struct to operate on
+ * \param str: destination buffer
+ * \pparam max: bytes in destination buffer
+ *
+ * returns 0 if OK or nonzero if the string + NUL won't fit.
+ */
+
+LWS_VISIBLE LWS_EXTERN int
+lws_tokenize_cstr(struct lws_tokenize *ts, char *str, size_t max);
+
+
+/*
+ * lws_strexp: flexible string expansion helper api
+ *
+ * This stateful helper can handle multiple separate input chunks and multiple
+ * output buffer loads with arbitrary boundaries between literals and expanded
+ * symbols.  This allows it to handle fragmented input as well as arbitrarily
+ * long symbol expansions that are bigger than the output buffer itself.
+ *
+ * A user callback is used to convert symbol names to the symbol value.
+ *
+ * A single byte buffer for input and another for output can process any
+ * length substitution then.  The state object is around 64 bytes on a 64-bit
+ * system and it only uses 8 bytes stack.
+ */
+
+
+typedef int (*lws_strexp_expand_cb)(void *priv, const char *name, char *out,
+				    size_t *pos, size_t olen, size_t *exp_ofs);
+
+typedef struct lws_strexp {
+	char			name[32];
+	lws_strexp_expand_cb	cb;
+	void			*priv;
+	char			*out;
+	size_t			olen;
+	size_t			pos;
+
+	size_t			exp_ofs;
+
+	uint8_t			name_pos;
+	char			state;
+} lws_strexp_t;
+
+enum {
+	LSTRX_DONE,			/* it completed OK */
+	LSTRX_FILLED_OUT,		/* out buf filled and needs resetting */
+	LSTRX_FATAL_NAME_TOO_LONG = -1,	/* fatal */
+	LSTRX_FATAL_NAME_UNKNOWN  = -2,
+};
+
+
+/**
+ * lws_strexp_init() - initialize an lws_strexp_t for use
+ *
+ * \p exp: the exp object to init
+ * \p priv: the user's object pointer to pass to callback
+ * \p cb: the callback to expand named objects
+ * \p out: the start of the output buffer, or NULL just to get the length
+ * \p olen: the length of the output buffer in bytes
+ *
+ * Prepares an lws_strexp_t for use and sets the initial output buffer
+ *
+ * If \p out is NULL, substitution proceeds normally, but no output is produced,
+ * only the length is returned.  olen should be set to the largest feasible
+ * overall length.  To use this mode, the substitution callback must also check
+ * for NULL \p out and avoid producing the output.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_strexp_init(lws_strexp_t *exp, void *priv, lws_strexp_expand_cb cb,
+		char *out, size_t olen);
+
+/**
+ * lws_strexp_reset_out() - reset the output buffer on an existing strexp
+ *
+ * \p exp: the exp object to init
+ * \p out: the start of the output buffer, or NULL to just get length
+ * \p olen: the length of the output buffer in bytes
+ *
+ * Provides a new output buffer for lws_strexp_expand() to continue to write
+ * into.  It can be the same as the old one if it has been copied out or used.
+ * The position of the next write will be reset to the start of the given buf.
+ *
+ * If \p out is NULL, substitution proceeds normally, but no output is produced,
+ * only the length is returned.  \p olen should be set to the largest feasible
+ * overall length.  To use this mode, the substitution callback must also check
+ * for NULL \p out and avoid producing the output.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_strexp_reset_out(lws_strexp_t *exp, char *out, size_t olen);
+
+/**
+ * lws_strexp_expand() - copy / expand a string into the output buffer
+ *
+ * \p exp: the exp object for the copy / expansion
+ * \p in: the start of the next input data
+ * \p len: the length of the input data
+ * \p pused_in: pointer to write the amount of input used
+ * \p pused_out: pointer to write the amount of output used
+ *
+ * Copies in to the output buffer set in exp, expanding any ${name} tokens using
+ * the callback.  \p *pused_in is set to the number of input chars used and
+ * \p *pused_out the number of output characters used
+ *
+ * May return LSTRX_FILLED_OUT early with *pused < len if the output buffer is
+ * filled.  Handle the output buffer and reset it with lws_strexp_reset_out()
+ * before calling again with adjusted in / len to continue.
+ *
+ * In the case of large expansions, the expansion itself may fill the output
+ * buffer, in which case the expansion callback returns the LSTRX_FILLED_OUT
+ * and will be called again to continue with its *exp_ofs parameter set
+ * appropriately.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_strexp_expand(lws_strexp_t *exp, const char *in, size_t len,
+		  size_t *pused_in, size_t *pused_out);
+
+/**
+ * lws_strcmp_wildcard() - strcmp but the first arg can have wildcards
+ *
+ * \p wildcard: a string that may contain zero to three *, and may lack a NUL
+ * \p wlen: length of the wildcard string
+ * \p check: string to test to see if it matches wildcard
+ * \p clen: length of check string
+ *
+ * Like strcmp, but supports patterns like "a*", "a*b", "a*b*" etc
+ * where a and b are arbitrary substrings.  Both the wc and check strings need
+ * not be NUL terminated, but are specified by lengths.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_strcmp_wildcard(const char *wildcard, size_t wlen, const char *check,
+		    size_t clen);

include/libwebsockets/lws-vfs.h

@@ -0,0 +1,273 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup fops file operation wrapping
+ *
+ * ##File operation wrapping
+ *
+ * Use these helper functions if you want to access a file from the perspective
+ * of a specific wsi, which is usually the case.  If you just want contextless
+ * file access, use the fops callbacks directly with NULL wsi instead of these
+ * helpers.
+ *
+ * If so, then it calls the platform handler or user overrides where present
+ * (as defined in info->fops)
+ *
+ * The advantage from all this is user code can be portable for file operations
+ * without having to deal with differences between platforms.
+ */
+//@{
+
+/** struct lws_plat_file_ops - Platform-specific file operations
+ *
+ * These provide platform-agnostic ways to deal with filesystem access in the
+ * library and in the user code.
+ */
+
+#if defined(LWS_PLAT_FREERTOS)
+/* sdk preprocessor defs? compiler issue? gets confused with member names */
+#define LWS_FOP_OPEN		_open
+#define LWS_FOP_CLOSE		_close
+#define LWS_FOP_SEEK_CUR	_seek_cur
+#define LWS_FOP_READ		_read
+#define LWS_FOP_WRITE		_write
+#else
+#define LWS_FOP_OPEN		open
+#define LWS_FOP_CLOSE		close
+#define LWS_FOP_SEEK_CUR	seek_cur
+#define LWS_FOP_READ		read
+#define LWS_FOP_WRITE		write
+#endif
+
+#define LWS_FOP_FLAGS_MASK		   ((1 << 23) - 1)
+#define LWS_FOP_FLAG_COMPR_ACCEPTABLE_GZIP (1 << 24)
+#define LWS_FOP_FLAG_COMPR_IS_GZIP	   (1 << 25)
+#define LWS_FOP_FLAG_MOD_TIME_VALID	   (1 << 26)
+#define LWS_FOP_FLAG_VIRTUAL		   (1 << 27)
+
+struct lws_plat_file_ops;
+
+struct lws_fop_fd {
+	lws_filefd_type			fd;
+	/**< real file descriptor related to the file... */
+	const struct lws_plat_file_ops	*fops;
+	/**< fops that apply to this fop_fd */
+	void				*filesystem_priv;
+	/**< ignored by lws; owned by the fops handlers */
+	lws_filepos_t			pos;
+	/**< generic "position in file" */
+	lws_filepos_t			len;
+	/**< generic "length of file" */
+	lws_fop_flags_t			flags;
+	/**< copy of the returned flags */
+	uint32_t			mod_time;
+	/**< optional "modification time of file", only valid if .open()
+	 * set the LWS_FOP_FLAG_MOD_TIME_VALID flag */
+};
+typedef struct lws_fop_fd *lws_fop_fd_t;
+
+struct lws_fops_index {
+	const char *sig;	/* NULL or vfs signature, eg, ".zip/" */
+	uint8_t len;		/* length of above string */
+};
+
+struct lws_plat_file_ops {
+	lws_fop_fd_t (*LWS_FOP_OPEN)(const struct lws_plat_file_ops *fops,
+				     const char *filename, const char *vpath,
+				     lws_fop_flags_t *flags);
+	/**< Open file (always binary access if plat supports it)
+	 * vpath may be NULL, or if the fops understands it, the point at which
+	 * the filename's virtual part starts.
+	 * *flags & LWS_FOP_FLAGS_MASK should be set to O_RDONLY or O_RDWR.
+	 * If the file may be gzip-compressed,
+	 * LWS_FOP_FLAG_COMPR_ACCEPTABLE_GZIP is set.  If it actually is
+	 * gzip-compressed, then the open handler should OR
+	 * LWS_FOP_FLAG_COMPR_IS_GZIP on to *flags before returning.
+	 */
+	int (*LWS_FOP_CLOSE)(lws_fop_fd_t *fop_fd);
+	/**< close file AND set the pointer to NULL */
+	lws_fileofs_t (*LWS_FOP_SEEK_CUR)(lws_fop_fd_t fop_fd,
+					  lws_fileofs_t offset_from_cur_pos);
+	/**< seek from current position */
+	int (*LWS_FOP_READ)(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
+			    uint8_t *buf, lws_filepos_t len);
+	/**< Read from file, on exit *amount is set to amount actually read */
+	int (*LWS_FOP_WRITE)(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
+			     uint8_t *buf, lws_filepos_t len);
+	/**< Write to file, on exit *amount is set to amount actually written */
+
+	struct lws_fops_index fi[3];
+	/**< vfs path signatures implying use of this fops */
+
+	const struct lws_plat_file_ops *next;
+	/**< NULL or next fops in list */
+
+	/* Add new things just above here ---^
+	 * This is part of the ABI, don't needlessly break compatibility */
+};
+
+/**
+ * lws_get_fops() - get current file ops
+ *
+ * \param context: context
+ */
+LWS_VISIBLE LWS_EXTERN struct lws_plat_file_ops * LWS_WARN_UNUSED_RESULT
+lws_get_fops(struct lws_context *context);
+LWS_VISIBLE LWS_EXTERN void
+lws_set_fops(struct lws_context *context, const struct lws_plat_file_ops *fops);
+/**
+ * lws_vfs_tell() - get current file position
+ *
+ * \param fop_fd: fop_fd we are asking about
+ */
+LWS_VISIBLE LWS_EXTERN lws_filepos_t LWS_WARN_UNUSED_RESULT
+lws_vfs_tell(lws_fop_fd_t fop_fd);
+/**
+ * lws_vfs_get_length() - get current file total length in bytes
+ *
+ * \param fop_fd: fop_fd we are asking about
+ */
+LWS_VISIBLE LWS_EXTERN lws_filepos_t LWS_WARN_UNUSED_RESULT
+lws_vfs_get_length(lws_fop_fd_t fop_fd);
+/**
+ * lws_vfs_get_mod_time() - get time file last modified
+ *
+ * \param fop_fd: fop_fd we are asking about
+ */
+LWS_VISIBLE LWS_EXTERN uint32_t LWS_WARN_UNUSED_RESULT
+lws_vfs_get_mod_time(lws_fop_fd_t fop_fd);
+/**
+ * lws_vfs_file_seek_set() - seek relative to start of file
+ *
+ * \param fop_fd: fop_fd we are seeking in
+ * \param offset: offset from start of file
+ */
+LWS_VISIBLE LWS_EXTERN lws_fileofs_t
+lws_vfs_file_seek_set(lws_fop_fd_t fop_fd, lws_fileofs_t offset);
+/**
+ * lws_vfs_file_seek_end() - seek relative to end of file
+ *
+ * \param fop_fd: fop_fd we are seeking in
+ * \param offset: offset from start of file
+ */
+LWS_VISIBLE LWS_EXTERN lws_fileofs_t
+lws_vfs_file_seek_end(lws_fop_fd_t fop_fd, lws_fileofs_t offset);
+
+extern struct lws_plat_file_ops fops_zip;
+
+/**
+ * lws_plat_file_open() - open vfs filepath
+ *
+ * \param fops: file ops struct that applies to this descriptor
+ * \param vfs_path: filename to open
+ * \param flags: pointer to open flags
+ *
+ * The vfs_path is scanned for known fops signatures, and the open directed
+ * to any matching fops open.
+ *
+ * User code should use this api to perform vfs opens.
+ *
+ * returns semi-opaque handle
+ */
+LWS_VISIBLE LWS_EXTERN lws_fop_fd_t LWS_WARN_UNUSED_RESULT
+lws_vfs_file_open(const struct lws_plat_file_ops *fops, const char *vfs_path,
+		  lws_fop_flags_t *flags);
+
+/**
+ * lws_plat_file_close() - close file
+ *
+ * \param fop_fd: file handle to close
+ */
+static LWS_INLINE int
+lws_vfs_file_close(lws_fop_fd_t *fop_fd)
+{
+	if (*fop_fd && (*fop_fd)->fops)
+		return (*fop_fd)->fops->LWS_FOP_CLOSE(fop_fd);
+
+	return 0;
+}
+
+/**
+ * lws_plat_file_seek_cur() - close file
+ *
+ *
+ * \param fop_fd: file handle
+ * \param offset: position to seek to
+ */
+static LWS_INLINE lws_fileofs_t
+lws_vfs_file_seek_cur(lws_fop_fd_t fop_fd, lws_fileofs_t offset)
+{
+	return fop_fd->fops->LWS_FOP_SEEK_CUR(fop_fd, offset);
+}
+/**
+ * lws_plat_file_read() - read from file
+ *
+ * \param fop_fd: file handle
+ * \param amount: how much to read (rewritten by call)
+ * \param buf: buffer to write to
+ * \param len: max length
+ */
+static LWS_INLINE int LWS_WARN_UNUSED_RESULT
+lws_vfs_file_read(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
+		   uint8_t *buf, lws_filepos_t len)
+{
+	return fop_fd->fops->LWS_FOP_READ(fop_fd, amount, buf, len);
+}
+/**
+ * lws_plat_file_write() - write from file
+ *
+ * \param fop_fd: file handle
+ * \param amount: how much to write (rewritten by call)
+ * \param buf: buffer to read from
+ * \param len: max length
+ */
+static LWS_INLINE int LWS_WARN_UNUSED_RESULT
+lws_vfs_file_write(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
+		    uint8_t *buf, lws_filepos_t len)
+{
+	return fop_fd->fops->LWS_FOP_WRITE(fop_fd, amount, buf, len);
+}
+
+/* these are the platform file operations implementations... they can
+ * be called directly and used in fops arrays
+ */
+
+LWS_VISIBLE LWS_EXTERN lws_fop_fd_t
+_lws_plat_file_open(const struct lws_plat_file_ops *fops, const char *filename,
+		    const char *vpath, lws_fop_flags_t *flags);
+LWS_VISIBLE LWS_EXTERN int
+_lws_plat_file_close(lws_fop_fd_t *fop_fd);
+LWS_VISIBLE LWS_EXTERN lws_fileofs_t
+_lws_plat_file_seek_cur(lws_fop_fd_t fop_fd, lws_fileofs_t offset);
+LWS_VISIBLE LWS_EXTERN int
+_lws_plat_file_read(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
+		    uint8_t *buf, lws_filepos_t len);
+LWS_VISIBLE LWS_EXTERN int
+_lws_plat_file_write(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
+		     uint8_t *buf, lws_filepos_t len);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_alloc_vfs_file(struct lws_context *context, const char *filename,
+		   uint8_t **buf, lws_filepos_t *amount);
+//@}

include/libwebsockets/lws-write.h

@@ -0,0 +1,276 @@
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/*! \defgroup sending-data Sending data
+
+    APIs related to writing data on a connection
+*/
+//@{
+#if !defined(LWS_SIZEOFPTR)
+#define LWS_SIZEOFPTR ((int)sizeof (void *))
+#endif
+
+#if defined(__x86_64__)
+#define _LWS_PAD_SIZE 16	/* Intel recommended for best performance */
+#else
+#define _LWS_PAD_SIZE LWS_SIZEOFPTR   /* Size of a pointer on the target arch */
+#endif
+#define _LWS_PAD(n) (((n) % _LWS_PAD_SIZE) ? \
+		((n) + (_LWS_PAD_SIZE - ((n) % _LWS_PAD_SIZE))) : (n))
+/* last 2 is for lws-meta */
+#define LWS_PRE _LWS_PAD(4 + 10 + 2)
+/* used prior to 1.7 and retained for backward compatibility */
+#define LWS_SEND_BUFFER_PRE_PADDING LWS_PRE
+#define LWS_SEND_BUFFER_POST_PADDING 0
+
+#define LWS_WRITE_RAW LWS_WRITE_HTTP
+
+/*
+ * NOTE: These public enums are part of the abi.  If you want to add one,
+ * add it at where specified so existing users are unaffected.
+ */
+enum lws_write_protocol {
+	LWS_WRITE_TEXT						= 0,
+	/**< Send a ws TEXT message,the pointer must have LWS_PRE valid
+	 * memory behind it.
+	 *
+	 * The receiver expects only valid utf-8 in the payload */
+	LWS_WRITE_BINARY					= 1,
+	/**< Send a ws BINARY message, the pointer must have LWS_PRE valid
+	 * memory behind it.
+	 *
+	 * Any sequence of bytes is valid */
+	LWS_WRITE_CONTINUATION					= 2,
+	/**< Continue a previous ws message, the pointer must have LWS_PRE valid
+	 * memory behind it */
+	LWS_WRITE_HTTP						= 3,
+	/**< Send HTTP content */
+
+	/* LWS_WRITE_CLOSE is handled by lws_close_reason() */
+	LWS_WRITE_PING						= 5,
+	LWS_WRITE_PONG						= 6,
+
+	/* Same as write_http but we know this write ends the transaction */
+	LWS_WRITE_HTTP_FINAL					= 7,
+
+	/* HTTP2 */
+
+	LWS_WRITE_HTTP_HEADERS					= 8,
+	/**< Send http headers (http2 encodes this payload and LWS_WRITE_HTTP
+	 * payload differently, http 1.x links also handle this correctly. so
+	 * to be compatible with both in the future,header response part should
+	 * be sent using this regardless of http version expected)
+	 */
+	LWS_WRITE_HTTP_HEADERS_CONTINUATION			= 9,
+	/**< Continuation of http/2 headers
+	 */
+
+	/****** add new things just above ---^ ******/
+
+	/* flags */
+
+	LWS_WRITE_BUFLIST = 0x20,
+	/**< Don't actually write it... stick it on the output buflist and
+	 *   write it as soon as possible.  Useful if you learn you have to
+	 *   write something, have the data to write to hand but the timing is
+	 *   unrelated as to whether the connection is writable or not, and were
+	 *   otherwise going to have to allocate a temp buffer and write it
+	 *   later anyway */
+
+	LWS_WRITE_NO_FIN = 0x40,
+	/**< This part of the message is not the end of the message */
+
+	LWS_WRITE_H2_STREAM_END = 0x80,
+	/**< Flag indicates this packet should go out with STREAM_END if h2
+	 * STREAM_END is allowed on DATA or HEADERS.
+	 */
+
+	LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
+	/**< client packet payload goes out on wire unmunged
+	 * only useful for security tests since normal servers cannot
+	 * decode the content if used */
+};
+
+/* used with LWS_CALLBACK_CHILD_WRITE_VIA_PARENT */
+
+struct lws_write_passthru {
+	struct lws *wsi;
+	unsigned char *buf;
+	size_t len;
+	enum lws_write_protocol wp;
+};
+
+
+/**
+ * lws_write() - Apply protocol then write data to client
+ *
+ * \param wsi:	Websocket instance (available from user callback)
+ * \param buf:	The data to send.  For data being sent on a websocket
+ *		connection (ie, not default http), this buffer MUST have
+ *		LWS_PRE bytes valid BEFORE the pointer.
+ *		This is so the protocol header data can be added in-situ.
+ * \param len:	Count of the data bytes in the payload starting from buf
+ * \param protocol:	Use LWS_WRITE_HTTP to reply to an http connection, and one
+ *		of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate
+ *		data on a websockets connection.  Remember to allow the extra
+ *		bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT
+ *		are used.
+ *
+ * This function provides the way to issue data back to the client, for any
+ * role (h1, h2, ws, raw, etc).  It can only be called from the WRITEABLE
+ * callback.
+ *
+ * IMPORTANT NOTICE!
+ *
+ * When sending with ws protocol
+ *
+ * LWS_WRITE_TEXT,
+ * LWS_WRITE_BINARY,
+ * LWS_WRITE_CONTINUATION,
+ * LWS_WRITE_PING,
+ * LWS_WRITE_PONG,
+ *
+ * or sending on http/2... the send buffer has to have LWS_PRE bytes valid
+ * BEFORE the buffer pointer you pass to lws_write().  Since you'll probably
+ * want to use http/2 before too long, it's wise to just always do this with
+ * lws_write buffers... LWS_PRE is typically 16 bytes it's not going to hurt
+ * usually.
+ *
+ * start of alloc       ptr passed to lws_write      end of allocation
+ *       |                         |                         |
+ *       v  <-- LWS_PRE bytes -->  v                         v
+ *       [----------------  allocated memory  ---------------]
+ *              (for lws use)      [====== user buffer ======]
+ *
+ * This allows us to add protocol info before the data, and send as one packet
+ * on the network without payload copying, for maximum efficiency.
+ *
+ * So for example you need this kind of code to use lws_write with a
+ * 128-byte payload
+ *
+ *   char buf[LWS_PRE + 128];
+ *
+ *   // fill your part of the buffer... for example here it's all zeros
+ *   memset(&buf[LWS_PRE], 0, 128);
+ *
+ *   if (lws_write(wsi, &buf[LWS_PRE], 128, LWS_WRITE_TEXT) < 128) {
+ *   		... the connection is dead ...
+ *   		return -1;
+ *   }
+ *
+ * LWS_PRE is currently 16, which covers ws and h2 frame headers, and is
+ * compatible with 32 and 64-bit alignment requirements.
+ *
+ * (LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off.)
+ *
+ * Return may be -1 is the write failed in a way indicating that the connection
+ * has ended already, in which case you can close your side, or a positive
+ * number that is at least the number of bytes requested to send (under some
+ * encapsulation scenarios, it can indicate more than you asked was sent).
+ *
+ * The recommended test of the return is less than what you asked indicates
+ * the connection has failed.
+ *
+ * Truncated Writes
+ * ================
+ *
+ * The OS may not accept everything you asked to write on the connection.
+ *
+ * Posix defines POLLOUT indication from poll() to show that the connection
+ * will accept more write data, but it doesn't specifiy how much.  It may just
+ * accept one byte of whatever you wanted to send.
+ *
+ * LWS will buffer the remainder automatically, and send it out autonomously.
+ *
+ * During that time, WRITABLE callbacks to user code will be suppressed and
+ * instead used internally.  After it completes, it will send an extra WRITEABLE
+ * callback to the user code, in case any request was missed.  So it is possible
+ * to receive unasked-for WRITEABLE callbacks, the user code should have enough
+ * state to know if it wants to write anything and just return if not.
+ *
+ * This is to handle corner cases where unexpectedly the OS refuses what we
+ * usually expect it to accept.  It's not recommended as the way to randomly
+ * send huge payloads, since it is being copied on to heap and is inefficient.
+ *
+ * Huge payloads should instead be sent in fragments that are around 2 x mtu,
+ * which is almost always directly accepted by the OS.  To simplify this for
+ * ws fragments, there is a helper lws_write_ws_flags() below that simplifies
+ * selecting the correct flags to give lws_write() for each fragment.
+ *
+ * In the case of RFC8441 ws-over-h2, you cannot send ws fragments larger than
+ * the max h2 frame size, typically 16KB, but should further restrict it to
+ * the same ~2 x mtu limit mentioned above.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_write(struct lws *wsi, unsigned char *buf, size_t len,
+	  enum lws_write_protocol protocol);
+
+/* helper for case where buffer may be const */
+#define lws_write_http(wsi, buf, len) \
+	lws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
+
+/**
+ * lws_write_ws_flags() - Helper for multi-frame ws message flags
+ *
+ * \param initial: the lws_write flag to use for the start fragment, eg,
+ *		   LWS_WRITE_TEXT
+ * \param is_start: nonzero if this is the first fragment of the message
+ * \param is_end: nonzero if this is the last fragment of the message
+ *
+ * Returns the correct LWS_WRITE_ flag to use for each fragment of a message
+ * in turn.
+ */
+static LWS_INLINE int
+lws_write_ws_flags(int initial, int is_start, int is_end)
+{
+	int r;
+
+	if (is_start)
+		r = initial;
+	else
+		r = LWS_WRITE_CONTINUATION;
+
+	if (!is_end)
+		r |= LWS_WRITE_NO_FIN;
+
+	return r;
+}
+
+/**
+ * lws_raw_transaction_completed() - Helper for flushing before close
+ *
+ * \param wsi: the struct lws to operate on
+ *
+ * Returns -1 if the wsi can close now.  However if there is buffered, unsent
+ * data, the wsi is marked as to be closed when the output buffer data is
+ * drained, and it returns 0.
+ *
+ * For raw cases where the transaction completed without failure,
+ * `return lws_raw_transaction_completed(wsi)` should better be used than
+ * return -1.
+ */
+LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
+lws_raw_transaction_completed(struct lws *wsi);
+
+///@}