C Main API Instance Handles

An instance handle (similar in concept to a file handle) represents a program's access to the API, and distinguishes the program-specific resources and settings used within the API. This identification is necessary for dynamic shared libraries, which may be accessed by several different programs simultaneously. When a program initializes the API by calling EssInit(), an instance handle is returned.

Using the Instance Handle in an Application

An instance handle is declared as type ESS_HINST_T in C programs.

The instance handle must be passed to the EssLogin() call, which returns a context handle, and also to the API terminate function EssTerm() to free any program-specific resources used within the API.

Instance handles may be passed to other programs, child processes, or threads, which can then log in independently of the original using the same API resources and settings. Make sure that all programs, processes or threads using the same instance handle log out before they can terminate the API.

Note:

A thread may require its own instance handle (phInstance) to avoid overwriting another thread's networking status information.