package maxminddb

maxminddb-golang – github.com/oschwald/maxminddb-golang Index | Examples | Files

import "github.com/oschwald/maxminddb-golang"

Index ¶

Constants
type InvalidDatabaseError

func (e InvalidDatabaseError) Error() string

type Metadata
type Networks

func (n *Networks) Err() error
func (n *Networks) Network(result interface{}) (*net.IPNet, error)
func (n *Networks) Next() bool

type Reader

func FromBytes(buffer []byte) (*Reader, error)
func Open(file string) (*Reader, error)
func (r *Reader) Close() error
func (r *Reader) Decode(offset uintptr, result interface{}) error
func (r *Reader) Lookup(ip net.IP, result interface{}) error
func (r *Reader) LookupNetwork(ip net.IP, result interface{}) (network *net.IPNet, ok bool, err error)
func (r *Reader) LookupOffset(ip net.IP) (uintptr, error)
func (r *Reader) Networks() *Networks
func (r *Reader) Verify() error

type UnmarshalTypeError

func (e UnmarshalTypeError) Error() string

Constants ¶

const (
	// NotFound is returned by LookupOffset when a matched root record offset
	// cannot be found.
	NotFound = ^uintptr(0)
)

Types ¶

type InvalidDatabaseError ¶

type InvalidDatabaseError struct {
	// contains filtered or unexported fields
}

InvalidDatabaseError is returned when the database contains invalid data and cannot be parsed.

func (InvalidDatabaseError) Error ¶

func (e InvalidDatabaseError) Error() string

type Metadata ¶

type Metadata struct {
	BinaryFormatMajorVersion uint              `maxminddb:"binary_format_major_version"`
	BinaryFormatMinorVersion uint              `maxminddb:"binary_format_minor_version"`
	BuildEpoch               uint              `maxminddb:"build_epoch"`
	DatabaseType             string            `maxminddb:"database_type"`
	Description              map[string]string `maxminddb:"description"`
	IPVersion                uint              `maxminddb:"ip_version"`
	Languages                []string          `maxminddb:"languages"`
	NodeCount                uint              `maxminddb:"node_count"`
	RecordSize               uint              `maxminddb:"record_size"`
}

Metadata holds the metadata decoded from the MaxMind DB file. In particular in has the format version, the build time as Unix epoch time, the database type and description, the IP version supported, and a slice of the natural languages included.

type Networks ¶

type Networks struct {
	// contains filtered or unexported fields
}

Networks represents a set of subnets that we are iterating over.

func (*Networks) Err ¶

func (n *Networks) Err() error

Err returns an error, if any, that was encountered during iteration.

func (*Networks) Network ¶

func (n *Networks) Network(result interface{}) (*net.IPNet, error)

Network returns the current network or an error if there is a problem decoding the data for the network. It takes a pointer to a result value to decode the network's data into.

func (*Networks) Next ¶

func (n *Networks) Next() bool

Next prepares the next network for reading with the Network method. It returns true if there is another network to be processed and false if there are no more networks or if there is an error.

type Reader ¶

type Reader struct {
	Metadata Metadata
	// contains filtered or unexported fields
}

Reader holds the data corresponding to the MaxMind DB file. Its only public field is Metadata, which contains the metadata from the MaxMind DB file.

func FromBytes ¶

func FromBytes(buffer []byte) (*Reader, error)

FromBytes takes a byte slice corresponding to a MaxMind DB file and returns a Reader structure or an error.

func Open ¶

func Open(file string) (*Reader, error)

Open takes a string path to a MaxMind DB file and returns a Reader structure or an error. The database file is opened using a memory map, except on Google App Engine where mmap is not supported; there the database is loaded into memory. Use the Close method on the Reader object to return the resources to the system.

func (*Reader) Close ¶

func (r *Reader) Close() error

Close unmaps the database file from virtual memory and returns the resources to the system. If called on a Reader opened using FromBytes or Open on Google App Engine, this method does nothing.

func (*Reader) Decode ¶

func (r *Reader) Decode(offset uintptr, result interface{}) error

Decode the record at |offset| into |result|. The result value pointed to must be a data value that corresponds to a record in the database. This may include a struct representation of the data, a map capable of holding the data or an empty interface{} value.

If result is a pointer to a struct, the struct need not include a field for every value that may be in the database. If a field is not present in the structure, the decoder will not decode that field, reducing the time required to decode the record.

As a special case, a struct field of type uintptr will be used to capture the offset of the value. Decode may later be used to extract the stored value from the offset. MaxMind DBs are highly normalized: for example in the City database, all records of the same country will reference a single representative record for that country. This uintptr behavior allows clients to leverage this normalization in their own sub-record caching.

func (*Reader) Lookup ¶

func (r *Reader) Lookup(ip net.IP, result interface{}) error

Lookup retrieves the database record for ip and stores it in the value pointed to by result. If result is nil or not a pointer, an error is returned. If the data in the database record cannot be stored in result because of type differences, an UnmarshalTypeError is returned. If the database is invalid or otherwise cannot be read, an InvalidDatabaseError is returned.

Example (Interface)¶

This example demonstrates how to decode to an interface{}

