Inheritance diagram for Com.DeviceAtlas.Carrier.CarrierApi:

Public Member Functions
	CarrierApi ()
	Construct a Carrier API object More...

	CarrierApi (string path)
	Construct a Carrier API object and Load the data file from the provided path. More...

string	GetDeviceAtlasApiVersion ()
	Get CarrierApi version. More...

virtual void	DownloadAndLoadDataFile (DataFileConfig dataFileConfig)
	Downloads and loads the DeviceAtlas carrier detection data into the API. The data file is downloaded from the DeviceAtlas web-site. More...

virtual void	DownloadAndLoadDataFile (string dataFileDownloadUrl)
	Downloads and loads the DeviceAtlas carrier detection data into the API. The data file is downloaded from the DeviceAtlas web-site. More...

void	LoadDataFromFile (string path)
	Load the data file from the provided path. The data file is reloaded every time this method is called. More...

string	GetDataFileCopyright ()
	Returns the data file copyright text. More...

string	GetDataFileCreationDate ()
	Returns the data file creation date in ISO8601 format. More...

string	GetDataFileVersion ()
	Returns the version of the data file. More...

Properties	GetProperties (string ipv4)
	Get the Carrier properties for a given IP address. More...

Properties	GetProperties (Dictionary< string, string > keyVals)

Property	GetProperty (string ipv4, string propertyName)

Property	GetProperty (Dictionary< string, string > keyVals, string propertyName)

ReadOnlyCollection< PropertyName >	GetPropertyNames ()
	A set of all the possible property names. The Set contains PropertyName objects that each have a string name and an associated data type. More...

string	GetIp (Dictionary< string, string > keyVals)
	Get the most suitable IP address from the given keyVals set of HTTP headers. This function checks the headers defined in HEADERS_TO_CHECK. More...

string	ExtractIp (string headerName, string headerValue)

Static Public Member Functions
static string	GetApiVersion ()
	Get CarrierApi version. More...

static bool	IsPublicIp (string ipStr)
	An IP address is considered public if it is not in any of the following ranges: More...

Static Public Attributes
static readonly string	API_VERSION = "1.3"

static readonly string []	HEADERS_TO_CHECK
	A list of HTTP headers to choose the original client IP address from. In addition to these the RemoteAddr (REMOTE_ADDR) is also used as a final fallback. More...

Detailed Description

The main class for the Carrier Identification API. Used to load the data file and to perform lookups using IPv4 addresses. For usage in a Web Container it is recommended to also include the CarrierApiWeb jar file as this facilitates passing a HttpRequest object.

Please note that it is advisable to load only a single instance of this class to avoid multiple loadings of the data file. This can be done in a Web Container by storing a reference to it in the ServletContext.

Example usage:

string ip = "62.40.34.220";
CarrierApi carrierApi = new CarrierApi();
carrierApi.LoadDataFromFile("/path/to/sample.dat");
// get all properties
Properties props = carrierApi.GetProperties(ip);
// .... use the properties ....
if (props.ContainsKey("networkOperator"))
{
    Property property   = props.Get("networkOperator");
    String operatorName = property.AsString();
    Response.Write("networkOperator: "+operatorName);
}
// get a single property
Property mccProp = carrierApi.GetProperty(ip, "mcc");
if (mccProp != null)
{
    string mcc = mccProp.AsString();
    Response.Write("MCC: "+mcc);
}

Please see the code in the Examples directory for additional samples.

Copyright: Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved.

Author: DeviceAtlas Limited

Constructor & Destructor Documentation

◆ CarrierApi() [1/2]

Com.DeviceAtlas.Carrier.CarrierApi.CarrierApi ( )

inline

Construct a Carrier API object

◆ CarrierApi() [2/2]

Com.DeviceAtlas.Carrier.CarrierApi.CarrierApi ( string path )

inline

Construct a Carrier API object and Load the data file from the provided path.

Parameters

path	The path on disk to the data file.

Exceptions

DataLoadingException thrown when there is a problem with the data file.

Member Function Documentation

◆ DownloadAndLoadDataFile() [1/2]

virtual void Com.DeviceAtlas.Carrier.CarrierApi.DownloadAndLoadDataFile ( DataFileConfig dataFileConfig )

inlinevirtual

Downloads and loads the DeviceAtlas carrier detection data into the API. The data file is downloaded from the DeviceAtlas web-site.

Parameters

dataFileConfig Data file download and load configuration

Exceptions

DataLoadingException

◆ DownloadAndLoadDataFile() [2/2]

virtual void Com.DeviceAtlas.Carrier.CarrierApi.DownloadAndLoadDataFile ( string dataFileDownloadUrl )

inlinevirtual

Downloads and loads the DeviceAtlas carrier detection data into the API. The data file is downloaded from the DeviceAtlas web-site.

Parameters

dataFileDownloadUrl The URL to download the data file from.

Exceptions

DataLoadingException

◆ ExtractIp()

string Com.DeviceAtlas.Carrier.CarrierApi.ExtractIp	(	string	headerName,
		string	headerValue
	)

inline

Extracts and cleans an IP address from the headerValue. Some headers such as "X-Forwarded-For" can contain multiple IP addresses such as: clientIP, proxy1, proxy2...

This method splits up the headerValue and takes the most appropriate value as the IP.

Parameters

headerName	The name of the HTTP Header
headerValue	The value for the HTTP Header

Returns: The most suitable IP Address or null if no IP is found

◆ GetApiVersion()

static string Com.DeviceAtlas.Carrier.CarrierApi.GetApiVersion ( )

inlinestatic

Get CarrierApi version.

Returns: CarrierApi version

◆ GetDataFileCopyright()

string Com.DeviceAtlas.Carrier.CarrierApi.GetDataFileCopyright ( )

inline

