@ -1369,7 +1369,7 @@ AutoConnectElements contained in AutoConnectAux object are uniquely identified b
<p>To retrieve the values entered in a custom Web page you need to access the AutoConnectElement of the page that caused the request to this page and to do this, you use the <ahref="api.html#where">AutoConnect::where</a> function. The <code>AutoConnect::where</code> function returns a pointer to the AutoConnectAux object of the custom Web page that caused the HTTP request.</p>
<divclass="admonition note">
<pclass="admonition-title">The where() function is available for only AutoConnectAux.</p>
<p>The <code>AutoConnect::where</code> function is available only for the AutoConnectAux object. It is invalid for HTTP requests from individual pages registered with the <strong>on</strong> handler of ESP8266WebServer/ESP32. In other words, the <code>AutoConnect::where</code> function only returns the last AutoConnecAux page called.</p>
<p>The <code>AutoConnect::where</code> function is available only for the AutoConnectAux object. It is invalid for HTTP requests from individual pages registered with the <strong>on</strong> handler of ESP8266WebServer/WebServer for ESP32. In other words, the <code>AutoConnect::where</code> function only returns the last AutoConnecAux page called.</p>
</div>
<h3id="when-setting-the-initial-values"><iclass="fa fa-desktop"></i> When setting the initial values<aclass="headerlink"href="#when-setting-the-initial-values"title="Permanent link">¶</a></h3>
<p>An AutoConnectAux page is dynamically created by AutoConnect when its uri is requested. The initial value of AutoConnectElements can be set before its page request. It is also possible during <code>loop()</code>. To set the initial value when the page is accessed it needs by the handler of its page.</p>
@ -1581,8 +1581,8 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
<h3id="the-uri-of-the-custom-web-pages">The URI of the custom Web pages<aclass="headerlink"href="#the-uri-of-the-custom-web-pages"title="Permanent link">¶</a></h3>
<p>The transition of the custom Web page follows the URI of the page, but the ESP8266WebServer class does not know the URI of an AutoConnectAux page. (Registering a custom Web page does not use the <em>ESP8266WebServer::on</em>/<em>WebServer::on</em> function.) Therefore ESP8266WebServer class does not detect its URI access. If you want to detect an http request to AutoConnectAux's custom Web page, you need to register its URI with the <ahref="apiaux.html#on">AutoConnectAux::on</a> function.</p>
<p>In addition to this, there are restrictions in the handler for the custom Web page as shown in the following section.</p>
<p>The custom Web pages handler has the following limitations.</p>
<ul>
<li>
<p>Do not send HTTP responses from the handler.</p>
@ -1597,13 +1597,13 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
<p>During the connection attempt, the web browser of the client will send a probe for a captive portal. Its request will cause unintended custom Web page transitions.</p>
</li>
<li>
<p>Can not place URI of the custom Web pages to AUTOCONNECT_URI].</p>
<p>Can not place URI of the custom Web pages to AUTOCONNECT_URI.</p>
<p>AutoConnect will not work if you place a custom Web page to <ahref="api.html#defined-macros">AUTOCONNECT_URI</a>.</p>
<p>To transition from a custom Web page to a sketch owned page, execute the link function of JavaScript with the AutoConnectElement element.</p>
<divclass="admonition caution">
<pclass="admonition-title">Do not handle for the same page</p>
<p>Do not duplicate AutoConnect::on with ESP8266WebServer::on (also WebServer::on) for the same custom web page.</p>
</div>
<script>
window.onload = function() {
@ -1618,7 +1618,7 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
<p>The valid scope of the name is within an AutoConnectAux. <aclass="footnote-backref"href="#fnref:1"rev="footnote"title="Jump back to footnote 1 in the text">↩</a></p>
</li>
<liid="fn:2">
<p>The pattern of AutoConnectInput conforms to javascript specification. <aclass="footnote-backref"href="#fnref:2"rev="footnote"title="Jump back to footnote 2 in the text">↩</a></p>
<p>Regular expression specification as a pattern of AutoConnectInput is <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions">JavaScript compliant</a>. <aclass="footnote-backref"href="#fnref:2"rev="footnote"title="Jump back to footnote 2 in the text">↩</a></p>
AutoConnectAux is a container for AutoConnectElements. To make a custom Web page, create elements that make up the page and put it in the AutoConnectAux object. Joining its AutoConnectAux object to AutoConnect will integrate the custom Web page into the AutoConnect menu.</p>
<p><imgsrc="images/ac_declaration.svg"></p>
<p>The above figure shows a code sequence that declares AutoConnectElements and put in the AutoConnectAux container and integrates those into AutoConnect. It declares two text elements named <em>header</em> and <em>caption</em>, adds them to the AutoConnectAux object as <em>aux</em>, binds to an AutoConnect object named <em>portal</em>. This sequence is the basic procedure for creating custom Web pages with the sketch. Also, further explanation of AutoConnectElements is the<ahref="acelements.html">documentation</a>.</p>
<p>The above figure shows a code sequence that declares AutoConnectElements and put in the AutoConnectAux container and integrates those into AutoConnect. It declares two text elements named <em>header</em> and <em>caption</em>, adds them to the AutoConnectAux object as <em>aux</em>, binds to an AutoConnect object named <em>portal</em>. This sequence is the basic procedure for creating custom Web pages with the sketch. The further explanation is available in section<ahref="acelements.html">AutoConnectElements</a> also.</p>
<h2id="custom-web-pages-in-autoconnect-menu">Custom Web pages in AutoConnect menu<aclass="headerlink"href="#custom-web-pages-in-autoconnect-menu"title="Permanent link">¶</a></h2>
<ulclass="horizontal-list">
<li><imgstyle="margin:0 20px 0 -20px;float:left;width:300px;"src="images/ac_auxmenu.png">
Returns a pointer to the AutoConnectAux object of the custom Web page that caused the request to that page. This function is available only for the AutoConnectAux object. It is invalid for HTTP requests from individual pages registered with the <strong>on</strong> handler of ESP8266WebServer/ESP32. In other words, this function only returns the last AutoConnecAux page called.
Returns a pointer to the AutoConnectAux object of the custom Web page that caused the request to the page.<br>
AutoConnect identifies the URI (ie. the referrer URI) that caused the request each time from the client occurs and will save the URI If the request source is a custom Web page of AutoConnectAux. The <strong>where</strong> function returns a pointer of AutoConnectAux which is a URI of a least recent request from the custom Web page.<br>
This function is provided to access the fields (ie. the AutoConnectElements) with a custom Web page handler of a page and is available only for request source that is the custom Web pages. It is invalid for HTTP requests from individual pages registered with the <strong>on</strong> handler of ESP8266WebServer/WebServer for ESP32. In other words, this function only returns the AutoConnecAux page which is a least recently displayed.
<dlclass="apidl">
<dt><strong>Retuen value</strong></dt>
<dt><strong>Return value</strong></dt>
<dd>A pointer to the AutoConnectAux that caused the request the page.</dd>
</dl></p>
<p>The <strong>where</strong> function usage is described in the section <ahref="achandling.html#where-to-pick-up-the-values"><em>Where to pick up the values</em></a>.</p>
<li>Supports <ahref="apiconfig.html#hostname"><strong>AutoConnectConfig::hostName</strong></a>. It activates <code>WiFi.hostname()</code>/<code>WiFi.setHostName()</code>.</li>
<li>Supports the captive portal time-out. It can be controlled by <ahref="apiconfig.html#portaltimeout"><strong>AutoConnectConfig::portalTimeout</strong></a> and <ahref="apiconfig.html#retainportal"><strong>AutoConnectConfig::retainPortal</strong></a>.</li>
<h3id="ip-adderss"><iclass="fa fa-exchange"></i> IP adderss<aclass="headerlink"href="#ip-adderss"title="Permanent link">¶</a></h3>
<h3id="ip-address"><iclass="fa fa-exchange"></i> IP address<aclass="headerlink"href="#ip-address"title="Permanent link">¶</a></h3>
<p>To convert a String to an IP address, use <strong>IPAddress::fromString</strong>. To stringize an instance of an IP address, use <strong>IPAddress::toString</strong>.</p>
<p>The ssanf library function cannot be used with the old Arduino core. <aclass="footnote-backref"href="#fnref:1"rev="footnote"title="Jump back to footnote 1 in the text">↩</a></p>
</li>
<liid="fn:2">
<p>This regular expressiondoes not fully support the format of the e-mail address requested in <ahref="https://tools.ietf.org/html/rfc5322">RFC5322</a>. <aclass="footnote-backref"href="#fnref:2"rev="footnote"title="Jump back to footnote 2 in the text">↩</a></p>
<p>This regular expressiondoes not fully support the format of the e-mail address requested in <ahref="https://tools.ietf.org/html/rfc5322">RFC5322</a>. <aclass="footnote-backref"href="#fnref:2"rev="footnote"title="Jump back to footnote 2 in the text">↩</a></p>
</li>
<liid="fn:3">
<p>This regular expression does not consider semantic constraints. It is not possible to detect errors that do not exist as actual dates. <aclass="footnote-backref"href="#fnref:3"rev="footnote"title="Jump back to footnote 3 in the text">↩</a></p>
<p>Several parameters of <ahref="apiconfig.html">AutoConnectConfig</a> affect the behavior of <ahref="api.html#begin">AutoConnect::begin</a> function. Each parameter affects the behaves in complicated order and apply the followings with the priority in the logic sequence of AutoConnect::begin.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1"rel="footnote">1</a></sup></p>
<p>Several parameters as follows of <ahref="apiconfig.html">AutoConnectConfig</a> affect the behavior of <ahref="api.html#begin">AutoConnect::begin</a> function. Each parameter affects the behaves in interacted order with the priority and apply to the logic sequence of AutoConnect::begin.</p>
<ul>
<li><ahref="apiconfig.html#immediatestart">immediateStart</a> : The captive portal start immediately, without first WiFi.begin.</li>
<li><ahref="apiconfig.html#autoreconnect">autoReconenct</a> : Attempt re-connect with past SSID by saved credential.</li>
@ -767,16 +767,12 @@
</ul>
<p>You can use these parameters in combination with sketch requirements and need to understand correctly the behavior caused by the parameters. The following chart shows the AutoConnect::begin logic sequence including the effect of these parameters.</p>
<p>For example, AutoConnect::begin will not exits without the portalTimeout while the connection not establishes, but WebServer will start to work. So, your sketch may work seemingly, but it will close with inside a loop of the AutoConnect::begin function. Especially when invoking AutoConnect::begin in the <strong>setup()</strong>, execution control does not pass to the <strong>loop()</strong>.</p>
<p>As different scenes, you may use the immediateStart effectively. Equipped the external switch to activate the captive portal with the ESP module, combined with the portalTime and the retainPortal it will become WiFi active connection feature. You can start AutoConnect::begin at any point in the <strong>loop()</strong>, which allows your sketch can behave both the offline mode and the online mode.</p>
<p>For example, AutoConnect::begin will not exits without the <strong>portalTimeout</strong> while the connection not establishes, but WebServer will start to work. So, your sketch may work seemingly, but it will close with inside a loop of the AutoConnect::begin function. Especially when invoking AutoConnect::begin in the <strong>setup()</strong>, execution control does not pass to the <strong>loop()</strong>.</p>
<p>As different scenes, you may use the <strong>immediateStart</strong> effectively. Equipped the external switch to activate the captive portal with the ESP module, combined with the <strong>portalTime</strong> and the <strong>retainPortal</strong> it will become WiFi active connection feature. You can start AutoConnect::begin at any point in the <strong>loop()</strong>, which allows your sketch can behave both the offline mode and the online mode.</p>
<p>Please consider these kinds of influence when you make sketches.</p>
<divclass="footnote">
<hr/>
<ol>
<liid="fn:1">
<p>Another parameter as the <ahref="api.html#begin">3<sup>rd</sup> parameter</a> of AutoConnect::begin related to timeout constrains the connection wait time after WiFi.begin. It is the <strong>CONNECTED</strong> judgment of the above chart that it has an effect. <aclass="footnote-backref"href="#fnref:1"rev="footnote"title="Jump back to footnote 1 in the text">↩</a></p>
<p>Another parameter as the <ahref="api.html#begin">3<sup>rd</sup> parameter</a> of AutoConnect::begin related to timeout constrains the connection wait time after WiFi.begin. It is the <strong>CONNECTED</strong> judgment of the above chart that it has an effect.</p>
Hieromon Ikasamo
5 years ago
