source: trunk/libtransmission/error.h

Last change on this file was 14724, checked in by jordan, 5 years ago

use '#pragma once' instead of #ifndef..#define..#endif guards

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