Code:

{
	db, err := maxminddb.Open("test-data/test-data/GeoIP2-City-Test.mmdb")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ip := net.ParseIP("81.2.69.142")

	var record interface{}
	err = db.Lookup(ip, &record)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%v", record)
}

Example (Struct)¶

This example shows how to decode to a struct

Code:

{
	db, err := maxminddb.Open("test-data/test-data/GeoIP2-City-Test.mmdb")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ip := net.ParseIP("81.2.69.142")

	var record struct {
		Country struct {
			ISOCode string `maxminddb:"iso_code"`
		} `maxminddb:"country"`
	} // Or any appropriate struct

	err = db.Lookup(ip, &record)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(record.Country.ISOCode)
	// Output:
	// GB
}

Output:

GB

func (*Reader) LookupNetwork ¶

func (r *Reader) LookupNetwork(ip net.IP, result interface{}) (network *net.IPNet, ok bool, err error)

LookupNetwork retrieves the database record for ip and stores it in the value pointed to by result. The network returned is the network associated with the data record in the database. The ok return value indicates whether the database contained a record for the ip.

If result is nil or not a pointer, an error is returned. If the data in the database record cannot be stored in result because of type differences, an UnmarshalTypeError is returned. If the database is invalid or otherwise cannot be read, an InvalidDatabaseError is returned.

func (*Reader) LookupOffset ¶

func (r *Reader) LookupOffset(ip net.IP) (uintptr, error)

LookupOffset maps an argument net.IP to a corresponding record offset in the database. NotFound is returned if no such record is found, and a record may otherwise be extracted by passing the returned offset to Decode. LookupOffset is an advanced API, which exists to provide clients with a means to cache previously-decoded records.

func (*Reader) Networks ¶

func (r *Reader) Networks() *Networks

Networks returns an iterator that can be used to traverse all networks in the database.

Please note that a MaxMind DB may map IPv4 networks into several locations in in an IPv6 database. This iterator will iterate over all of these locations separately.

Example¶

This example demonstrates how to iterate over all networks in the database

Code:

{
	db, err := maxminddb.Open("test-data/test-data/GeoIP2-Connection-Type-Test.mmdb")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	record := struct {
		Domain string `maxminddb:"connection_type"`
	}{}

	networks := db.Networks()
	for networks.Next() {
		subnet, err := networks.Network(&record)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%s: %s\n", subnet.String(), record.Domain)
	}
	if networks.Err() != nil {
		log.Fatal(networks.Err())
	}
	// Output:
	// ::100:0/120: Dialup
	// ::100:100/120: Cable/DSL
	// ::100:200/119: Dialup
	// ::100:400/118: Dialup
	// ::100:800/117: Dialup
	// ::100:1000/116: Dialup
	// ::100:2000/115: Dialup
	// ::100:4000/114: Dialup
	// ::100:8000/113: Dialup
	// ::50d6:0/116: Cellular
	// ::6001:0/112: Cable/DSL
	// ::600a:0/111: Cable/DSL
	// ::6045:0/112: Cable/DSL
	// ::605e:0/111: Cable/DSL
	// ::6c60:0/107: Cellular
	// ::af10:c700/120: Dialup
	// ::bb9c:8a00/120: Cable/DSL
	// ::c9f3:c800/120: Corporate
	// ::cfb3:3000/116: Cellular
	// 1.0.0.0/24: Dialup
	// 1.0.1.0/24: Cable/DSL
	// 1.0.2.0/23: Dialup
	// 1.0.4.0/22: Dialup
	// 1.0.8.0/21: Dialup
	// 1.0.16.0/20: Dialup
	// 1.0.32.0/19: Dialup
	// 1.0.64.0/18: Dialup
	// 1.0.128.0/17: Dialup
	// 80.214.0.0/20: Cellular
	// 96.1.0.0/16: Cable/DSL
	// 96.10.0.0/15: Cable/DSL
	// 96.69.0.0/16: Cable/DSL
	// 96.94.0.0/15: Cable/DSL
	// 108.96.0.0/11: Cellular
	// 175.16.199.0/24: Dialup
	// 187.156.138.0/24: Cable/DSL
	// 201.243.200.0/24: Corporate
	// 207.179.48.0/20: Cellular
	// 2001:0:100::/56: Dialup
	// 2001:0:100:100::/56: Cable/DSL
	// 2001:0:100:200::/55: Dialup
	// 2001:0:100:400::/54: Dialup
	// 2001:0:100:800::/53: Dialup
	// 2001:0:100:1000::/52: Dialup
	// 2001:0:100:2000::/51: Dialup
	// 2001:0:100:4000::/50: Dialup
	// 2001:0:100:8000::/49: Dialup
	// 2001:0:50d6::/52: Cellular
	// 2001:0:6001::/48: Cable/DSL
	// 2001:0:600a::/47: Cable/DSL
	// 2001:0:6045::/48: Cable/DSL
	// 2001:0:605e::/47: Cable/DSL
	// 2001:0:6c60::/43: Cellular
	// 2001:0:af10:c700::/56: Dialup
	// 2001:0:bb9c:8a00::/56: Cable/DSL
	// 2001:0:c9f3:c800::/56: Corporate
	// 2001:0:cfb3:3000::/52: Cellular
	// 2002:100::/40: Dialup
	// 2002:100:100::/40: Cable/DSL
	// 2002:100:200::/39: Dialup
	// 2002:100:400::/38: Dialup
	// 2002:100:800::/37: Dialup
	// 2002:100:1000::/36: Dialup
	// 2002:100:2000::/35: Dialup
	// 2002:100:4000::/34: Dialup
	// 2002:100:8000::/33: Dialup
	// 2002:50d6::/36: Cellular
	// 2002:6001::/32: Cable/DSL
	// 2002:600a::/31: Cable/DSL
	// 2002:6045::/32: Cable/DSL
	// 2002:605e::/31: Cable/DSL
	// 2002:6c60::/27: Cellular
	// 2002:af10:c700::/40: Dialup
	// 2002:bb9c:8a00::/40: Cable/DSL
	// 2002:c9f3:c800::/40: Corporate
	// 2002:cfb3:3000::/36: Cellular
	// 2003::/24: Cable/DSL

}

