Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lbussy/lcburl
Arduino library for handling URLs
https://github.com/lbussy/lcburl
arduino arduino-lib arduino-library url urllib
Last synced: 1 day ago
JSON representation
Arduino library for handling URLs
- Host: GitHub
- URL: https://github.com/lbussy/lcburl
- Owner: lbussy
- License: mit
- Created: 2019-10-06T13:02:50.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-25T17:26:53.000Z (16 days ago)
- Last Synced: 2025-01-05T11:16:48.619Z (5 days ago)
- Topics: arduino, arduino-lib, arduino-library, url, urllib
- Language: C++
- Size: 148 KB
- Stars: 7
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LCBUrl - An Arduino library for handling URLs
[](https://www.ardu-badge.com/LCBUrl)
[](https://github.com/lbussy/LCBUrl/releases)
[](https://github.com/lbussy/LCBUrl/blob/master/LICENSE)
[](http://github.com/lbussy/LCBUrl/issues)
[](http://github.com/lbussy/LCBUrl/pulls)
[](#Contributing)
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](https://tools.ietf.org/html/rfc3986). Take for example this terrifying URL:
`http://%7EFoo:%7Ep@[email protected]: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@[email protected]/~this/is/a/./path/test.php?foo=bar#frag`
- `getIPUrl()` returns: `http://~Foo:~p@[email protected]/~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@[email protected]`
- `getIPAuthority()` returns: `~Foo:~p@[email protected]`
- `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](#mdns-support)) re-parse a URL and replace the `*.local` hostname with the resolved IP address.
:exclamation: 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
:exclamation: 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:
- [X] Convert percent-encoded triplets to uppercase
- [X] Convert the scheme and host to lowercase
- [X] Decode percent-encoded triplets of unreserved characters
- [ ] Remove dot-segments
- [X] Convert an empty path to a "/" path
- [X] Remove the default port
- [X] ~~Add a trailing "/" to a non-empty path (may remove this)~~ (removed this after some thought)
- [X] 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](https://platformio.org/lib/show/6778/LCBUrl).
### Arduino IDE
LCBUrl is published via the [Arduino Library Manager](https://www.ardu-badge.com/LCBUrl). 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:
``` cpp
#include
```
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:
``` cpp
#define LCBURL_MDNS
#include
```
Or, define it globally in the platformio.ini or compiler definitions:
``` ini
-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](https://github.com/lbussy/LCBUrl/blob/master/LICENSE).
## Copyright
LCBUrl is Copyright © 2019-2022 by Lee C Bussy.