Discussion:
[cairo] API: get error message
Adrian Johnson
2017-11-11 08:53:15 UTC
Permalink
There a number of status types where cairo could report additional
information on the error:

CAIRO_STATUS_PNG_ERROR
CAIRO_STATUS_FREETYPE_ERROR
CAIRO_STATUS_WIN32_GDI_ERROR
CAIRO_STATUS_TAG_ERROR

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.
--
cairo mailing list
***@cairographics.org
https://lists.cairographic
Uli Schlachter
2017-11-11 09:32:18 UTC
Permalink
Post by Adrian Johnson
There a number of status types where cairo could report additional
How would such an error message look like?
Post by Adrian Johnson
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)
Post by Adrian Johnson
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)
Post by Adrian Johnson
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?

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?
Post by Adrian Johnson
CAIRO_STATUS_TAG_ERROR
This one seems to be purely cairo-internal, so the least of a problem.
Post by Adrian Johnson
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.

Uli
--
"Do you know that books smell like nutmeg or some spice from a foreign
land?"
-- Faber in Fahrenheit 451
--
cairo mailing list
***@cairographics.or
Adrian Johnson
2017-11-11 10:00:27 UTC
Permalink
Post by Uli Schlachter
Post by Adrian Johnson
There a number of status types where cairo could report additional
How would such an error message look like?
Post by Adrian Johnson
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)
Post by Adrian Johnson
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
Post by Uli Schlachter
Post by Adrian Johnson
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.
Post by Uli Schlachter
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.
Post by Uli Schlachter
Post by Adrian Johnson
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.
Post by Uli Schlachter
Post by Adrian Johnson
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.
Post by Uli Schlachter
Uli
--
cairo mailing list
***@cairographics.org
http
Bill Spitzak
2017-11-13 19:33:48 UTC
Permalink
This would be very useful.

It should be called "cairo_xxx_strerror" for consistency with some
other library apis. Not clear what goes in the middle but I don't
think it should say "surface" because the errors are per-context,
right?

Return a null pointer if there is no error.
Post by Adrian Johnson
Post by Uli Schlachter
Post by Adrian Johnson
There a number of status types where cairo could report additional
How would such an error message look like?
Post by Adrian Johnson
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)
Post by Adrian Johnson
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)
https://www.freetype.org/freetype2/docs/reference/ft2-error_code_values.html
Post by Uli Schlachter
Post by Adrian Johnson
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.
Post by Uli Schlachter
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.
Post by Uli Schlachter
Post by Adrian Johnson
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.
Post by Uli Schlachter
Post by Adrian Johnson
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.
Post by Uli Schlachter
Uli
--
cairo mailing list
https://lists.cairographics.org/mailman/listinfo/cairo
--
cairo mailing list
***@cairographics.org
https://lists.cairographi
Adrian Johnson
2017-11-26 10:11:16 UTC
Permalink
Post by Bill Spitzak
This would be very useful.
It should be called "cairo_xxx_strerror" for consistency with some
other library apis. Not clear what goes in the middle but I don't
think it should say "surface" because the errors are per-context,
right?
"strerror" is not consistent with the cairo style of whole words
separated by underscores. Also, strerror() is for converting an error
number to text. We already have cairo_status_to_string() for that purpose.

Based on feedback I propose adding the function for all objects that can
use it: surface, cairo context, and scaled font.

const char *
cairo_surface_get_error_explanation()

const char *
cairo_get_error_explanation()

const char *
cairo_scaled_font_get_error_explanation()

Any alternative suggestions for the "error_explanation" name?
--
cairo mailing list
***@cairographics.org
https://lists.cairographics.org
Uli Schlachter
2017-11-26 10:45:43 UTC
Permalink
On 26.11.2017 11:11, Adrian Johnson wrote:
[...]
Post by Adrian Johnson
const char *
cairo_surface_get_error_explanation()
const char *
cairo_get_error_explanation()
const char *
cairo_scaled_font_get_error_explanation()
Any alternative suggestions for the "error_explanation" name?
error_details?

Cheers,
Uli
--
A normal person is just someone you don't know well enough yet.
- Nettie Wiebe
--
cairo mailing list
***@cairographics.org
https://lists
Petr Kobalíček
2017-11-26 15:57:48 UTC
Permalink
I vote for error_message, seems much more standard than 'explanation' or
'details' to me.
Post by Uli Schlachter
[...]
Post by Adrian Johnson
const char *
cairo_surface_get_error_explanation()
const char *
cairo_get_error_explanation()
const char *
cairo_scaled_font_get_error_explanation()
Any alternative suggestions for the "error_explanation" name?
error_details?
Cheers,
Uli
--
A normal person is just someone you don't know well enough yet.
- Nettie Wiebe
--
cairo mailing list
https://lists.cairographics.org/mailman/listinfo/cairo
Adrian Johnson
2017-11-27 09:17:31 UTC
Permalink
Post by Uli Schlachter
[...]
Post by Adrian Johnson
const char *
cairo_surface_get_error_explanation()
const char *
cairo_get_error_explanation()
const char *
cairo_scaled_font_get_error_explanation()
Any alternative suggestions for the "error_explanation" name?
error_details?
I like this one. So the API will be:

const char *
cairo_surface_get_error_details ()

const char *
cairo_get_error_details ()

const char *
cairo_scaled_font_get_error_details ()
Post by Uli Schlachter
Cheers,
Uli
--
cairo mailing list
***@cairographics.org
https://lists.cairog
Bill Spitzak
2017-11-27 20:10:02 UTC
Permalink
Would prefer "text" or "string" or "message" over "details" to make it
really clear that this is a string that can be printed. "details"
sounds like it is returning a data structure imho.

It also seems like you need one of these for every object that can
return a status, I see the following:

cairo_font_options_status (cairo_font_options_t *options);
cairo_font_face_status (cairo_font_face_t *font_face);
cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
cairo_status (cairo_t *cr);
cairo_surface_status (cairo_surface_t *surface);
cairo_pattern_status (cairo_pattern_t *pattern);
Post by Adrian Johnson
Post by Uli Schlachter
[...]
Post by Adrian Johnson
const char *
cairo_surface_get_error_explanation()
const char *
cairo_get_error_explanation()
const char *
cairo_scaled_font_get_error_explanation()
Any alternative suggestions for the "error_explanation" name?
error_details?
const char *
cairo_surface_get_error_details ()
const char *
cairo_get_error_details ()
const char *
cairo_scaled_font_get_error_details ()
Post by Uli Schlachter
Cheers,
Uli
--
cairo mailing list
https://lists.cairographics.org/mailman/listinfo/cairo
--
cairo mailing list
***@cairographics.org
https://lists.cairographics.org/mailman/listinfo/cair
Loading...