Task7792

From GNUpdf

Task #7792
Design of the Error Module
State	STARTED
Priority	5
Estimated effort	8ph
Scheduled	01-01-2008
Deadline	02-02-2007
Start
End
Assigned to	gerel
Savannah task

1 Design of the Error Module
- 1.1 Overview
2 Description
3 Context-based Errors
4 References

[edit]

Design of the Error Module

[edit]

Overview

The Error module provides procedures for error reporting to the client as well as for error tracing (via debug messages) to developers. Here we also define status types returned by most procedures (there are exceptions though).

The idea of context-based errors is subject to each module implementation and I'm not sure how to deal with that right now. However I created the section for open discussion.

[edit]

Description

This is the initial API for implementation.

[edit]

Status Types

pdf_status_t: A status variable.

The following constants defines the valid values to be hold in a pdf_status_t variable:

PDF_OK
PDF_ERROR
PDF_EBADDATA
PDF_ENOMEM
PDF_EEOF
PDF_EDIVBYZERO
PDF_ENONODE
PDF_EINVRANGE
PDF_ETEXTENC
PDF_ENOMATCH

This list will grow as we get closer to a mature state of development.

I ask everyone working on some module to help me here. I just added the most general ones by reading the info document. Actually, some of them could be used on different modules, like PDF_EINVRANGE, when dealing with indexes.

[edit]

Error reporting procedures

Function: void pdf_perror (pdf_status_t status, const char *str)

Prints the message corresponding to 'status' to stderr followed by 'str'

Parameters

status

status code

str

a user-defined message

Returns

nothing

Function: void pdf_error (pdf_status_t status, FILE *fd, const char *format, ...)

Prints a message with `fprintf (fd, format, ...)';

if status is nonzero, also prints the corresponding message.

Parameters

status

status/error code

file descriptor open for writing

format

string format for the message

...

format's arguments

Returns

nothing

[edit]

Debugging procedures

For each layer there is a macro procedure defined. The file name and the line number at which the error ocurred is printed to stderr followed by 'message'

Macro: PDF_DEBUG_BASE (message, ...)

Macro: PDF_DEBUG_OBJECT (message, ...)

Macro: PDF_DEBUG_DOCUMENT (message, ...)

Macro: PDF_DEBUG_PAGE (message, ...)

Parameters

message

a 'const char*' string

...

message's arguments

Returns

nothing

An example call would be like:

PDF_DEBUG_BASE("Testing macro '%s' '%d' '%lf'", "string", 7, 10.1);

In case debugging is not enabled these macros should be defined to the null string.

[edit]

Context-based Errors

Since the library will be thread-safe we can't share global variables. To deal with error tracing the idea of a 'context' will be introduced (like other libraries do [1] [2]).

As for the Error Module I think we should only provide a structure for error tracing that later would be part of each object's context, the latter being subject to the module's implementation.

[edit]