Control Layer
- Former user (Deleted)
Introduction
The control layer is a module bound to µC/HTTP-server used to manage multiple groups of authentication process and application process. There are many cases where one would like to have multiple functions bound to the same hook but with different goals. This is a the role of the Control layer.
The control layer maps each hook function available in µC/HTTP-server on its own hook. The configuration of those hooks has two layers : The Authentications and the Applications.
It provides an abstraction over the HTTPs_CONN's and HTTPs_INSTANCE's contextual data holders: p_instance->DataPtr and p_conn->ConnDataPtr. The Control Layer will automatically substitute them. Those contextual information are saved after each hook call and restored before each hook call. Which means that each Control Layer instance has its own connection and instance data pointers. The following diagram shows these context switches through color variance:
Authentications
The Authentications layer is the part of the configuration where one can specify how to hide an application e.g. Put your application behind a Login form. Each Control Layer configuration can have a list of authentications which must succeed in order to access any application of the same configuration.
Therefore, for a given Control Layer configuration, many Authentication modules can be defined. Each module must declared its own HTTPs_CTRL_LAYER_AUTH_INST object that regroups a pointer to its own hook configuration (HTTPs_CTRL_LAYER_AUTH_HOOKS object) and a pointer to other configurations required by the module if necessary (See section HooksCfgPtr Parameter).
Applications
The Application layer is the part where HTTP requests can be analyze and HTTP responses will be built. At this point, the authentications required have passed already. The application layer handles both body parsing and body formatting. The application has full control over the µC/HTTP-server response and is called every time the server needs to poll the hook to complete its task.
typedef struct https_ctrl_layer_app_hooks {
HTTPs_INSTANCE_INIT_HOOK OnInstanceInit;
HTTPs_REQ_HDR_RX_HOOK OnReqHdrRx;
HTTPs_REQ_HOOK OnReq;
HTTPs_REQ_BODY_RX_HOOK OnReqBodyRx;
HTTPs_REQ_RDY_SIGNAL_HOOK OnReqSignal;
HTTPs_REQ_RDY_POLL_HOOK OnReqPoll;
HTTPs_RESP_HDR_TX_HOOK OnRespHdrTx;
HTTPs_RESP_TOKEN_HOOK OnRespToken;
HTTPs_RESP_CHUNK_HOOK OnRespChunk;
HTTPs_TRANS_COMPLETE_HOOK OnTransComplete;
HTTPs_ERR_HOOK OnError;
HTTPs_CONN_CLOSE_HOOK OnConnClose;
} HTTPs_CTRL_LAYER_APP_HOOKS;
typedef struct https_ctrl_layer_app_inst {
HTTPs_CTRL_LAYER_APP_HOOKS *HooksPtr;
void *HooksCfgPtr;
} HTTPs_CTRL_LAYER_APP_INST;
As for the Authentication Layer, a given Control Layer configuration can have many Application modules. each module must declared its own HTTPs_CTRL_LAYER_APP_INST object that regroups a pointer to its own hook configuration (HTTPs_CTRL_LAYER_APP_HOOKS object) and a pointer to other configurations required by the module if necessary (See section HooksCfgPtr Parameter).
Configuration
Demystify the HooksCfgPtr Parameter
The HooksCfgPtr parameter will be passed as argument with each hook function from HooksPtr. Therefore, HooksCfgPtr parameter is offered to passed information necessary to specify the comportment of a given authentication instance or application instance. This information highly depends on the instance nature. If not necessary, the HooksCfgPtr parameter can be set to DEF_NULL.
HTTPs_CTRL_LAYER_CFG and HTTPs_CTRL_LAYER_CFG_LIST
The control layer takes an HTTPs_CTRL_LAYER_CFG_LIST structure pointer as configuration. Below is the definition of the structures for the configuration of the Control Layer:
/* Controlled service layer. */
typedef struct https_ctrl_layer_cfg {
HTTPs_CTRL_LAYER_AUTH_INST **AuthInstsPtr;
CPU_SIZE_T AuthInstsNbr;
HTTPs_CTRL_LAYER_APP_INST **AppInstsPtr;
CPU_SIZE_T AppInstsNbr;
} HTTPs_CTRL_LAYER_CFG;
/* List of controlled services. */
typedef struct https_ctrl_layer_cfg_List {
HTTPs_CTRL_LAYER_CFG **CfgsPtr;
CPU_SIZE_T Size;
} HTTPs_CTRL_LAYER_CFG_LIST;
Here's an example how to declare a Control Layer configuration:
/* Define some authentication hook set. */
HTTPs_CTRL_LAYER_AUTH_HOOKS AuthHooks = { ... };
/* Create an auth instance based on the hook set and a user config pointer */
HTTPs_CTRL_LAYER_AUTH_INST AuthInst = { &AuthHooks, ... };
/* Define some application hook set */
HTTPs_CTRL_LAYER_APP_HOOKS SomeAppHooks = { ... };
/*Create an app instance based on the hook set and a user config pointer */
HTTPs_CTRL_LAYER_APP_INST SomeAppInst = { &SomeAppHooks, ... };
/* List both authentications and applications */
HTTPs_CTRL_LAYER_AUTH_INST *AuthInsts[] = { &AuthInst };
HTTPs_CTRL_LAYER_APP_INST *AppInsts[] = { &SomeAppInst };
/* Create a config for the control layer */
HTTPs_CTRL_LAYER_CFG SomeCfg = {
authInsts,
sizeof(authInsts) / sizeof(HTTPs_CTRL_LAYER_AUTH_INST *),
appInsts,
sizeof(appInsts) / sizeof(HTTPs_CTRL_LAYER_APP_INST *),
};
/* List the configurations. */
HTTPs_CTRL_LAYER_CFG *CtrlLayerCfgs[] = { &SomeCfg };
/* Build the cfg structure for the control layer */
HTTPs_CTRL_LAYER_CFG_LIST CtrlLayerCfgList= {
CtrlLayerCfgs,
sizeof(CtrlLayerCfgs) / sizeof(HTTPs_CTRL_LAYER_CFG *)
};
µC/HTTP-server Hook Binding
Here's an example of how to bind it to an HTTPs_CFG:
const HTTPs_CFG foo = {
...,
/*
*--------------------------------------------------------------------------------------------------------
* HOOKS CONFIGURATION
*--------------------------------------------------------------------------------------------------------
*/
/* Declared in uC-HTTP/Server/Add-on/CtrlLayer/http-s_ctrl_layer.h */
&HTTPsCtrlLayer_HookCfg, /* .HooksPtr */
/* Previously declared in the configuration section */
&CtrlLayerCfgList, /* .Hooks_CfgPtr */
...
};