Output:

::100:0/120: Dialup
::100:100/120: Cable/DSL
::100:200/119: Dialup
::100:400/118: Dialup
::100:800/117: Dialup
::100:1000/116: Dialup
::100:2000/115: Dialup
::100:4000/114: Dialup
::100:8000/113: Dialup
::50d6:0/116: Cellular
::6001:0/112: Cable/DSL
::600a:0/111: Cable/DSL
::6045:0/112: Cable/DSL
::605e:0/111: Cable/DSL
::6c60:0/107: Cellular
::af10:c700/120: Dialup
::bb9c:8a00/120: Cable/DSL
::c9f3:c800/120: Corporate
::cfb3:3000/116: Cellular
1.0.0.0/24: Dialup
1.0.1.0/24: Cable/DSL
1.0.2.0/23: Dialup
1.0.4.0/22: Dialup
1.0.8.0/21: Dialup
1.0.16.0/20: Dialup
1.0.32.0/19: Dialup
1.0.64.0/18: Dialup
1.0.128.0/17: Dialup
80.214.0.0/20: Cellular
96.1.0.0/16: Cable/DSL
96.10.0.0/15: Cable/DSL
96.69.0.0/16: Cable/DSL
96.94.0.0/15: Cable/DSL
108.96.0.0/11: Cellular
175.16.199.0/24: Dialup
187.156.138.0/24: Cable/DSL
201.243.200.0/24: Corporate
207.179.48.0/20: Cellular
2001:0:100::/56: Dialup
2001:0:100:100::/56: Cable/DSL
2001:0:100:200::/55: Dialup
2001:0:100:400::/54: Dialup
2001:0:100:800::/53: Dialup
2001:0:100:1000::/52: Dialup
2001:0:100:2000::/51: Dialup
2001:0:100:4000::/50: Dialup
2001:0:100:8000::/49: Dialup
2001:0:50d6::/52: Cellular
2001:0:6001::/48: Cable/DSL
2001:0:600a::/47: Cable/DSL
2001:0:6045::/48: Cable/DSL
2001:0:605e::/47: Cable/DSL
2001:0:6c60::/43: Cellular
2001:0:af10:c700::/56: Dialup
2001:0:bb9c:8a00::/56: Cable/DSL
2001:0:c9f3:c800::/56: Corporate
2001:0:cfb3:3000::/52: Cellular
2002:100::/40: Dialup
2002:100:100::/40: Cable/DSL
2002:100:200::/39: Dialup
2002:100:400::/38: Dialup
2002:100:800::/37: Dialup
2002:100:1000::/36: Dialup
2002:100:2000::/35: Dialup
2002:100:4000::/34: Dialup
2002:100:8000::/33: Dialup
2002:50d6::/36: Cellular
2002:6001::/32: Cable/DSL
2002:600a::/31: Cable/DSL
2002:6045::/32: Cable/DSL
2002:605e::/31: Cable/DSL
2002:6c60::/27: Cellular
2002:af10:c700::/40: Dialup
2002:bb9c:8a00::/40: Cable/DSL
2002:c9f3:c800::/40: Corporate
2002:cfb3:3000::/36: Cellular
2003::/24: Cable/DSL

func (*Reader) Verify ¶

func (r *Reader) Verify() error

Verify checks that the database is valid. It validates the search tree, the data section, and the metadata section. This verifier is stricter than the specification and may return errors on databases that are readable.

type UnmarshalTypeError ¶

type UnmarshalTypeError struct {
	Value string       // stringified copy of the database value that caused the error
	Type  reflect.Type // type of the value that could not be assign to
}

UnmarshalTypeError is returned when the value in the database cannot be assigned to the specified data type.

func (UnmarshalTypeError) Error ¶

func (e UnmarshalTypeError) Error() string

Source Files ¶

decoder.go errors.go mmap_unix.go node.go reader.go reader_other.go traverse.go verifier.go

Version: v1.5.0
Published: Sep 8, 2019
Platform: js/wasm
Imports: 12 packages
Last checked: now –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples