[cairo] API: get error message

[Adrian Johnson]

On 11/11/17 20:02, Uli Schlachter wrote:
> On 11.11.2017 09:53, Adrian Johnson wrote:
>> There a number of status types where cairo could report additional
>> information on the error:
> 
> How would such an error message look like?
> 
>>  CAIRO_STATUS_PNG_ERROR
> 
> Looking at cairo-png.c, the extra info here would be the error message
> provided by libpng, I guess? (png_simple_error_callback() in cairo-png.c)
> 
>>  CAIRO_STATUS_FREETYPE_ERROR
> 
> This is a catch-all for most FT_Error values. Does freetype provide its
> own error strings here or do you plan to invent your own descriptions?
> (_ft_to_cairo_error() in cairo-ft-font.c)

Freetype has descriptions available:

https://www.freetype.org/freetype2/docs/reference/ft2-error_code_values.html

> 
>>  CAIRO_STATUS_WIN32_GDI_ERROR
> 
> Heh. :-)
> 
> _cairo_win32_print_gdi_error() currently (as the name implies) just
> prints the error to stderr and then returns this error code. Do you want
> to get rid of this print-to-stderr?

More a case of if we add this function for the other statuses we should
handle GDI as well. We should also be consistent. Either print extra
detail, when available, for all status types to stderr for find some
other way of reporting it.

> 
> Also, the error messages here (specifically: the context argument to the
> above function) seem quite internal to me, mentioning names of static
> functions. What's the exact plan here?

We can only use what windows provides us but any information is better
that none.

> 
>>  CAIRO_STATUS_TAG_ERROR
> 
> This one seems to be purely cairo-internal, so the least of a problem.

It would be helpful to report which tag caused the error or what the
parsing error on the attributes is.

> 
>> Currently the status just tells us something went wrong. With the above
>> status types there could be multiple reasons why it might fail.
>>
>> I'd like to introduce a new function that can retrieve the reason for
>> the failure.
>>
>> const char *
>> cairo_surface_get_error_explanation()
>>
>> Returns NULL if no error explanation available for the current status
>> type (including SUCCESS). The returned string is owned by the surface
>> and will be destroyed when the surface is destroyed.
> 
> Why only for surfaces? For example, the freetype errors likely end up
> being on a font face and the win32 error will most likely be encountered
> on a cairo context.

No reason why it can't be added to other objects. I was keeping it
simple. The status is propagated to the surface.

This is intended make debugging problems easier. There have been
occasions when I needed to set a _cairo_error breakpoint to figure out
why it is failing.

> 
> Uli
>