Connect Functions

ihuConnect

Use the ihuConnect function to connect to a Historian server. The function provides a server handle to be used in subsequent calls.

Prototype

ihuConnect {
 in MSO MSO Char * server,
 in MSO MSO Char * username, in MSO MSO Char * password, out long * serverhandle
};

Remarks

The inputs to the function are server, username, and password. Each has a default value if NULL is passed.

  • server: If NULL is passed, then the connection attempt is to the local machine.
  • username and password: If NULL is passed, then the username that owns the process is used. Most of the time this is the same as the user logged into the operating system. However, in the case of a program running as a service, you can specify a username and password that the process should use.

The output of this function is a server handle.

Server handles are valid only during the lifetime of the process. They should not be saved to a file and reused.

You do not need to call ihuConnectEx more than one time for a username and password. If the connection to the server was lost and restored, the handle can be used after reconnection. If the server was not available at connect time, a handle is still returned, which you can use as soon as the connection becomes available. Reconnects are performed inside the API. The application should wait and retry reads and writes with the returned server handle. Reads and writes succeed after the underlying connection is re-established.

You should still call ihuDisconnect with the returned server handle, even if an error is returned.

A connection to the server consumes a Client Access License (CAL) only if you have not already accessed the server from your current IP address. There is no way to connect without consuming a CAL.

Returns

The ihuConnect function returns the following values:

  • ihuSTATUS_OK
  • ihuSTATUS_FAILED
  • ihuSTATUS_API_TIMEOUT
  • ihuSTATUS_NOT_VALID_USER
  • ihuSTATUS_LIC_TOO_MANY_USERS

ihuConnectEx

Use the ihuConnectEx function to connect to a server with store and forward support.

Prototype

ihuErrorCode IHUAPI ihuConnectEx (
MSO Char * server,
MSO Char * username,
MSO Char * password,
MSO Char * buffername,
unsigned long MaxMegMemory,
unsigned long MinMegDiskFree,
long * serverhandle
);

Remarks

The inputs to this function are:

  • server: If NULL is passed, then the connection attempt is to the local machine.
  • username and password: If NULL is passed, then the username that owns the process is used. Most of the time this is the same as the user logged into the operating system. However, in the case of a program running as a service, you can specify a username and password that the process should use.
  • buffername: The target filename and location to store buffered data. The buffer file name must be unique.
  • MaxMegMemory: Maximum memory in MB. Buffered data is stored in this memory until it is full and is later stored to disk.
  • MinMegDiskFree: Minimum free disk space in MB.

The output of this function is a server handle.

Server handles are valid only during the lifetime of the process. They should not be saved to a file and reused.

There is no need to call ihuConnectEx more than one time for a username and password. If the connection to the server was lost and restored, the handle can be used after reconnection. If the server was not available at connect time, a handle is still returned, which you can use as soon as the connection becomes available. Reconnects are performed inside the API. The application should wait and retry reads and writes with the returned server handle. Reads and writes succeed after the underlying connection is re-established.

You should still call ihuDisconnect with the returned server handle, even if an error is returned.

A connection to the server consumes a Client Access License (CAL) only if you have not already accessed the server from your current IP address. There is no way to connect without consuming a CAL.

Returns

The ihuConnectEx function returns the following values:

  • ihuSTATUS_OK
  • ihuSTATUS_FAILED
  • ihuSTATUS_API_TIMEOUT
  • ihuSTATUS_NOT_VALID_USER
  • ihuSTATUS_LIC_TOO_MANY_USERS

ihuDisconnect

Use the ihuDisconnect function to release connection resources.

Prototype

ihuDisconnect {
in long serverhandle
};

Returns

The ihuDisconnect function returns the following values:

  • ihuSTATUS_OK

ihuSetConnectionParameters

Use the ihuSetConnectionParameters function to set the socket connection timeout.

Prototype

ihuSetConnectionParameters {
in IHU_CONNECTION_PARAMETERS*Params
};

Remarks

The input to the function is IHU_CONNECTION_PARAMETERS structure to pass in a connection timeout:

/* Client-side, global connection parameters */
typedef struct {
int Size; // Structure size in bytes
int TCPConnectionWindow; // Max time to establish a TCP connection with server in seconds (default 5s)
} IHU_CONNECTION_PARAMETERS;

The default connection timeout is 5 seconds. There is no maximum value, but it is not recommended to set the value to longer than 60 seconds. If you increase the timeout, server connection attempts take more time to return if the server is unavailable.

Sample Code

If an archiver is too busy to process connections, you can set a longer timeout by using the following code:

IHU_CONNECTION_PARAMETERS params;
params.Size = sizeof(IHU_CONNECTION_PARAMETERS);
params.TCPConnectionWindow = 30; // extend window to 30s
ihuSetConnectionParameters(&params);
Note: This code applies only to the connections made from your program. You must make this call each time you run your program.

Returns

The ihuSetConnectionParameters function returns the following values:

  • ihuSTATUS_OK
  • ihuSTATUS_FAILED

ihuRestoreDefaultConnectionParameters

Use the ihuRestoreDefaultConnectionParameters function to reset all connection parameters (for example, the socket connection timeout) to default values.

Prototype

ihuRestoreDefaultConnectionParameters {
 void,
};

Remarks

The example code resets the connection timeout to 5 seconds.

Returns

IhuSTATUS_OK

ihuServerRegisterCallbacks

Use the ihuServerRegisterCallbacks function if you want your program to be notified of changes in buffering or connection state. For example, your program can be notified of connection loss or that buffering is full.

Prototype

ihuErrorCode IHUAPI ihuServerRegisterCallbacks (
long hServer,
void *UserParameter,
long *RegisterCallbacksStatus,
void *BufferCallbackFunction,
void *ConnectionCallbackFunction
);

Remarks

The inputs to this function are:

  • hServer: Server handle from the connection. Callbacks are as per server handle, so you can have callbacks for some connections and not for others, or specific callbacks for different handles.
  • UserParameter: NULL or an integer value that you want passed to you in the callback.
  • RegisterCallbacksStatus: Callback setup success or failure.
  • BufferCallbackFunction: Callback function for buffer state changes.
  • ConnectionCallbackFunction: Callback function for connection state changes.

Returns

ihuServerRegisterCallbacks returns the following values:

  • ihuSTATUS_OK
  • ihuSTATUS_FAILED

ihuBrowseCollectors

Use the ihuBrowseCollectors function to browse collectors that are connected to the archiver.

Prototype

ihuErrorCode IHUAPI ihuBrowseCollectors (
long hServer,
MSO Char *InterfaceNameMask
IHU_COLLECTOR **Collectors,
int *NumOfCollectors
);

Remarks

The inputs to the function are:

  • hServer: Server handle for the server to be browsed.
  • *InterfaceNameMask: Pass * for all interfaces, or the interface name or detailed mask for efficiency.

The outputs of the function are:

  • **Collectors: Returns a list of interfaces/collectors.
  • *NumOfCollectors: Returns the number of interfaces found.

Returns

The ihuBrowseCollectors function returns the following values:

  • ihuSTATUS_OK
  • ihuSTATUS_FAILED