QQWRY

https://github.com/zfh521/rust-qqwry
Admin
QQWRY is a Rust library for searching IP address geolocation information using the qqwry.data...
Tokens:3,493
Snippets:23
Trust Score:5.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Convert IP Range to Strings with `get_start_ip_str` / `get_end_ip_str`

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

These methods convert the raw `u32` start and end IP values in `IPLocation` back into dotted-decimal IPv4 strings. Useful for displaying the full IP range.

```rust
use qqwry::qqwry::QQWry;

fn main() {
    let mut wry = QQWry::from(String::from("/path/to/qqwry.dat"));

    if let Some(loc) = wry.read_ip_location("1.1.1.1") {
        let start = loc.get_start_ip_str();
        let end   = loc.get_end_ip_str();
        println!("1.1.1.1 belongs to range: {} ~ {}", start, end);
        println!("Location: {} / {}", loc.country, loc.area);
    }
}

// Example output:
// 1.1.1.1 belongs to range: 1.1.1.1 ~ 1.1.1.1
// Location: APNIC&CloudFlare DNS Resolver project /  APNIC
```

--------------------------------

### Construct QQWry Instance with `from`

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

Creates a new QQWry instance by providing the file path to the qqwry.dat database. The file is opened on each call to `read_ip_location`.

```rust
use qqwry::qqwry::QQWry;

fn main() {
    // Provide the path to your local qqwry.dat file
    let wry = QQWry::from(String::from("/path/to/qqwry.dat"));
    println!("QQWry initialized with file: {}", wry.file);
}
```

--------------------------------

### Search IP Address Location with QQWry in Rust

Source: https://github.com/zfh521/rust-qqwry/blob/main/README.md

Initialize the QQWry database with the path to your 'qqwry.dat' file and then read the location for a given IP address. Ensure the file path is correct.

```rust
mod tests {
    use crate::qqwry;
    #[test]
    fn it_works() {
       let mut wry = qqwry::QQWry::from(String::from("/Users/zfh/Documents/qqwry.dat"));
       let location = wry.read_ip_location("127.0.0.1");
        println!("{:?}",location.unwrap());
    }
}
```

```shell
IPLocation { index_offset: 8206782, record_offset: 2633253, start_ip: 2130706433, end_ip: 2130706433, country: "本机地址", area: " CZ88.NET" }
```

--------------------------------

### Perform IP Geolocation in Rust

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

This Rust code snippet demonstrates how to initialize the QQWRY database and read IP location information. Ensure the `qqwry.dat` file is accessible, either in the current directory or specified via the `QQWRY_PATH` environment variable.

```rust
// src/main.rs
use qqwry::qqwry::QQWry;

fn main() {
    let db_path = std::env::var("QQWRY_PATH")
        .unwrap_or_else(|_| String::from("./qqwry.dat"));

    let mut wry = QQWry::from(db_path);

    let ip = "223.5.5.5";
    match wry.read_ip_location(ip) {
        Some(loc) => println!("{} -> {} {}", ip, loc.country, loc.area),
        None      => println!("{} -> not found", ip),
    }
}
```

--------------------------------

### Add QQWRY as a Cargo Dependency

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

Add this to your `Cargo.toml` file to include the QQWRY crate in your project.

```toml
[dependencies]
qqwry = "0.1.0"
```

--------------------------------

### QQWry::from

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

Constructs a new QQWry instance by providing the file path to the qqwry.dat database. The file is opened on each call to read_ip_location.

```APIDOC
## `QQWry::from` — Construct a QQWry instance

Creates a new `QQWry` instance by providing the file path to the `qqwry.dat` database. This does not open or validate the file at construction time; the file is opened on each call to `read_ip_location`.

```rust
use qqwry::qqwry::QQWry;

fn main() {
    // Provide the path to your local qqwry.dat file
    let wry = QQWry::from(String::from("/path/to/qqwry.dat"));
    println!("QQWry initialized with file: {}", wry.file);
}
```
```

--------------------------------

### Look up Geolocation with `read_ip_location`

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

Searches the qqwry.dat database for the geolocation record matching the given IPv4 address string. Returns `Some(IPLocation)` if found, or `None` if the IP is outside all ranges.

```rust
use qqwry::qqwry::QQWry;

fn main() {
    let mut wry = QQWry::from(String::from("/path/to/qqwry.dat"));

    let test_ips = vec![
        "127.0.0.1",
        "8.8.8.8",
        "1.1.1.1",
        "192.168.1.1",
    ];

    for ip in test_ips {
        match wry.read_ip_location(ip) {
            Some(location) => {
                println!("IP: {}", ip);
                println!("  Range:   {} - {}", location.get_start_ip_str(), location.get_end_ip_str());
                println!("  Country: {}", location.country);
                println!("  Area:    {}", location.area);
                println!("  Index offset:  {}", location.index_offset);
                println!("  Record offset: {}", location.record_offset);
            }
            None => {
                println!("IP: {} -> Not found in database", ip);
            }
        }
    }
}

// Example output for 127.0.0.1:
// IP: 127.0.0.1
//   Range:   127.0.0.1 - 127.0.0.1
//   Country: 本机地址
//   Area:     CZ88.NET
//   Index offset:  8206782
//   Record offset: 2633253
```

