Instance_Create function

Applies To: Implementing a custom GeoTransformer

Creates an instance of a custom GeoTransformer, initialized upon given arguments. When your custom module implements multiple GeoTransformers, it acts as a factory method and decides which one should be initiated.

This function will be called by GeoTransCore component whenever it needs to create a GeoTransformer implemented in your custom module.

[C / C++]

extern "C" HGeoTrans __stdcall Instance_Create(

const char * szGeoTransDef, // GeoTransformer definition string

GeoTrans_CreationFlags dwFlags // creation flags specifying how it will be used

);

Arguments

[in] szGeoTransDef

An XML formatted string defining the custom GeoTransformer. The root node of the XML structure should contain two attributes: class and version. The rest of the XML document’s content is your choice to define and use as it fits your needs in describing all the parameters that construct your objects.

The class attribute is made of two parts separated by a dot: idModule and idType. The idModule is the filename of your custom module (without the “.dll” file extension), and it tells to GeoTransCore component to load and call your custom module, in order to create your custom GeoTransformer objects. The idType is any identifier string naming a GeoTransformer type supported by your implementation.

The version attribute is used entirely by your implementation in order to support versioning control. We encourage versioning control support for GeoTransformers, since their implementation changes may be completely silent and the use of incompatible version of the input could have catastrophic impact on the results.

Note: It is not required to test against NULL since GeoTransCore component ensures the validity of the pointer.

[in] dwFlags

A flag combination specifying which functionalities are required for this instance. You are supposed to use it as a hint when initializing your objects, because some implementations of GeoTransformers might require a very expensive processing for supporting transformations in both directions.

GeoTrans_CreationFlags type is defined in GeoTransCreation namespace which also enumerates the possible values of this parameter:

If you wish to ignore this parameter, it can be simply declared as DWORD or unsigned int.

Return Value

When a custom GeoTransformer instance is created successfully, return a handle that your implementation can use to identify the instance when GeoTransCore component will pass it back as a parameter. It can be a pointer to a C data structure, an address of a C++ class instance, or anything else that your implementation understands.

HGeoTrans type is defined in GeoTransCreation namespace and it is basically a HANDLE.

Return NULL if  a valid instance could not be created. Following explains how errors and warnings can be reported.

Reporting errors and warnings: Set both error and warning codes by calling SetLastError. GeoTransCore component will call GetLastError to retrieve the code and will treat it as an error if the function also returns NULL, else as a warning. To learn how to provide descriptions for your custom error and warning codes, please see Error_FormatMessage function documentation. GTM_Errors_Warnings namespace enumerates some recommended codes and descriptions to be supported, from which the following would be set by this function:

Remarks

Most likely, an XML parser of your choice will be required to extract the values that are used to initialize custom GeoTransformers. Considering the usual content of a GeoTransformer definition string and its possible large size, a lite XML parser could be the better choice. We do not consider speed of this function’s implementation a critical issue when your custom module supports serialization.

For further details on serialization, please see Instance_Serialize and Instance_UnSerialize.

Exception handling: Usual considerations regarding C / C++ exception handling should be taken, with extra care on memory allocation failures and buffer overrun situations.

Versioning control: We recommend using the 4-number versioning system (1.0.0.0), in which first two numbers (major and minor) are considered critical changes to the content, thus your implementation should refuse to use it. Please upgrade the value of the version attribute within the GeoTransformer definition on every change of its content or its interpretation.

Requirements

Example

For a better understanding of the XML structure given in szGeoTransDef parameter, following shows a sample XML definition of a custom GeoTransformer:

[XML]

<GeoTransDef class="GeoTransModule.CustomGeoTransformer" version="1.0.2.7">

<Info/>

</GeoTransDef>

For a detailed example on how to implement this function, please see Custom GeoTransformer VC++ Sample.

Related Topics

See also: Instance_Discard, Error_FormatMessage, Instance_TryReuseCached, Instance_Serialize, Instance_UnSerialize, GeoTransCreation, GTM_Errors_Warnings