Throughout the Spatial+ library, the concept of a handle is prevalent. A handle is a reference to an object that is required by the library, and is not to be manipulated directly by the developer. For example, when the Spatial+ library is initialized, a handle is returned. This handle (or one derived from it by another function) is required for every library function that will be called, except pipDistance.
This approach satisfies the requirements that Precisely had when creating this library:
- The library must be language independent.
- The library must be platform independent.
- The library API must be the same regardless of language or platform.
NOTE: The library does not require you to have any special knowledge about the above requirements. The most important concept to remember is: If a function creates a new handle, then memory or other resources have been allocated by the library. In order to return those resources to the system (for example, to free memory and close files), you must use the appropriate command to terminate the handle when you have completed the task. For example, when importing an object file, you will have two derived handles for the import process. The first handle is for the overall library. The second handle is for the import process. When the import process is complete, you need to terminate both handles.