ihapi.h File Overview

All technical information for the System API is included in a single ihapi.h header file. This document highlights the areas of ihapi.h that might affect your programs.

System API Functions and Data Structures

#pragma pack(push,BeforeihAPI)
#pragma pack(1)
The System API uses 1 byte packing for structures:
// Setup a link dependency on the ihAPI lib
#define ihAPILIB_NAME "ihAPI55.lib"
#define ihAPIDLL_NAME L"ihAPI55.dll"
#define ihAPIDLL_VERSION 550

The version specified in the given example changes for each version of Historian. The version of your program should match the version of Historian installed.

#ifdef _WCHAR_T_DEFINED
typedef ihPUBLIC wchar_t ihChar; 
#else 
typedef ihPUBLIC unsigned short ihChar; 
#endif 
The System API uses Unicode. Your program should use ihChar for all strings and you can find the correct data type from ihapi.h file.
typedef struct ihTimeStruct {
MSO_ULONG Seconds; 
MSO_ULONG Nanoseconds; 
} ihTimeStruct; // (Must match MSOTimeStruct) 

Timestamps are nanosecond resolution in the System API. However, only microseconds are exposed to users.

// Error Statuses typedef enum 
ihStatus { ihSTATUS_OK = 0,
 ... 
} ihStatus; 

There is a fixed set of error codes and you cannot add new ones. Your program can receive errors on reads or writes or tag adds and those errors will be described with the function documentation.

 typedef enum ihQualityStatus {
ihOPCBad = 0,
... 
} ihQualityStatus;
typedef enum ihQualitySubStatus {
ihOPCNonspecific = 0,
...
} ihQualitySubStatus;

Historian uses a fixed set of quality and subquality data and you cannot add new ones.

 typedef enum ihDataType {
ihDataTypeUndefined = 0,
... } ihDataType; 

There are a fixed set of data types and user-defined data types. You cannot add new native data types.

 typedef enum ihSamplingMode {
 ihSamplingModeUndefined=0, 
... 
} ihSamplingMode;
typedef enum ihCalculationMode {
ihCalculationModeUndefined=0, 
... 
} ihCalculationMode; 

To read data you should specify a sampling mode, calculation mode, a filter condition (optional), and a query modifier (optional).

typedef ihHIDDEN struct ihBlobData {
ihVoidPtr Blob;
MSO_ULONG BlobSize; 
} ihBlobData; 

The blob data type is a size and a pointer in the System API

typedef struct ihTagProperties { 
ihString Tagname; 
... 
} ihTagProperties; 

A tag has a fixed set of properties as listed in this structure. Some tag properties may not exist in the earlier versions of Historian and new properties may be added in the future. You are limited to the set of properties available in the version of the ihapi.h shipped with this SDK and you cannot add new tag properties.

 typedef struct ihDataProperties {
 ihTimeStruct TimeStamp;
 ihDataType ValueDataType;
 ihValue Value;
 ihQuality Quality;
 unsigned char NumberOfComments;
 ihCommentsPtr Comments; 
ihGeoLocation Unsupported; 
} ihDataProperties; 
The given prototype is the structure for one raw data sample and it has timestamp, data type, value, and quality. It can optionally have comments. This structure is used on both data reads and data writes.
typedef struct ihDataRecordset {
 ihDataFields Fields;
 ihDataCriteria Criteria;
 ihUNSIGNED long NumberOfResults; // (Num items in results)
 ihDataResultPtr Results; // (array. One for each matching tag) 
} ihDataRecordset;

The given prototype is a collection of data samples that you get back from a data read or subscription.

Callback Prototypes/typedefs

typedef void (__stdcall *ihInterfaceGetCurrentValueCallbackFunction) (ihServerHandle hServer, void *UserParameter, 
ihUNSIGNED long NumberOfSourceAddresses,  
ihString *SourceAddresses, ihCallbackId CallbackId); 

A lot of information can be communicated to your program using callback if you subscribe to changes which is optional. The following sections describe this in more detail.