<![CDATA[
# DeviceAtlas Data File Configuration #
Automated data file download and load configuration.
### Overview ###
The DeviceAtlas Device API and Carrier API provide the functionality of
downloading and loading their respective data files given a URL. After
the first data file load a background task is scheduled to load a fresh
data file at a configured time in the future to ensure the API has the latest
version of DeviceAtlas data.
Please note that basic telemetry data such as the number of API lookups
are collected when using the download and load functionality.
### Obtaining the data file download URL ###
Please note that only data files using GZIP compression are supported by
the download and load feature.
#### Device Data File URL ####
Navigate to https://deviceatlas.com/user and copy the device data file download URL
located at "API Data Files" -> "Device Identification" -> "Download Data" -> "GZIP"
#### Carrier Data File URL ####
Navigate to https://deviceatlas.com/user and copy the carrier data file download URL
located at "API Data Files" -> "Carrier Identification" -> "Download Data" -> "GZIP"
### Basic Usage ###
To change the default download and load behaviour you must create an instance of the
`DataFileConfig` class and pass it to the `DownloadAndLoadDataFile` method in either an
instance of `DeviceApi` or `CarrierApi` :
```csharp
// Device data file example usage
DataFileConfig deviceDataFileConfig = DataFileConfigBuilder.Create(<data file download URL>).BuildDevice();
DeviceApi deviceApi = new DeviceApi();
deviceApi.DownloadAndLoadDataFile(deviceDataFileConfig);
// Carrier data file example usage
DataFileConfig carrierDataFileConfig = DataFileConfigBuilder.Create(<data file download URL>).BuildCarrier();
CarrierApi carrierApi = new CarrierApi();
carrierApi.DownloadAndLoadDataFile(carrierDataFileConfig);
```
### DataFileConfig class ###
The DataFileConfig class provides options to customize the frequency,
location and validation of the DeviceAtlas data file download.
* Download and load frequency
* Download file location
* Data file download connection timeout
* Data file download validation
* Disabling automatic data file download and load
#### Download and load frequency ####
The frequency in days to download and load the latest data file.
Note the minimum value is 1 day.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DownloadAndLoadFrequencyDays(<integer>);
```
**Default value**
1
#### Download and load schedule time ####
The time of day to schedule the download and load of the data file.
The format is HH:mm:ss (hours:minutes:seconds) e.g "13:00:00" will schedule
the file to be downloaded and loaded at 1PM.
Please note that this option is ignored on the first data file load and only
applies to the background task that downloads and loads the latest data file.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DownloadAndLoadScheduleTime(<string>);
```
**Default value**
The current time in hours, minutes and seconds
#### Download file location ####
The file system directory where the data file will be downloaded to.
It is strongly recommended to set this to a persistent file path to
ensure there is always a data file on the system that can be loaded
immediately.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).FileDirectory(<string>);
```
**Default value**
The system's temporary directory.
#### Data file download connection timeout ####
The time in milliseconds allowed to establish a connection to the download
server.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DownloadConnectionTimeoutMilliseconds(<integer>);
```
**Default value**
60000 (60 seconds)
#### Data file download read timeout ####
The time in milliseconds allowed to read data from the download server.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DownloadReadTimeoutMilliseconds(<integer>);
```
**Default value**
60000 (60 seconds)
#### Disabling automatic data file download and load ####
If for any reason it is necessary to prevent the scheduled load and
reload of the data file this can be achieved by calling the
`disableScheduledDownloadAndReload` method with `true`.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DisableScheduledDownloadAndReload(<boolean>);
```
**Default value**
false
#### Dealing with scheduled background data file load failures ####
In the event that the background task that loads the data file into the
API fails you may implement the `DownloadAndLoadTaskFailureCallback` interface
and set it in the `DataFile` object. If an exception occurs the `handle` method
of the interface will be called and an instance of `System.Exception` is passed
as a parameter. An example use case for this callback would be to log the exception.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DownloadAndLoadTaskFailureCallback(<DownloadAndLoadTaskFailureCallback>);
```
**Example**
```csharp
class DownloadAndLoadTaskFailureCallbackImpl : DownloadAndLoadTaskFailureCallback
{
public void handle(System.Exception exception)
{
Console.WriteLine("Data file load task error: " + exception.Message);
}
}
DataFileConfigBuilder.Create(<data file download URL>).DownloadAndLoadTaskFailureCallback(new DownloadAndLoadTaskFailureCallbackImpl());
```
#### Scheduled data file load background task success callback ####
In addition to handling errors during the background task that loads the data file, a
success callback is also provided.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).DownloadAndLoadTaskSuccessCallback(<DownloadAndLoadTaskSuccessCallback>);
```
**Example**
```csharp
class DownloadAndLoadTaskSuccessCallbackImpl : DownloadAndLoadTaskSuccessCallback
{
public void handle()
{
Console.WriteLine("Data file load task success");
}
}
DataFileConfigBuilder.Create(<data file download URL>).DownloadAndLoadTaskSuccessCallback(new DownloadAndLoadTaskSuccessCallbackImpl());
```
### Custom Endpoint Data File Provisioning ###
If you would like to provision the data files from a custom endpoint please
note the following:
#### Supported content types ####
For both the Device and Carrier data files only GZIP compression is supported.
Please provide "application/x-gzip" or "application/gzip" as a "Content-Type" response header.
#### Data file download validation ####
The data file download is validated by comparing the MD5 checksum of the data file
against the MD5 checksum header (Content-MD5) sent with the data file download.
It is recommended to provide an MD5 checksum of the data file as a "Content-MD5"
response header.
If you do not wish to send an MD5 checksum header this validation can be disabled by
passing `false` to the `ValidateMD5` method. The name of the header containing the MD5
checksum can also be modified using the `headerContentMd5` method.
**Usage**
```csharp
DataFileConfigBuilder.Create(<data file download URL>).ValidateMD5(<boolean>).HeaderContentMd5(<string>);
```
**Validate MD5 default value**
true
**MD5 header default value**
"Content-MD5"
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved. _
_ https://deviceatlas.com _
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li><a href="README.Installation.html">Enterprise API Installation</a></li><li class="disabled"><a href="README.DataFileConfig.html">Data File Configuration</a></li><li><a href="README.DeviceApi.html">Device Identification API</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li class="divider"></li><li><a href="./DeviceApiDocs/classes.html">Device API Docs</a></li><li><a href="./CarrierApiDocs/classes.html">Carrier API Docs</a></li></ul></div>]]>