--------------------------------

### IPLocation Struct and Methods

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

The IPLocation struct holds geolocation data for a matched IP range. It includes public fields for IP values and decoded strings, along with helper methods to convert raw IP integers back to dotted-decimal strings.

```APIDOC
## `IPLocation` — Geolocation result struct

The `IPLocation` struct holds all data returned for a matched IP range. It derives `Debug` and exposes public fields for both raw `u32` IP values and decoded string fields. Two helper methods convert the raw integer IPs back to dotted-decimal strings.

```rust
use qqwry::qqwry::{QQWry, IPLocation};

fn print_location(loc: &IPLocation) {
    println!("Index Offset:  {}", loc.index_offset);
    println!("Record Offset: {}", loc.record_offset);
    println!("Start IP (u32): {}", loc.start_ip);
    println!("End IP   (u32): {}", loc.end_ip);
    println!("Start IP (str): {}", loc.get_start_ip_str());
    println!("End IP   (str): {}", loc.get_end_ip_str());
    println!("Country: {}", loc.country);
    println!("Area:    {}", loc.area);
    // Debug formatting is also available:
    println!("{:?}", loc);
}

fn main() {
    let mut wry = QQWry::from(String::from("/path/to/qqwry.dat"));
    if let Some(location) = wry.read_ip_location("8.8.8.8") {
        print_location(&location);
    }
}
```

## `IPLocation::get_start_ip_str` / `get_end_ip_str` — Convert IP range to strings

These methods convert the raw `u32` start and end IP values stored in the `IPLocation` struct back into human-readable dotted-decimal IPv4 strings. Useful when displaying the full IP range that the queried address belongs to.

```rust
use qqwry::qqwry::QQWry;

fn main() {
    let mut wry = QQWry::from(String::from("/path/to/qqwry.dat"));

    if let Some(loc) = wry.read_ip_location("1.1.1.1") {
        let start = loc.get_start_ip_str();
        let end   = loc.get_end_ip_str();
        println!("1.1.1.1 belongs to range: {} ~ {}", start, end);
        println!("Location: {} / {}", loc.country, loc.area);
    }
}

// Example output:
// 1.1.1.1 belongs to range: 1.1.1.1 ~ 1.1.1.1
// Location: APNIC&CloudFlare DNS Resolver project /  APNIC
```
```

--------------------------------

### Access `IPLocation` Struct Fields

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

The `IPLocation` struct holds geolocation data including IP ranges, country, area, and offsets. It provides helper methods to convert raw IP values to strings.

```rust
use qqwry::qqwry::{QQWry, IPLocation};

fn print_location(loc: &IPLocation) {
    println!("Index Offset:  {}", loc.index_offset);
    println!("Record Offset: {}", loc.record_offset);
    println!("Start IP (u32): {}", loc.start_ip);
    println!("End IP   (u32): {}", loc.end_ip);
    println!("Start IP (str): {}", loc.get_start_ip_str());
    println!("End IP   (str): {}", loc.get_end_ip_str());
    println!("Country: {}", loc.country);
    println!("Area:    {}", loc.area);
    // Debug formatting is also available:
    println!("{:?}", loc);
}

fn main() {
    let mut wry = QQWry::from(String::from("/path/to/qqwry.dat"));
    if let Some(location) = wry.read_ip_location("8.8.8.8") {
        print_location(&location);
    }
}
```

--------------------------------

### QQWry::read_ip_location

Source: https://context7.com/zfh521/rust-qqwry/llms.txt

Searches the qqwry.dat binary database for the geolocation record matching the given IPv4 address string. Returns Some(IPLocation) if found, or None if the IP is outside all ranges in the database.

```APIDOC
## `QQWry::read_ip_location` — Look up geolocation for an IPv4 address

Searches the `qqwry.dat` binary database for the geolocation record matching the given IPv4 address string. Returns `Some(IPLocation)` if a matching record is found, or `None` if the IP is outside all ranges in the database. The function opens the database file, reads the header to locate index boundaries, and performs a forward/right-edge search to find the containing IP range.

```rust
use qqwry::qqwry::QQWry;

fn main() {
    let mut wry = QQWry::from(String::from("/path/to/qqwry.dat"));

    let test_ips = vec![
        "127.0.0.1",
        "8.8.8.8",
        "1.1.1.1",
        "192.168.1.1",
    ];

    for ip in test_ips {
        match wry.read_ip_location(ip) {
            Some(location) => {
                println!("IP: {}", ip);
                println!("  Range:   {} - {}", location.get_start_ip_str(), location.get_end_ip_str());
                println!("  Country: {}", location.country);
                println!("  Area:    {}", location.area);
                println!("  Index offset:  {}", location.index_offset);
                println!("  Record offset: {}", location.record_offset);
            }
            None => {
                println!("IP: {} -> Not found in database", ip);
            }
        }
    }
}

// Example output for 127.0.0.1:
// IP: 127.0.0.1
//   Range:   127.0.0.1 - 127.0.0.1
//   Country: 本机地址
//   Area:     CZ88.NET
//   Index offset:  8206782
//   Record offset: 2633253
```
```
Tokens:
Raw