f31f196d53e7e4ea72c4cf074185fea599c60b59
[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, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
19  */
20
21 #include <config.h>
22 #include "libsigrokdecode.h"
23
24 /**
25  * @file
26  *
27  * Error handling in libsigrokdecode.
28  */
29
30 /**
31  * @defgroup grp_error Error handling
32  *
33  * Error handling in libsigrokdecode.
34  *
35  * libsigrokdecode functions usually return @ref SRD_OK upon success, or a
36  * negative error code on failure.
37  *
38  * @{
39  */
40
41 /**
42  * Return a human-readable error string for the given libsigrokdecode error
43  * code.
44  *
45  * @param error_code A libsigrokdecode error code number, such as
46  *                   SRD_ERR_MALLOC.
47  *
48  * @return A const string containing a short, human-readable (English)
49  *         description of the error, such as "memory allocation error".
50  *         The string must NOT be free'd by the caller!
51  *
52  * @see srd_strerror_name
53  *
54  * @since 0.2.0
55  */
56 SRD_API const char *srd_strerror(int error_code)
57 {
58         const char *str;
59
60         /*
61          * Note: All defined SRD_* error macros from libsigrokdecode.h must
62          * have an entry in this function, as well as in srd_strerror_name().
63          */
64
65         switch (error_code) {
66         case SRD_OK:
67                 str = "no error";
68                 break;
69         case SRD_ERR:
70                 str = "generic/unspecified error";
71                 break;
72         case SRD_ERR_MALLOC:
73                 str = "memory allocation error";
74                 break;
75         case SRD_ERR_ARG:
76                 str = "invalid argument";
77                 break;
78         case SRD_ERR_BUG:
79                 str = "internal error";
80                 break;
81         case SRD_ERR_PYTHON:
82                 str = "Python API error";
83                 break;
84         case SRD_ERR_DECODERS_DIR:
85                 str = "decoders directory access error";
86                 break;
87         default:
88                 str = "unknown error";
89                 break;
90         }
91
92         return str;
93 }
94
95 /**
96  * Return the "name" string of the given libsigrokdecode error code.
97  *
98  * For example, the "name" of the SRD_ERR_MALLOC error code is
99  * "SRD_ERR_MALLOC", the name of the SRD_OK code is "SRD_OK", and so on.
100  *
101  * This function can be used for various purposes where the "name" string of
102  * a libsigrokdecode error code is useful.
103  *
104  * @param error_code A libsigrokdecode error code number, such as
105  *                   SRD_ERR_MALLOC.
106  *
107  * @return A const string containing the "name" of the error code as string.
108  *         The string must NOT be free'd by the caller!
109  *
110  * @see srd_strerror
111  *
112  * @since 0.2.0
113  */
114 SRD_API const char *srd_strerror_name(int error_code)
115 {
116         const char *str;
117
118         /*
119          * Note: All defined SRD_* error macros from libsigrokdecode.h must
120          * have an entry in this function, as well as in srd_strerror().
121          */
122
123         switch (error_code) {
124         case SRD_OK:
125                 str = "SRD_OK";
126                 break;
127         case SRD_ERR:
128                 str = "SRD_ERR";
129                 break;
130         case SRD_ERR_MALLOC:
131                 str = "SRD_ERR_MALLOC";
132                 break;
133         case SRD_ERR_ARG:
134                 str = "SRD_ERR_ARG";
135                 break;
136         case SRD_ERR_BUG:
137                 str = "SRD_ERR_BUG";
138                 break;
139         case SRD_ERR_PYTHON:
140                 str = "SRD_ERR_PYTHON";
141                 break;
142         case SRD_ERR_DECODERS_DIR:
143                 str = "SRD_ERR_DECODERS_DIR";
144                 break;
145         default:
146                 str = "unknown error code";
147                 break;
148         }
149
150         return str;
151 }
152
153 /** @} */