The DeviceAtlas Carrier documentation
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
Com.DeviceAtlas.Carrier.CarrierApi Class Reference

More...

Inheritance diagram for Com.DeviceAtlas.Carrier.CarrierApi:
Com.DeviceAtlas.Carrier.CarrierApiWeb Com.DeviceAtlas.Carrier.CarrierApiWeb

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< PropertyNameGetPropertyNames ()
 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.

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
pathThe path on disk to the data file.
Exceptions
DataLoadingExceptionthrown 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
dataFileConfigData 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
dataFileDownloadUrlThe 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
headerNameThe name of the HTTP Header
headerValueThe 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
keyValsA 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
ipv4The 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
keyValsA 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
ipv4The IP address to find carrier properties for.
propertyNameThe name of the property to return.
Returns
The Property or null if no property found.
Exceptions
InvalidPropertyNameExceptionThrown 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
keyValsA map of HTTP header name to HTTP header value. Both must be strings.
propertyNameThe name of the property to return
Returns
The Property or null if no property found.
Exceptions
InvalidPropertyNameExceptionThrown 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
ipThe 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
pathThe path on disk to the data file.
Exceptions
IOExceptionThrown when there is a problem loading the file.
DataLoadingExceptionthrown 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: