[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Error Handling

Many functions in GPGME can return an error if they fail. For this reason, the application should always catch the error condition and take appropriate measures, for example by releasing the resources and passing the error up to the caller, or by displaying a descriptive message to the user and cancelling the operation.

Some error values do not indicate a system error or an error in the operation, but the result of an operation that failed properly. For example, if you try to decrypt a tempered message, the decryption will fail. Another error value actually means that the end of a data buffer or list has been reached. The following descriptions explain what each error message means in general. Some error values have specific meanings if returned by a specific function. Such cases are described in the documentation of those functions.

4.1 Error Values  A list of all error values used.
4.2 Error Strings  How to get a descriptive string from a value.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Error Values

Data type: enum GpgmeError
The GpgmeError type specifies the set of all error values that are used by GPGME. Possible values are:

GPGME_EOF
This value indicates the end of a list, buffer or file.

GPGME_No_Error
This value indicates success. The value of this error is 0.

GPGME_General_Error
This value means that something went wrong, but either there is not enough information about the problem to return a more useful error value, or there is no separate error value for this type of problem.

GPGME_Out_Of_Core
This value means that an out-of-memory condition occurred.

GPGME_Invalid_Value
This value means that some user provided data was out of range. This can also refer to objects. For example, if an empty GpgmeData object was expected, but one containing data was provided, this error value is returned.

GPGME_Busy
This value is returned if you try to start a new operation in a context that is already busy with some earlier operation which was not cancelled or finished yet.

GPGME_No_Request
This value is in some sense the opposite of GPGME_Busy. There is no pending operation, but it is required for the function to succeed.

GPGME_Exec_Error
This value means that an error occurred when trying to spawn a child process.

GPGME_Too_Many_Procs
This value means that there are too many active backend processes.

GPGME_Pipe_Error
This value means that the creation of a pipe failed.

GPGME_No_Recipients
This value means that no valid recipients for a message have been set.

GPGME_Invalid_Recipients
This value means that some, but not all, recipients for a message have been invalid.

GPGME_No_Data
This value means that a GpgmeData object which was expected to have content was found empty.

GPGME_Conflict
This value means that a conflict of some sort occurred.

GPGME_Not_Implemented
This value indicates that the specific function (or operation) is not implemented. This error should never happen. It can only occur if you use certain values or configuration options which do not work, but for which we think that they should work at some later time.

GPGME_Read_Error
This value means that an I/O read operation failed.

GPGME_Write_Error
This value means that an I/O write operation failed.

GPGME_Invalid_Type
This value means that a user provided object was of a wrong or incompatible type. Usually this refers to the type of a GpgmeData object.

GPGME_Invalid_Mode
This value means that a GpgmeData object has an incorrect mode of operation (for example, doesn't support output although it is attempted to use it as an output buffer).

GPGME_File_Error
This value means that a file I/O operation failed. The value of errno contains the system error value.

GPGME_Decryption_Failed
This value indicates that a decryption operation was unsuccessful.

GPGME_No_Passphrase
This value means that the user did not provide a passphrase when requested.

GPGME_Canceled
This value means that the operation was canceled.

GPGME_Invalid_Key
This value means that a key was invalid.

GPGME_Invalid_Engine
This value means that the engine that implements the desired protocol is currently not available. This can either be because the sources were configured to exclude support for this engine, or because the engine is not installed properly.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Error Strings

Function: const char * gpgme_strerror (GpgmeError err)
The function gpgme_strerror returns a pointer to a statically allocated string containing a description of the error with the error value err. This string can be used to output a diagnostic message to the user.

The following example illustrates the use of gpgme_strerror:

 
GpgmeCtx ctx;
GpgmeError err = gpgme_new (&ctx);
if (err)
  {
    fprintf (stderr, "%s: creating GpgME context failed: %s\n",
             argv[0], gpgme_strerror (err));
    exit (1);
  }


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by John Goerzen on November, 21 2002 using texi2html