CPLGetLastErrorNo doc does not mention it's GDAL-only

[Mateusz Łoskot]

The documentation of CPL error handling API, functions like CPLGetLastErrorNo, should be updated to explain it can only deals with errors from GDAL or those reported as CPLErr code, but it does not regard errors signaled with OGRErr.

[Even Rouault]

r18748 /trunk/gdal/port/cpl_error.cpp: Improve doc of CPLGetLastErrorNo() and CPLGetLastErrorType() (#3389)

Actually, this isn't GDAL related. It just depends on the last call to CPLError(), which can be made by OGR too.

[Mateusz Łoskot]

Replying to rouault:

It just depends on the last call to CPLError(), which can be made by OGR too.

Thanks for the update, but it does not explain it any better. The question is: considering a function with return type of OGRerr:

Is it guaranteed that if OGRERR_NONE flag is returned, then no CPLErr code other than CE_None has been put on the internal errors stack, meaning no CPLError() call performed?

That's what interests OGR users first. Details of CPL error machinery like how to clear errors with CPLErrorReset() goes next.

[Even Rouault]

"Is it guaranteed that if OGRERR_NONE flag is returned, then no CPLErr code other than CE_None has been put on the internal errors stack, meaning no CPLError() call performed?"

No, I don't think there's any such guarantee. An OGR method could theoretically return OGRERR_NONE but could have emitted a CPLError(CE_Warning, ....) during its execution. So CPLGetLastErrorType() would return CE_Warning. For example, OGRSpatialReference::importFromUSGS() can do that, and many others I guess. OGRERR_xxxx codes are only used as return values.

[Mateusz Łoskot]

Replying to rouault:

OGRERR_xxxx codes are only used as return values.

I agree CE_Warning is a minor issue, but the lack of the guarantee I'm asking about means that CE_Failure may be set and OGRERR_NONE returned at the same time. I don't agree that OGRERR_xxx value is only a return value. From client's perspective, it's a very important value.

To summary, in order to achieve best error handling option, to control application state properly, client should in fact check both error conditions together:

• more common option

OGRErr err = ...;
if (OGRERR_NONE != err || CE_Failure == CPLGetLastErrorNo())
{
   // error
}

• stricter alternative

OGRErr err = ...;
if (OGRERR_NONE != err || CE_None != CPLGetLastErrorNo())
{
   // error
}
}}