All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
src/include/aerospike/as_error.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_status.h>
26 
27 #include <stdarg.h>
28 #include <stdint.h>
29 #include <stdio.h>
30 #include <string.h>
31 
32 /******************************************************************************
33  * MACROS
34  *****************************************************************************/
35 
36 /**
37  * The size of as_error.message
38  *
39  * @ingroup as_error_object
40  */
41 #define AS_ERROR_MESSAGE_MAX_SIZE 1024
42 
43 /**
44  * The maximum string length of as_error.message
45  *
46  * @ingroup as_error_object
47  */
48 #define AS_ERROR_MESSAGE_MAX_LEN (AS_ERROR_MESSAGE_MAX_SIZE - 1)
49 
50 /******************************************************************************
51  * TYPES
52  *****************************************************************************/
53 
54 /**
55  * All operations that interact with the Aerospike cluster accept an as_error
56  * argument and return an as_status value. The as_error argument is populated
57  * with information about the error that occurred. The as_status return value
58  * is the as_error.code value.
59  *
60  * When an operation succeeds, the as_error.code value is usually set to
61  * `AEROSPIKE_OK`. There are some operations which may have other success
62  * status codes, so please review each operation for information on status
63  * codes.
64  *
65  * When as_error.code is not a success value (`AEROSPIKE_OK`), then you can
66  * expect the other fields of as_error.code to be populated.
67  *
68  * Example usage:
69  * ~~~~~~~~~~{.c}
70  * as_error err;
71  *
72  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
73  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
74  * }
75  * ~~~~~~~~~~
76  *
77  * You can reuse an as_error with multiple operations. Each operation
78  * internally resets the error. So, if an error occurred in one operation,
79  * and you did not check it, then the error will be lost with subsequent
80  * operations.
81  *
82  * Example usage:
83  *
84  * ~~~~~~~~~~{.c}
85  * as_error err;
86  *
87  * if ( aerospike_key_put(&as, &err, NULL, &key, rec) != AEROSPIKE_OK ) {
88  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
89  * }
90  *
91  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
92  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
93  * }
94  * ~~~~~~~~~~
95  *
96  * @ingroup client_objects
97  */
98 typedef struct as_error_s {
99 
100  /**
101  * Numeric error code
102  */
104 
105  /**
106  * NULL-terminated error message
107  */
109 
110  /**
111  * Name of the function where the error occurred.
112  */
113  const char * func;
114 
115  /**
116  * Name of the file where the error occurred.
117  */
118  const char * file;
119 
120  /**
121  * Line in the file where the error occurred.
122  */
123  uint32_t line;
124 
125 } as_error;
126 
127 /******************************************************************************
128  * MACROS
129  *****************************************************************************/
130 
131 /**
132  * as_error_update(&as->error, AEROSPIKE_OK, "%s %d", "a", 1);
133  *
134  * @ingroup as_error_object
135  */
136 #define as_error_update(__err, __code, __fmt, ...) \
137  as_error_setallv( __err, __code, __func__, __FILE__, __LINE__, __fmt, ##__VA_ARGS__ );
138 
139 /******************************************************************************
140  * FUNCTIONS
141  *****************************************************************************/
142 
143 /**
144  * Initialize the error to default (empty) values, returning the error.
145  *
146  * @param err The error to initialize.
147  *
148  * @returns The initialized err.
149  *
150  * @relates as_error
151  * @ingroup as_error_object
152  */
153 static inline as_error * as_error_init(as_error * err) {
154  err->code = AEROSPIKE_OK;
155  err->message[0] = '\0';
156  err->func = NULL;
157  err->file = NULL;
158  err->line = 0;
159  return err;
160 }
161 
162 /**
163  * Resets the error to default (empty) values, returning the status code.
164  *
165  * @param err The error to reset.
166  *
167  * @returns AEROSPIKE_OK.
168  *
169  * @relates as_error
170  * @ingroup as_error_object
171  */
172 static inline as_status as_error_reset(as_error * err) {
173  err->code = AEROSPIKE_OK;
174  err->message[0] = '\0';
175  err->func = NULL;
176  err->file = NULL;
177  err->line = 0;
178  return err->code;
179 }
180 
181 /**
182  * Sets the error.
183  *
184  * @return The status code set for the error.
185  *
186  * @relates as_error
187  */
188 static inline as_status as_error_setall(as_error * err, as_status code, const char * message, const char * func, const char * file, uint32_t line) {
189  err->code = code;
190  strncpy(err->message, message, AS_ERROR_MESSAGE_MAX_LEN);
191  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
192  err->func = func;
193  err->file = file;
194  err->line = line;
195  return err->code;
196 }
197 
198 /**
199  * Sets the error.
200  *
201  * @return The status code set for the error.
202  *
203  * @relates as_error
204  */
205 static inline as_status as_error_setallv(as_error * err, as_status code, const char * func, const char * file, uint32_t line, const char * fmt, ...) {
206  if ( fmt != NULL ) {
207  va_list ap;
208  va_start(ap, fmt);
209  vsnprintf(err->message, AS_ERROR_MESSAGE_MAX_LEN, fmt, ap);
210  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
211  va_end(ap);
212  }
213  err->code = code;
214  err->func = func;
215  err->file = file;
216  err->line = line;
217  return err->code;
218 }
219 
220 /**
221  * Sets the error message
222  *
223  * @relates as_error
224  */
225 static inline as_status as_error_set(as_error * err, as_status code, const char * fmt, ...) {
226  if ( fmt != NULL ) {
227  va_list ap;
228  va_start(ap, fmt);
229  vsnprintf(err->message, AS_ERROR_MESSAGE_MAX_LEN, fmt, ap);
230  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
231  va_end(ap);
232  }
233  err->code = code;
234  return err->code;
235 }
static as_error * as_error_init(as_error *err)
static as_status as_error_set(as_error *err, as_status code, const char *fmt,...)
static as_status as_error_reset(as_error *err)
#define AS_ERROR_MESSAGE_MAX_SIZE
char message[AS_ERROR_MESSAGE_MAX_SIZE]
#define AS_ERROR_MESSAGE_MAX_LEN
static as_status as_error_setallv(as_error *err, as_status code, const char *func, const char *file, uint32_t line, const char *fmt,...)
static as_status as_error_setall(as_error *err, as_status code, const char *message, const char *func, const char *file, uint32_t line)