-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.md
102 lines (72 loc) · 5.25 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# Wake-on-LAN
[![pub.dev][image-pubdev]][link-pubdev]
![license][image-license]
Dart library package to easily send [Wake-on-LAN][link-wiki-wol] magic packets to devices on your local network.
## Getting Started
`wake_on_lan` has three core classes for functionality, `IPAddress`, `MACAddress`, and `WakeOnLAN`. All classes are exported in the main file, to import:
```dart
import 'package:wake_on_lan/wake_on_lan.dart';
```
#### Create an IP Address
`IPAddress` has a static function, `validate(address, { type })` which allows for easy validation that an IP address string is correctly formatted. An IPv6 address can be used, but `type` must be set to `InternetAddressType.IPv6` during validation of the address and construction of the class.
Create an `IPAddress` instance by using `IPAddress(address, { type })` where `address` is a string representation of the [broadcast address][link-broadcast-tool] (IPv4) or multicast address (IPv6) of the network and `type` is the internet address type (defaults to `InternetAddressType.IPv4`). The constructor will call the validation function mentioned above, but will throw the exception on a poorly constructed address string, so it is recommended to validate it first.
```dart
String ipv4 = '192.168.1.1';
final validation = IPAddress.validate(ipv4);
if(validation.state) {
IPAddress ip = IPAddress(ipv4);
// Continue execution
} else {
// Handle invalid the address case - access the error that was thrown during validation via `validation.error`.
}
```
You can also optionally create an `IPAddress` instance using the `fromHost(host, { type, hostPredicate })` static method which will lookup the host and use the associated IP address. By default the function will select and return the first address returned within the lookup. `hostPredicate` can be set to choose which host address is selected and returned.
#### Create MAC Address
`MACAddress` has a static function, `validate(String address, { delimiter })` which allows easy validation that a MAC address string is correctly formatted.
Create a `MACAddress` instance by using `MACAddress(address, { delimiter })` where `address` is a string representation of the address. The constructor will call the validation function mentioned above, but will throw the exception on a poorly constructed address string, so it is recommended to validate it first.
```dart
String address = 'AA:BB:CC:DD:EE:FF';
final validation = MACAddress.validate(address);
if(validation.state) {
MACAddress mac = MACAddress(address);
//Continue execution
} else {
// Handle invalid address case
}
```
You can optionally pass in a custom `delimiter` when the octets are not separated by colons (:). Ensure you pass the custom `delimiter` to both the `validate` function and the factory constructor when instantiating a `MACAddress` in this scenario.
```dart
String delimiter = '#';
String address = 'AA#BB#CC#DD#EE#FF';
if(MACAddress.validate(address, delimiter: delimiter)) {
MACAddress mac = MACAddress(address, delimiter: delimiter);
//Continue execution
} else {
// Handle invalid the address case - access the error that was thrown during validation via `validation.error`.
}
```
#### Sending the Wake-on-LAN Packet
Create a `WakeOnLAN` instance by using `WakeOnLAN(ip, mac, { port })` where `ip` is an `IPAddress` instance, `mac` is a `MACAddress` instance, and `port` is an optional integer parameter for which port the packet should be sent over (defaulted to the specification standard port, 9).
Once created, call the function `wake({ repeat })` on the `WakeOnLAN` object to send the packet. You may optionally set the `repeat` integer parameter to repeatedly send the Wake on LAN packet (with a 100ms delay between repeats) before closing the socket connection.
```dart
String mac = 'AA:BB:CC:DD:EE:FF';
String ipv6 = '2001:0DB8:3333:4444:5555:6666:7777:8888';
final macValidation = MACAddress.validate(mac);
final ipValidation = IPAddress.validate(ipv6, type: InternetAddressType.IPv6);
if(macValidation.state && ipValidation.state) {
MACAddress macAddress = MACAddress(mac);
IPAddress ipAddress = IPAddress(ipv6, type: InternetAddressType.IPv6);
WakeOnLAN wakeOnLan = WakeOnLAN(ipAddress, macAddress);
await wakeOnLan.wake().then(() => print('sent'));
}
```
## Web Support
Wake on LAN functionality utilizes the [User Datagram Protocol (UDP)][link-wiki-udp] which is not available in the browser because of security constraints.
## Notes
Because wake-on-LAN packets are sent over UDP, beyond the successful creation of a datagram socket and sending the data over the network, there is no way to confirm that the machine has been awoken beyond pinging the machine after waking it (**This functionality is not implemented in this package**). This is because of the nature of UDP sockets which do not need to establish the connection for the data to be sent.
[link-broadcast-tool]: https://remotemonitoringsystems.ca/broadcast.php
[link-pubdev]: https://pub.dev/packages/wake_on_lan/
[link-wiki-udp]: https://en.wikipedia.org/wiki/User_Datagram_Protocol
[link-wiki-wol]: https://en.wikipedia.org/wiki/Wake-on-LAN
[image-license]: https://img.shields.io/github/license/JagandeepBrar/package-wake-on-lan?style=for-the-badge
[image-pubdev]: https://img.shields.io/pub/v/wake_on_lan.svg?style=for-the-badge