Interface Reference

vtView API Reference

vtView API is a library, which can be integrated in your software that retrieves usage, life and data retention information from a Virtium SSD.

Note: We try to keep this document up-to-date as possible. If you have any questions or to report errors, please contact software.support@virtium.com.

How To

vtViewApi is provided as Windows DLL, which can be integrated into your application in QT or Windows Visual Studio.

For Linux, please contact your Virtium FAE to discuss an integrated solution that will match your operating environment.

Include

#include “vtViewApi.h”

Compatibility

C++ 9, C++11, C++14

Using

<vector>

<string>

Downloads

If the operating environment required is not in the list, please contact your Virtium FAE.

­­­­

API Name OS, Compiler Support
vtViewApi-Windows-1.0-minGW Windows, Qt Builder (minGW)
vtViewApi-Windows-1.0-VS Windows, Microsoft Visual Studio ++
vtViewApi-Linux-32-x86-1.0.so Linux 32 bit, x86, gcc
vtViewApi-Linux-64-x86-1.0.so Linux 64 bit, x86, gcc

 

Get Usage Statistics

+ getUsageStatistics ()

Returns SSD usage statistics:

  • Remaining Life percentage: integer, value range from 0 – 100. Example: 10 is 10%
  • Remaining TBW: double, remaining Terabyte Written, unit is in GB. Example, 200 is 200GB
  • Remaining Time: double, estimate remaining time in hour. Example, 24 is 24 hours
  • Data Write in MB/hour: double, normalized workload in term of MB write per hour. Example, 5 is 5 MB/hour

Declaration

bool getUsageStatistics (const sGetUsageSetting & rSetting, sUsageStatistics& rUsageStatistics)

Parameters

Input: sGetUsageSetting &

Output: sUsageStatistics &

Parameter Descriptions

struct sGetUsageSetting
{

std::string SerialNo;
unsigned int StartRecord;
unsigned int RecordCount;

}

struct sUsageStatistics
{

unsigned int EstimateRemainingTBW;
unsigned int EstimateRemainingTime;
unsigned int DataWriteInGBperHour;
unsigned int RemainingLifePercentage;

};

 

Return Value

true: data is retrieved successfully. Output parameter contains valid data.

false: there is an error. Use GetLastError () to retrieve error code. See error code

 

Estimate Power off Data Retention

+ getPowerOffDataRetentionEstimate ()

The power off data retention is dictated by storage temperature based upon the SSD’s current condition. The estimates are returned for 25 C, 40 C, 55 C, 70 C, and 85 C.

Declaration

bool getPowerOffDataRetentionEstimate (std::string serialNo, sDataRetentionInfo &rDataRetention)

Parameters

Input: std::string serialNo

Output: sDataRetentionInfo & rDataRetention

Parameter Descriptions

struct sGetUsageSetting
{

unsigned int RemainingDay_25C;
unsigned int RemainingDay_40C;
unsigned int RemainingDay_55C;
unsigned int RemainingDay_70C;
unsigned int RemainingDay_85C;

}

Return Value

true: data is retrieved successfully. Output parameter contains valid data.

false: there is an error. Use GetLastError () to retrieve error code. See error code

Generate Log for Analysis

+ startLogging ()

This function starts a recording of SMART attributes in a log file. Application software must set up the following parameters:

  • Drive’s serial number: specify SSD to log using its serial number. Several serial numbers can be set for the same call.
  • Duration: unit of this number is seconds. Example, 3600 for 3600 seconds or one hour.
  • Frequency: how often the data will be logged in seconds. Example, 60 for 60 seconds.
  • Log file: name and path to log file,

Declaration

bool startLogging (const sLogSetting &rSetting)

Parameters

struct sLogSetting
{

std::string FileName;
unsigned int DurationInSec;
unsigned int FrequencyInSec;
std::set<std::string> SerialSet;

}

Return Value

true: data is retrieved successfully. Output parameter contains valid data.

false: there is an error. Use GetLastError () to retrieve error code. See error code

Error Handling

  • Recording stops automatically when disk is full.
  • Recording of a drive stops automatically when drive is unplugged

For failure reason code, use GetLastError ().

+ stopLogging ()

Stop or cancel current SMART logging session. .

Declaration

bool stopLogging ()

Parameters

none

Return Value

true: data is retrieved successfully. Output parameter contains valid data.

false: there is an error. Use GetLastError () to retrieve error code. See error code

SSD Detection & Identification

+ getDeviceArray ()

Returns a list of SSDs and their identify device information.

Declaration

void getDeviceArray (std::vector<sDeviceIdentification> & rDeviceArray)

Parameters

struct sDeviceIdentification
{

std::string SerialNo;
std::string ModelString;
std::string FirmwareRev;
std::string DevicePath;

};

Return Value

none

Logistics

+ ReleaseLogData ()

Release log data and memory resource.

It is important to use this function when there is no need to keep the log in memory.

Declaration

void ReleaseLogData ();

Parameters

none

Return Value

none

+ getLastError ()

Returns last error code.

Declaration

VtViewApi::eErrorCode getLastError ();

Parameters

None

Return Value

Error No

+ getRecordCount ()

Returns current record count in the log. Record count is required when calling function getUsageStatistics.

Please read retrieve usage statistics page for how to use record count.

Declaration

bool getRecordCount (const std::string & serialNo, unsigned int & recordCount);

Parameters

In: std::string serialNo – Serial number of the target SSD

Out: unsigned int & recordCount – record count will be stored in this reference parameter

Return Value

true: data is retrieved successfully. Output parameter contains valid data.

false: there is an error. Use GetLastError () to retrieve error code. See error code

Constants & Structures

Error code

enum eErrorCode {

eErrorNone = 0, eSerialNumberNotFound = 1, eRecordNotFound = 2, eAlreadyScheduled = 3, eNoLogFileSpecified = 4, eDriveUnplugged = 5, eFailToCreateLogFile = 6, eFailToSchedule = 7, eInvalidId = 8, eNoOfReturnCode

};

Device Information

struct sDeviceIdentification
{
std::string SerialNo;
std::string ModelString;
std::string FirmwareRev;
std::string DevicePath;
};