Error_FormatMessage function

Applies To: Implementing a custom GeoTransformer

Translates custom error / warning codes that were set by your implementation.

When your custom module needs to report an error or a warning, it should call SetLastError to set a code and provide a message description for it in this function. GeoTransCore component will provide a buffer in which to copy the description and will forward it to the calling reporter.

[C / C++]

extern "C" BOOL __stdcall Error_FormatMessage(

DWORD dwMessageId, // error code

char * szMessage, // message buffer

DWORD dwSize // buffer size

);

Arguments

[in] dwMessageId

Error code previously retrieved by calling GetLastError. Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no system error code has this bit set. Use this bit to ensure that custom error codes do not conflict with any error codes defined by the system.

Application-defined error codes

[out] szMessage

Fixed size buffer that will return the formatted message description. Copy your custom description identified by given dwMessageId. Your description must be NULL terminated. Do not overrun this buffer! Maximum number of bytes that can be copied is specified by dwSize parameter.

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

[in] dwSize

Length, in bytes, of szMessage buffer. Your message descriptions should be as short as possible, but still comprehensive. Given buffer has a predefined size and you may face the situation when your description will be truncated when too long. Thus, 2048 is recommended maximum size of your descriptions, including the terminating NULL character.

Return Value

If dwMessageId is not recognized as being set by your implementation, this function should return FALSE. Otherwise, szMessage should return the formatted description for the given error / warning code.

GTM_Errors_Warnings: namespace enumerates some recommended codes and descriptions to be supported.

Remarks

Usually, reporting consists in one predefined message per function call, but there are times when multiple descriptions should be concatenated in a report. For example, reporting missing values in the XML definition of a GeoTransformer could cumulate the names of those missing entries. To achieve this behaviour, define your dwMessageId as a combination of flags, where each bit corresponds with a possible warning. A loop could then test each bit, and when set, will append the appropriate description to the returned message buffer.

Since the number of bits is limited (31 available because bit 29 is always set), cumulating descriptions in one message might require temporary storage. The error / warning code cannot be used anymore as a flag combination, so the message must be constructed within the function setting the code. Later, when the code will be retrieved and your function will be called to provide the description, it should still be available. Do not use static or global variables for such purpose because your implementation must be thread safe, as described below.

Multi-threading: Concurrent calls from different threads can be made to this function. It is expected that its implementation is thread safe. Using SetLastError / GetLastError mechanism ensures that multiple threads do not overwrite each other's codes because are maintained on a per-thread basis. Your implementation should too, so when required, use Thread Local Storage (TLS) for variables shared between functions.

Exception handling: Do not overrun given szMessage buffer. You must return a message description that is NULL terminated.

Requirements

Example

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

Related Topics

See also: Instance_Create, GeoTrans_FromGlobalDirection, GeoTrans_ToGlobalDirection, Instance_TryReuseCached, Instance_Serialize, Instance_UnSerialize, GTM_Errors_Warnings