MMDB2 Decoder v1.0.1 MMDB2Decoder View Source
MMDB2 file format decoder.
Usage
To prepare lookups in a given database you need to parse it and hold the result available for later usage:
iex(1)> database = File.read!("/path/to/database.mmdb")
iex(2)> {:ok, meta, tree, data} = MMDB2Decoder.parse_database(database)
Using the returned database contents you can start looking up individual entries:
iex(3)> {:ok, ip} = :inet.parse(String.to_charlist("127.0.0.1"))
iex(4)> MMDB2Decoder.lookup(ip, meta, tree, data)
{:ok, %{...}}
For more details on the lookup methods (and a function suitable for direct piping) please see the individual function documentations.
Floating Point Precision
Please be aware that all values of the type float
are rounded to 4
decimal digits and double
values to 8 decimal digits.
This might be changed in the future if there are datasets known to return values with a higher precision.
Link to this section Summary
Functions
Looks up the data associated with an IP tuple
Calls lookup/4
and raises if an error occurs
Parses a database binary and splits it into metadata, lookup tree and data
Utility method to pipe parse_database/1
directly to lookup/4
Calls pipe_lookup/2
and raises if an error from parse_database/1
is given
or occurs during lookup/4
Link to this section Types
decoded_value() View Source
lookup_result()
View Source
lookup_result() :: {:ok, lookup_value() | nil} | {:error, term()}
lookup_result() :: {:ok, lookup_value() | nil} | {:error, term()}
lookup_value()
View Source
lookup_value() :: decoded_value() | nil
lookup_value() :: decoded_value() | nil
parse_result()
View Source
parse_result() ::
{:ok, MMDB2Decoder.Metadata.t(), binary(), binary()} | {:error, term()}
parse_result() :: {:ok, MMDB2Decoder.Metadata.t(), binary(), binary()} | {:error, term()}
Link to this section Functions
lookup(ip, meta, tree, data)
View Source
lookup(:inet.ip_address(), MMDB2Decoder.Metadata.t(), binary(), binary()) ::
lookup_result()
lookup(:inet.ip_address(), MMDB2Decoder.Metadata.t(), binary(), binary()) :: lookup_result()
Looks up the data associated with an IP tuple.
This is probably the main function you will use. The ip
address is expected
to be a 4- or 8-element tuple describing an IPv4 or IPv6 address. To obtain
this tuple from a string you can use :inet.ip_address/1
.
Usage
iex> MMDB2Decoder.lookup({127, 0, 0, 1}, meta, tree, data)
{
:ok,
%{
continent: %{...},
country: %{...},
registered_country: %{...}
}
}
The values for meta
, tree
and data
can be obtained by
parsing the file contents of a database using parse_database/1
.
lookup!(ip, meta, tree, data)
View Source
lookup!(:inet.ip_address(), MMDB2Decoder.Metadata.t(), binary(), binary()) ::
lookup_value() | no_return()
lookup!(:inet.ip_address(), MMDB2Decoder.Metadata.t(), binary(), binary()) :: lookup_value() | no_return()
Calls lookup/4
and raises if an error occurs.
parse_database(contents)
View Source
parse_database(binary()) :: parse_result()
parse_database(binary()) :: parse_result()
Parses a database binary and splits it into metadata, lookup tree and data.
It is expected that you pass the real contents of the file, not the name of the database or the path to it.
Usage
iex> MMDB2Decoder.parse_database(File.read!("/path/to/database.mmdb"))
{
:ok,
%MMDB2Decoder.Metadata{...},
<<...>>,
<<...>>
}
If parsing the database fails you will receive an appropriate error tuple:
iex> MMDB2Decoder.parse_database("invalid-database-contents")
{:error, :no_metadata}
pipe_lookup(error, ip)
View Source
pipe_lookup(parse_result(), :inet.ip_address()) :: lookup_result()
pipe_lookup(parse_result(), :inet.ip_address()) :: lookup_result()
Utility method to pipe parse_database/1
directly to lookup/4
.
Usage
Depending on how you handle the parsed database contents you may want to pass the results directly to the lookup.
iex> "/path/to/database.mmdb"
...> |> File.read!()
...> |> MMDB2Decoder.parse_database()
...> |> MMDB2Decoder.pipe_lookup({127, 0, 0, 1})
{:ok, %{...}}
pipe_lookup!(arg, ip)
View Source
pipe_lookup!(parse_result(), :inet.ip_address()) :: lookup_value() | no_return()
pipe_lookup!(parse_result(), :inet.ip_address()) :: lookup_value() | no_return()
Calls pipe_lookup/2
and raises if an error from parse_database/1
is given
or occurs during lookup/4
.