Skip to content

Latest commit

 

History

History
168 lines (117 loc) · 7.88 KB

README.md

File metadata and controls

168 lines (117 loc) · 7.88 KB
Raw

LCBUrl - An Arduino library for handling URLs

Arduino Library GitHub Release MIT License GitHub Issues GitHub Pull Requests Contributors Welcome

This library was written by and for a non-professional programmer. If you find some use out of it, that will make me happy, but if not, I'm still using it in my projects.

This library will parse a URL, and normalize it according to the information provided in RFC3986. Take for example this terrifying URL:

http://%7EFoo:%7Ep@$$word@servername.local:80/%7Ethis/is/a/./path/test.php?foo=bar#frag

LCBUrl will allow you to parse and access the hostname, user name, password, path, query string, fragment, etc.:

  • getUrl() returns: http://~Foo:~p@$$word@servername.local/~this/is/a/./path/test.php?foo=bar#frag
  • getIPUrl() returns: http://~Foo:~p@$$word@XXX.XXX.XXX.XXX/~this/is/a/./path/test.php?foo=bar#frag
  • getScheme() returns: http
  • getUserInfo() returns: ~Foo:~p@$$word
  • getUserName() returns: ~Foo
  • getPassword() returns: ~p@$$word
  • getHost() returns: servername.local
  • getIP() returns: XXX.XXX.XXX.XXX
  • getPort() returns: 80
  • getAuthority() returns: ~Foo:~p@$$word@servername.local
  • getIPAuthority() returns: ~Foo:~p@$$word@XXX.XXX.XXX.XXX
  • getPath() returns: ~this/is/a/./path/test.php
  • getAfterPath() returns: ?foo=bar#frag
  • getQuery() returns: foo=bar
  • getFragment() returns: frag

If you are using mDNS in your projects, you may have discovered many microcontroller libraries do not support mDNS in all areas. This library will additionally (but conditionally) re-parse a URL and replace the *.local hostname with the resolved IP address.

❗ IMPORTANT: Using any of the network-based methods in a timer (i.e. Ticker) will crash or hang your program. This hang is not a shortcoming of this library; it is how radio-functions (networking being one) work.

Public Methods

Core Methods

  • bool setUrl(String) - Pass the URL to be handled to the class
  • String getUrl() - Return a processed/normalized URI in the following format: scheme:[//authority]path[?query][#fragment]
  • String getIPUrl() - Return a processed URI with the host replaced by the IP address in the following format: scheme:[//authority]path[?query][#fragment] (useful for mDNS URLs)
  • String getScheme() - Get the scheme (currently only handles http and https)
  • String getUserInfo() - Return username and password (if present)
  • String getUserName() - Returns username (if present)
  • String getPassword() - Returns password (if present)
  • String getHost() - Return host name
  • word getPort() - Return port (if present) if non-standard
  • String getAuthority() - Return the authority (if present) in the following format: [userinfo@]host[:port]
  • String getIPAuthority() - Return the authority (if present) in the following format: [userinfo@]XXX.XXX.XXX.XXX[:port] (useful for mDNS URLs, will use cached IPs if they exist)
  • String getPath() - Returns the path segment (if present) with any query or fragment removed
  • String getAfterPath() - Returns query and fragment segments (if present)
  • String getQuery() - Returns query (if present)
  • String getFragment() - Returns fragment (if present)

Original Utility Methods

❗ These methods are deprecated and slated to be removed.

These utility methods are dependant upon the class' instantiation and current URL string.

  • bool isMDNS() - Return true or false determination of whether the class' host is a valid mDNS name
  • IPAddress getIP() - Return IP address of class' host (always does lookup)

Utility Methods

These methods are intended to extend functionality of the TCP libraries, and may be leveraged independent of a specific instance declaration.

  • bool isMDNS(const char *hostName) - Returns true if hostName is a valid mDNS name
  • IPAddress getIP(const char * hostName) - Return IP address of hostName (always does lookup)
  • bool isValidIP(const char * hostName) - Returns true if hostName represents a valid IP address string
  • int labelCount(const char * hostName) - Integer of the number of labels in the hostName
  • bool isANumber(const char * str) - Returns true if str is a valid number
  • bool isValidLabel(const char *label) - Returns true if the label is a valid DNS label
  • bool isValidHostName(const char *hostName) - Return true if the hostName passed is a valid DNS, mDNS or IP hostname

Progress:

  • Convert percent-encoded triplets to uppercase
  • Convert the scheme and host to lowercase
  • Decode percent-encoded triplets of unreserved characters
  • Remove dot-segments
  • Convert an empty path to a "/" path
  • Remove the default port
  • Add a trailing "/" to a non-empty path (may remove this) (removed this after some thought)
  • Add validity check functions (not yet part of the initialization)

Installation

Installation is particular to the platform with which you are developing:

PlatformIO

This library is available as lbussy/LCBUrl in PlatformIO's library manager.

Arduino IDE

LCBUrl is published via the Arduino Library Manager. You can include this library in your project by navigating to Sketch -> Include Libraries -> Manage Libraries (or Ctrl - Shift - I). Type LCBUrl in the search bar:

Manual

To install this library, place this entire folder as a subfolder in your ./lib/targets/libraries folder.

When installed, this library should contain the following files:

./lib/targets/libraries/LCBUrl                    (this library's folder)
./lib/targets/libraries/LCBUrl/examples           (the examples in the "open" menu)
./lib/targets/libraries/LCBUrl/keywords.txt       (the syntax coloring file)
./lib/targets/libraries/LCBUrl/library.properties (properties of this library)
./lib/targets/libraries/LCBUrl/LICENSE            (the license for this library)
./lib/targets/libraries/LCBUrl/README.md          (this file)
./lib/targets/libraries/LCBUrl/src/LCBUrl.cpp     (the library implementation file)
./lib/targets/libraries/LCBUrl/src/LCBUrl.h       (the library description file)

Building

Ensure that you add a corresponding line to the top of your sketch:

#include <LCBUrl.h>

To stop using this library, delete that line from your sketch.

mDNS Support {#mdns-support}

To enable mDNS support, define the macro before including the library:

#define LCBURL_MDNS
#include <LCBUrl.h>

Or, define it globally in the platformio.ini or compiler definitions:

-DLCBURL_MDNS

Without this definition, the mDNS functions will return failures.

mDNS on ESP8266

After initial release of this library, the upstream WiFi.hostByName() stopped resolving mDNS queries. I am exploring other options to provide name resolution for mDNS on the ESP8266.

Contributing

If you would like to contribute to this project:

  • Report bugs and errors
  • Ask for enhancements
  • Create issues and pull requests
  • Tell other people about this library

License

The library is licensed under the MIT License.

Copyright

LCBUrl is Copyright © 2019-2022 by Lee C Bussy.