source: trunk/libtransmission/error.h @ 14299

Last change on this file since 14299 was 14299, checked in by jordan, 7 years ago

mike.dld's portability improvements to libtransmission, pt 1

File size: 5.6 KB
Line 
1/*
2 * This file Copyright (C) 2013-2014 Mnemosyne LLC
3 *
4 * It may be used under the GNU GPL versions 2 or 3
5 * or any future license endorsed by Mnemosyne LLC.
6 *
7 * $Id$
8 */
9
10#ifndef TR_ERROR_H
11#define TR_ERROR_H
12
13#include <stdarg.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19#ifndef TR_GNUC_PRINTF
20 #ifdef __GNUC__
21  #define TR_GNUC_PRINTF(fmt, args) __attribute__ ((format (printf, fmt, args)))
22 #else
23  #define TR_GNUC_PRINTF(fmt, args)
24 #endif
25#endif
26
27/**
28 * @addtogroup error Error reporting
29 * @{
30 */
31
32/** @brief Structure holding error information. */
33typedef struct tr_error
34{
35  /** @brief Error code, platform-specific */
36  int    code;
37  /** @brief Error message */
38  char * message;
39}
40tr_error;
41
42/**
43 * @brief Create new error object using `printf`-style formatting.
44 *
45 * @param[in] code           Error code (platform-specific).
46 * @param[in] message_format Error message format string.
47 * @param[in] ...            Format arguments.
48 *
49 * @return Newly allocated error object on success, `NULL` otherwise.
50 */
51tr_error * tr_error_new                (int           code,
52                                        const char  * message_format,
53                                                      ...) TR_GNUC_PRINTF (2, 3);
54
55/**
56 * @brief Create new error object using literal error message.
57 *
58 * @param[in] code    Error code (platform-specific).
59 * @param[in] message Error message.
60 *
61 * @return Newly allocated error object on success, `NULL` otherwise.
62 */
63tr_error * tr_error_new_literal        (int           code,
64                                        const char  * message);
65
66/**
67 * @brief Create new error object using `vprintf`-style formatting.
68 *
69 * @param[in] code           Error code (platform-specific).
70 * @param[in] message_format Error message format string.
71 * @param[in] args           Format arguments.
72 *
73 * @return Newly allocated error object on success, `NULL` otherwise.
74 */
75tr_error * tr_error_new_valist         (int           code,
76                                        const char  * message_format,
77                                        va_list       args);
78
79/**
80 * @brief Free memory used by error object.
81 *
82 * @param[in] error Error object to be freed.
83 */
84void       tr_error_free               (tr_error    * error);
85
86/**
87 * @brief Create and set new error object using `printf`-style formatting.
88 *
89 * If passed pointer to error object is `NULL`, do nothing.
90 *
91 * @param[in,out] error          Pointer to error object to be set.
92 * @param[in]     code           Error code (platform-specific).
93 * @param[in]     message_format Error message format string.
94 * @param[in]     ...            Format arguments.
95 */
96void       tr_error_set                (tr_error   ** error,
97                                        int           code,
98                                        const char  * message_format,
99                                                      ...) TR_GNUC_PRINTF (3, 4);
100
101/**
102 * @brief Create and set new error object using literal error message.
103 *
104 * If passed pointer to error object is `NULL`, do nothing.
105 *
106 * @param[in,out] error   Pointer to error object to be set.
107 * @param[in]     code    Error code (platform-specific).
108 * @param[in]     message Error message.
109 */
110void       tr_error_set_literal        (tr_error   ** error,
111                                        int           code,
112                                        const char  * message);
113
114/**
115 * @brief Propagate existing error object upwards.
116 *
117 * If passed pointer to new error object is not `NULL`, copy old error object to
118 * new error object and free old error object. Otherwise, just free old error
119 * object.
120 *
121 * @param[in,out] new_error Pointer to error object to be set.
122 * @param[in,out] old_error Error object to be propagated. Cleared on return.
123 */
124void       tr_error_propagate          (tr_error   ** new_error,
125                                        tr_error   ** old_error);
126
127/**
128 * @brief Clear error object.
129 *
130 * Free error object being pointed and set pointer to `NULL`. If passed pointer
131 * is `NULL`, do nothing.
132 *
133 * @param[in,out] error Pointer to error object to be cleared.
134 */
135void       tr_error_clear              (tr_error   ** error);
136
137#if 0
138
139/**
140 * @brief Prefix message of exising error object.
141 *
142 * If passed pointer to error object is not `NULL`, prefix its message with
143 * `printf`-style formatted text. Otherwise, do nothing.
144 *
145 * @param[in,out] error         Pointer to error object to be set.
146 * @param[in]     prefix_format Prefix format string.
147 * @param[in]     ...           Format arguments.
148 */
149void       tr_error_prefix             (tr_error   ** error,
150                                        const char  * prefix_format,
151                                                      ...) TR_GNUC_PRINTF (2, 3);
152
153/**
154 * @brief Prefix message and propagate existing error object upwards.
155 *
156 * If passed pointer to new error object is not `NULL`, copy old error object to
157 * new error object, prefix its message with `printf`-style formatted text, and
158 * free old error object. Otherwise, just free old error object.
159 *
160 * @param[in,out] new_error Pointer to error object to be set.
161 * @param[in,out] old_error     Error object to be propagated. Cleared on return.
162 * @param[in] prefix_format Prefix format string.
163 * @param[in] ... Format arguments.
164 */
165void       tr_error_propagate_prefixed (tr_error   ** new_error,
166                                        tr_error   ** old_error,
167                                        const char  * prefix_format,
168                                                      ...) TR_GNUC_PRINTF (3, 4);
169
170#endif /* 0 */
171
172/** @} */
173
174#ifdef __cplusplus
175}
176#endif
177
178#endif
Note: See TracBrowser for help on using the repository browser.