Get Token Value

This hook function, if defined, is called by μC/HTTP-server when a token is found into a plain document such as HTML during the response construct process as shown in the figure Hook Functions. It allows the upper application to populate some part of a document dynamically.

Prototype

CPU_BOOLEAN  HTTPs_RespTokenValGetHook(const  HTTPs_INSTANCE  *p_instance,
                                              HTTPs_CONN      *p_conn,
									   const  void            *p_hook_cfg,
									   const  CPU_CHAR        *p_token,
                                              CPU_INT16U       token_len,
                                              CPU_CHAR        *p_val,
                                              CPU_INT16U       val_len_max);

Arguments

p_instance

Pointer to the instance structure (read only).

p_conn

Pointer to the connection structure.

p_hook_cfg

Pointer to hook application data.

p_token

Pointer to the string that contains the token name.

token_len

Length of the token.

p_val

Pointer to string where to copy the token substitution value.

val_len_max

Maximum string value length.

Return Values

DEF_OK

If token value copied successfully.

DEF_FAIL

Otherwise (see Notes).

Required Configuration

See Token Replacement Compile-time Configuration and Token Replacement Run-time Configuration.

Notes / Warnings

  • The instance structure is for read-only. It must not be modified.
  • Connection structure must not be modified by this function since the response transmission is started.
  • If the token replacement failed, the token will be replaced by a line of tilde (~) of length equal to val_len_max.

Example Template

The listing below demonstrates the µC/HTTP-server module capabilities. It checks if the token is equal to "TEXT_STRING" and replaces it with "Text"; otherwise it returns an error and lets the server replace the token by the default value.

Listing - CGI Poll Hook Function Example Code
static  CPU_BOOLEAN  HTTPs_RespTokenValGetHook (const  HTTPs_INSTANCE  *p_instance,
                                                       HTTPs_CONN      *p_conn,
												const  void            *p_hook_cfg,
												const  CPU_CHAR        *p_token,
                                                       CPU_INT16U       token_len,
                                                       CPU_CHAR        *p_val,
                                                       CPU_INT16U       val_len_max)
{
	if (Str_Cmp_N(p_token, "TEXT_STRING", 11) == 0) {
        Str_Copy_N(p_val, "Text", val_len_max);
        return (DEF_OK);
	}
          
	return (DEF_FAIL);
}