cfp: Drop unneeded annotation prefix; plural fixes.
[libsigrokdecode.git] / error.c
1 /*
2  * This file is part of the libsigrokdecode project.
3  *
4  * Copyright (C) 2013 Uwe Hermann <uwe@hermann-uwe.de>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, see <http://www.gnu.org/licenses/>.
18  */
19
20 #include <config.h>
21 #include "libsigrokdecode.h"
22
23 /**
24  * @file
25  *
26  * Error handling in libsigrokdecode.
27  */
28
29 /**
30  * @defgroup grp_error Error handling
31  *
32  * Error handling in libsigrokdecode.
33  *
34  * libsigrokdecode functions usually return @ref SRD_OK upon success, or a
35  * negative error code on failure.
36  *
37  * @{
38  */
39
40 /**
41  * Return a human-readable error string for the given libsigrokdecode error
42  * code.
43  *
44  * @param error_code A libsigrokdecode error code number, such as
45  *                   SRD_ERR_MALLOC.
46  *
47  * @return A const string containing a short, human-readable (English)
48  *         description of the error, such as "memory allocation error".
49  *         The string must NOT be free'd by the caller!
50  *
51  * @see srd_strerror_name
52  *
53  * @since 0.2.0
54  */
55 SRD_API const char *srd_strerror(int error_code)
56 {
57         const char *str;
58
59         /*
60          * Note: All defined SRD_* error macros from libsigrokdecode.h must
61          * have an entry in this function, as well as in srd_strerror_name().
62          */
63
64         switch (error_code) {
65         case SRD_OK:
66                 str = "no error";
67                 break;
68         case SRD_ERR:
69                 str = "generic/unspecified error";
70                 break;
71         case SRD_ERR_MALLOC:
72                 str = "memory allocation error";
73                 break;
74         case SRD_ERR_ARG:
75                 str = "invalid argument";
76                 break;
77         case SRD_ERR_BUG:
78                 str = "internal error";
79                 break;
80         case SRD_ERR_PYTHON:
81                 str = "Python API error";
82                 break;
83         case SRD_ERR_DECODERS_DIR:
84                 str = "decoders directory access error";
85                 break;
86         default:
87                 str = "unknown error";
88                 break;
89         }
90
91         return str;
92 }
93
94 /**
95  * Return the "name" string of the given libsigrokdecode error code.
96  *
97  * For example, the "name" of the SRD_ERR_MALLOC error code is
98  * "SRD_ERR_MALLOC", the name of the SRD_OK code is "SRD_OK", and so on.
99  *
100  * This function can be used for various purposes where the "name" string of
101  * a libsigrokdecode error code is useful.
102  *
103  * @param error_code A libsigrokdecode error code number, such as
104  *                   SRD_ERR_MALLOC.
105  *
106  * @return A const string containing the "name" of the error code as string.
107  *         The string must NOT be free'd by the caller!
108  *
109  * @see srd_strerror
110  *
111  * @since 0.2.0
112  */
113 SRD_API const char *srd_strerror_name(int error_code)
114 {
115         const char *str;
116
117         /*
118          * Note: All defined SRD_* error macros from libsigrokdecode.h must
119          * have an entry in this function, as well as in srd_strerror().
120          */
121
122         switch (error_code) {
123         case SRD_OK:
124                 str = "SRD_OK";
125                 break;
126         case SRD_ERR:
127                 str = "SRD_ERR";
128                 break;
129         case SRD_ERR_MALLOC:
130                 str = "SRD_ERR_MALLOC";
131                 break;
132         case SRD_ERR_ARG:
133                 str = "SRD_ERR_ARG";
134                 break;
135         case SRD_ERR_BUG:
136                 str = "SRD_ERR_BUG";
137                 break;
138         case SRD_ERR_PYTHON:
139                 str = "SRD_ERR_PYTHON";
140                 break;
141         case SRD_ERR_DECODERS_DIR:
142                 str = "SRD_ERR_DECODERS_DIR";
143                 break;
144         default:
145                 str = "unknown error code";
146                 break;
147         }
148
149         return str;
150 }
151
152 /** @} */