Update Logging.md

docs/Logging.md

@@ -104,9 +104,41 @@ To embed this custom HTML text in the Web Log, call `homeSpan.setWebLogCallback(
 
 ### Accessing Web Log HTML from within your sketch
 
-In addition to (or as an alternative to) serving an HTML Web Log page in response to HTTP requests, users can access the HTML for such page from within their sketch.  Since the HTML for a Web Log page can be very large, in order to avoid consuming too much RAM, HomeSpan generates the HTML on demand and streams the page in sequential chunks of 1024 bytes in response to an HTTP request for the Web Log.  It is therefore not possible for HomeSpan to simply provide the user with a `char *` pointing the HTML for a complete Web Log.  Instead, HomeSpan provides the user method with the following method that triggers the production of the HTML for a Web Log page and streams the resulting 1024-byte chubnks of HTML to a user-defined function for further processing and handling:
+In addition to (or as an alternative to) having HomeSpan serve HTML Web Log pages in response to HTTP requests, users can directly access the HTML text for a Web Log page from within their sketch for customized processing and handling.  Since the HTML for a Web Log page can be very large, HomeSpan only generates the HTML for a Web Log page when the page has been requested, and streams the HTML in sequential chunks of 1024 bytes in response to a Web Log HTTP request.  It is therefore not possible for HomeSpan to simply provide the user with a `char *` pointer to the HTML text for a complete Web Log.  Instead, HomeSpan provides the user with the following *homeSpan* method to trigger the production of a Web Log page and access the resulting HTML text whenever needed:
+
+`getWebLog(void (*f)(const char *htmlText, void *data), void *userData)`
+
+ * *f()* - a user-defined function that returns `void` and takes two arguments:
+   * *htmlText* - a null-terminated `const char *` pointer to a chunk of HTML text (max 1024 bytes) provided by HomeSpan
+   * *data* - a `void *` pointer to any user-provided data, *userData*
+ * *userData* - a `void *` pointer to any optional user-provided data that is passed to *f()* as its second argument, *data*
+
+When the above method is called from a sketch, HomeSpan will repeatedly call the user-defined function *f()* and provide sequential chunks of HTML text for the Web Log page as the first argument, *htmlText*.  Once all HTML chunks have been sent to the function *f()*, HomeSpan calls *f()* one final time with *htmlText* set to NULL to indicate there are no more HTML chunks to be sent.
+
+The primary purpose of this function is for the user to provide their own method of serving an HTML Web Log page, such as through a secure HTTPS channel.  Note this channel can be in addition to, or instead of, HomeSpan's normal serving of Web Log pages through HTTP requests depending on whether or not the URL argument used in the `homeSpan.enableWebLog()` method was set to NULL (disabling HomeSpan from serving Web Log pages in response to HTTP requests).
+
+The following psuedo-code snippet shows how `getWebLog()` can be used:
+
+```C++
+...
+homeSpan.enableWebLog(50,"pool.ntp.org","UTC",NULL);      // this enables the Web Log for 50 entries and sets the clock, but prevents HomeSpan from responding to any HTTP requests for a Web Log page
+...
+IF WEBLOG NEEDED THEN{
+  homeSpan.getWebLog(myWebLogHandler,NULL);               // this triggers HomeSpan to produce the HTML text for a Web Log page and stream the data to myWebLogHandler without any extra user data
+}
+...
+void myWebLogHandler(const char *htmlText, void *args){   // this is the user-defined Web Log handler (note the optional *arg parameter is not used in this example)
+  if(htmlText!=NULL){
+    DO SOMETHING WITH htmlText (e.g. transmit it to the user via an HTTPS connection)
+  }
+  else
+    PERFORM ANY CLEAN-UP PROCESSING (e.g. close the HTTPS connection)
+  }
+}
+```
+
+
  
- TBD
 ---
 
 [↩️](../README.md) Back to the Welcome page