This is a Ping Library for the Vlang Programming-Language (Link: vlang/v).
vping uses the "native" ping and traceroute|tracert commands of Linux and Windows (!Currently not well tested on Windows, and not compatible with MacOS. Tested on Ubuntu 20 based system).
- Added (early stage) Support for
Traceroute - Traceroute (including the Docs for that) can be found in
/tracerouteas "submodule" - Import Traceroute via
import vping.traceroute - Traceroute has its own Structs called
ParsedTraceAnswerand newly introducingAbstractTraceAnswer. UnfortunatlyParsedTraceAnswerand the TraceParser isn't implemented yet. - But it should work :)
Traceroute Docs in this subfolder. No need to install it separately since its part of vping.
To install I'll recommend to use vpm.
Which is just this one command:
v install hall_of_code.vpingto install it including all dependencies.
The dependencies are os (Builtin) and pcre.
After installation, you can simply use it by:
import hall_of_code.vpingBut now to the more 'nerdy' part - the Documentation.
module main
import hall_of_code.vping
fn main() {
result := vping.ping(ip: "google.com") //returns an vping.Answer Object
println(result.parsed.mam_line) // "min/avg/max/mdev = 16.865/17.175/17.436/0.248 ms"
println("The AVG Ping after ${result.parsed.pk_send} packages send, was ${result.parsed.avg}ms!")
}| Argument | Description | Importance | Example |
|---|---|---|---|
ip |
The IP-Adress/Hostname/Domain of the Host | required |
ping(ip: "google.com") |
count |
Number of Packets to send | (optional) |
ping(ip: "google.de", count: 4) |
timeout |
On Windows this is the time per Packet in MS - on Linux its for the whole Ping Process and in Seconds. | (optional) |
ping(ip: "google.de", timeout: 10) |
size |
Size per Packet to send in Byte | (optional) |
ping(ip: "google.de", size: 16) |
force |
Force to use IPv4 / IPv6 | (optional) |
ping(ip: "google.de", force: 4) //forces to IPv4 |
ttl |
Given TTL | (optional) |
ping(ip: "google.de", ttl: 15) |
iface |
Network Interface Name (Linux-Only) | (optional/Linux-Only) |
ping(ip: "google.de", iface: "eth0" |
interval |
Interval of packets in Seconds (Linux-Only) | (optional/Linux-Only) |
ping(ip: "google.de", interval: 1) |
Only public functions are documented here :) //everything else -> todo for later
This function takes a Conf-Struct as Parameter - since this is comparable with "named arguments", you also can do:
ping(ip: "google.de", count: 2, timeout: 5)The Command takes some time - (while running the Ping Process by os.execute) and then - returns an Answer{}
Struct/Object.
(Just for visualization-purpose).
This function is callable on Answer-Object, and returns a new Answer where <Answer>.raw all "\n" replaced by " ".
Example:
module main
import hall_of_code.vping
fn main() {
answ := vping.ping(ip: "google.com", timeout: 5, count: 2).no_newline_raw()
println(answ.raw)
}pub struct Answer {
mut:
conf Conf //given Conf (line {ip: "google.de", count: 3})
command string //the generated ping-command
status int //status code (exit_status) -> 0 = everything ok, 1 = packetloss, 2 = ping-error
raw string //full terminal-response as string
parsed Parsed //parsed response, here it gets interesting ;)
}pub struct Parsed {
pub mut:
time_tt int = -1 //in ms
pk_send int = -1 //number of packages send
pk_recv int = -1 //number of packages received
pk_loss_percent int = -1 //package loss in percent%
mam_line string = "-1" //min/max/avg full line
avg f32 = -1 //ms
min f32 = -1 //ms
max f32 = -1 //ms
mdev f32 = -1 //ms
//vping specific error (NOT comparable with Status-code (exit code) of ping command):
is_err int //if parse() error [vping specific] 1 = yes, 0 = no error detected
}!! Parser should only work properly for Linux right now - so for Windows you have to parse the Answer.raw yourself !! //todo
Force to use IPv6 Ping:
module main
import hall_of_code.vping
fn main() {
answ := vping.ping(ip: "ipv6.google.com", force: 6, timeout: 10)
if answ.status == 0 {
println(answ.parsed.avg.str()) //print the average time it took
} else if answ.status == 1 {
println("Packet Loss: " + answ.parsed.pk_loss_percent.str() + "%") //print the Packet Loss in %
} else {
println("Error: Status-Code = " + answ.status.str()) //print the Status Code
println(answ.raw) //print out ping response from terminal as string
}
}Use Conf-Struct as Parameter:
module main
import hall_of_code.vping
fn main() {
params := vping.Conf{
ip: "google.de"
count: 6
timeout: 10
interval: 2
}
println(vping.ping(params))
}When some values of Conf or Parsed are == -1 there would be a parsing/general problem.
Edit: For that case its now Parsed.is_err implemented (Linux only), if nothing got parsed/changed this value is 1. So feel free
to use
if result.parsed.is_err == 1 { println('ping result is not valid for usage - parser cant parse the result (raw)')}Since just few values shouldn't end up as an Error or Failure, it's implemented like that. So when using the
Answer make sure to proof if the value is >= 0 to "validate" it.