Returns the data file copyright text.

Returns: the copyright

◆ GetDataFileCreationDate()

string Com.DeviceAtlas.Carrier.CarrierApi.GetDataFileCreationDate ( )

inline

Returns the data file creation date in ISO8601 format.

Returns: the creationDate

◆ GetDataFileVersion()

string Com.DeviceAtlas.Carrier.CarrierApi.GetDataFileVersion ( )

inline

Returns the version of the data file.

Returns: the version

◆ GetDeviceAtlasApiVersion()

string Com.DeviceAtlas.Carrier.CarrierApi.GetDeviceAtlasApiVersion ( )

inline

Get CarrierApi version.

Returns: CarrierApi version

◆ GetIp()

string Com.DeviceAtlas.Carrier.CarrierApi.GetIp ( Dictionary< string, string > keyVals )

inline

Get the most suitable IP address from the given keyVals set of HTTP headers. This function checks the headers defined in HEADERS_TO_CHECK.

Parameters

keyVals A hash of HTTP headers {header-name:value}

Returns: IP address

◆ GetProperties() [1/2]

Properties Com.DeviceAtlas.Carrier.CarrierApi.GetProperties ( string ipv4 )

inline

Get the Carrier properties for a given IP address.

Parameters

ipv4	The IP address to find carrier properties for.

Returns: The found properties or null of no properties found.

◆ GetProperties() [2/2]

Properties Com.DeviceAtlas.Carrier.CarrierApi.GetProperties ( Dictionary< string, string > keyVals )

inline

Get the Carrier properties for a given Map of HTTP Headers. The API will choose the most appropriate IP to use.

The following headers are checked in order to find the most suitable IP address.

Client-Ip
X-Forwarded-For
Forwarded-For
Forwarded

Parameters

keyVals A map of HTTP header name to HTTP header value. Both must be strings.

Returns: The found properties or null if no properties found.

◆ GetProperty() [1/2]

Property Com.DeviceAtlas.Carrier.CarrierApi.GetProperty	(	string	ipv4,
		string	propertyName
	)

inline

Try and get a specific property for a given IP address.

Note: if multiple properties are needed for the same IP it is more efficient to call GetProperties() once than repeated calls to GetProperty().

Parameters

ipv4	The IP address to find carrier properties for.
propertyName	The name of the property to return.

Returns: The Property or null if no property found.

Exceptions

InvalidPropertyNameException Thrown if the property name does not exist.

◆ GetProperty() [2/2]

Property Com.DeviceAtlas.Carrier.CarrierApi.GetProperty	(	Dictionary< string, string >	keyVals,
		string	propertyName
	)

inline

Try and get a specific property for a given Map of HTTP Headers. The API will choose the most appropriate IP to use.

Note: if multiple properties are needed for the same IP it is more efficient to call GetProperties() once than repeated calls to GetProperty().

Parameters

keyVals	A map of HTTP header name to HTTP header value. Both must be strings.
propertyName	The name of the property to return

Returns: The Property or null if no property found.

Exceptions

InvalidPropertyNameException Thrown if the property name does not exist.

◆ GetPropertyNames()

ReadOnlyCollection<PropertyName> Com.DeviceAtlas.Carrier.CarrierApi.GetPropertyNames ( )

inline

A set of all the possible property names. The Set contains PropertyName objects that each have a string name and an associated data type.

Returns: A list of PropertyName objects

◆ IsPublicIp()

static bool Com.DeviceAtlas.Carrier.CarrierApi.IsPublicIp ( string ipStr )

inlinestatic

An IP address is considered public if it is not in any of the following ranges:

1) any local address IP: 0

2) a local loopback address range: 127/8

3) a site local address i.e. IP is in any of the ranges: range: 10/8 range: 172.16/12 range: 192.168/16

4) a link local address range: 169.254/16

Parameters

ip	The IP address to check

Returns: True if it is a public IP, false if the IP is invalid or is not public.

◆ LoadDataFromFile()

void Com.DeviceAtlas.Carrier.CarrierApi.LoadDataFromFile ( string path )

inline

Load the data file from the provided path. The data file is reloaded every time this method is called.

Parameters

path	The path on disk to the data file.

Exceptions

IOException	Thrown when there is a problem loading the file.
DataLoadingException	thrown when there is a problem with the data file.

Member Data Documentation

◆ HEADERS_TO_CHECK

readonly string [] Com.DeviceAtlas.Carrier.CarrierApi.HEADERS_TO_CHECK

static

Initial value:

= {
            "x-forwarded-for",
            "client-ip", 
            "x-client-ip", 
            "rlnclientipaddr",    
            "proxy-client-ip",
            "wl-proxy-client-ip", 
            "x-forwarded",
            "forwarded-for",
            "forwarded",
        }

A list of HTTP headers to choose the original client IP address from. In addition to these the RemoteAddr (REMOTE_ADDR) is also used as a final fallback.

The documentation for this class was generated from the following file:

Src/API/Com/DeviceAtlas/Carrier/CarrierApi.cs

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CarrierApi() [1/2]

◆ CarrierApi() [2/2]

Member Function Documentation

◆ DownloadAndLoadDataFile() [1/2]

◆ DownloadAndLoadDataFile() [2/2]

◆ ExtractIp()

◆ GetApiVersion()

◆ GetDataFileCopyright()

◆ GetDataFileCreationDate()

◆ GetDataFileVersion()

◆ GetDeviceAtlasApiVersion()

◆ GetIp()

◆ GetProperties() [1/2]

◆ GetProperties() [2/2]

◆ GetProperty() [1/2]

◆ GetProperty() [2/2]

◆ GetPropertyNames()

◆ IsPublicIp()

◆ LoadDataFromFile()

Member Data Documentation

◆ HEADERS_TO_CHECK